# HTML

HTML décrit **ce que contient** une page web : un titre, un paragraphe, un tableau, un lien. Il ne dit ni à quoi cela ressemble, c'est le rôle de [CSS](/web/css), ni comment cela réagit, c'est celui de JavaScript.

## Le problème

L'[API des scores](/reseau/api) renvoie du JSON :

```json
[{"player":"Bob","turns":30},{"player":"Alice","turns":42}]
```

C'est parfait pour un programme, illisible pour un joueur. On veut une page de classement qu'on ouvre dans un navigateur, sans lancer le jeu.

Ce site de documentation est lui-même fait de HTML : chaque fichier `.mdx` est transformé en page HTML par `npm run build`.

## La notion

### Les trois langages du navigateur

<Mermaid
  chart={`flowchart LR
    html[HTML<br/>le contenu et sa structure] --> page([La page affichée])
    css[CSS<br/>l'apparence] --> page
    js[JavaScript<br/>le comportement] --> page`}
/>

| Langage | Répond à | Comparaison avec le jeu |
| --- | --- | --- |
| HTML | Qu'y a-t-il sur la page ? | L'état : la carte, les unités |
| CSS | À quoi cela ressemble-t-il ? | Le rendu : couleurs, positions |
| JavaScript | Que se passe-t-il quand on clique ? | Les règles et les entrées |

Les garder séparés est la même discipline que de séparer les règles du jeu de son affichage.

### Balise, élément, attribut

```html
<a href="regles.html">Lire les règles</a>
```

| Morceau | Nom | Rôle |
| --- | --- | --- |
| `<a ...>` | Balise ouvrante | Début de l'élément |
| `href="regles.html"` | Attribut | Une précision : ici, la destination du lien |
| `Lire les règles` | Contenu | Ce qui est affiché |
| `</a>` | Balise fermante | Fin de l'élément |

Les éléments s'emboîtent les uns dans les autres et forment un **arbre**. Certains n'ont pas de contenu et pas de balise fermante, comme `<img>` ou `<br>`.

## Le squelette d'une page

```html
<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Classement - BestGameOfTheYear</title>
  </head>
  <body>
    <h1>BestGameOfTheYear</h1>
  </body>
</html>
```

| Ligne | Rôle |
| --- | --- |
| `<!doctype html>` | Annonce du HTML moderne |
| `<html lang="fr">` | La racine, avec la langue du contenu |
| `<head>` | Les informations **sur** la page, non affichées |
| `<meta charset="utf-8" />` | L'encodage. Sans lui, les accents peuvent s'afficher de travers |
| `<meta name="viewport" ...>` | Adapte la page à la largeur des téléphones |
| `<title>` | Le texte de l'onglet du navigateur |
| `<body>` | Tout ce qui est affiché |

## Les balises courantes

### Le texte

| Balise | Usage |
| --- | --- |
| `<h1>` à `<h6>` | Titres, du plus important au moins important. Un seul `<h1>` par page |
| `<p>` | Paragraphe |
| `<strong>`, `<em>` | Texte important, texte accentué |
| `<ul>`, `<ol>`, `<li>` | Liste à puces, liste numérotée, élément de liste |
| `<a href="...">` | Lien |
| `<img src="..." alt="...">` | Image. `alt` décrit l'image pour qui ne la voit pas |
| `<code>`, `<pre>` | Code dans une phrase, bloc de code |

### La structure

Ces balises ne changent rien à l'affichage. Elles disent **à quoi sert** chaque partie de la page.

<Mermaid
  chart={`flowchart TB
    body[body] --> header[header<br/>en-tête de la page]
    body --> main[main<br/>le contenu principal]
    body --> footer[footer<br/>pied de page]
    header --> nav[nav<br/>les liens de navigation]
    main --> section[section<br/>une partie avec son titre]`}
/>

On parle de HTML **sémantique** : choisir la balise pour son sens, pas pour son apparence. Trois raisons :

- les lecteurs d'écran, utilisés par les personnes malvoyantes, s'appuient sur ces balises pour se repérer ;
- les moteurs de recherche aussi ;
- le code se relit mieux qu'une pile de `<div>`.

`<div>` et `<span>` existent pour les cas où aucune balise n'a le sens voulu : un bloc ou un bout de texte qu'on veut seulement mettre en forme.

### Les tableaux

Un classement est un tableau de données : c'est la balise à utiliser.

| Balise | Rôle |
| --- | --- |
| `<table>` | Le tableau |
| `<caption>` | Son titre |
| `<thead>`, `<tbody>` | L'en-tête, le corps |
| `<tr>` | Une ligne |
| `<th>` | Une cellule d'en-tête |
| `<td>` | Une cellule de données |

### Les formulaires

```html
<form>
  <label for="player">Nom du joueur</label>
  <input id="player" name="player" type="text" required />
  <button type="submit">Chercher</button>
</form>
```

Chaque champ a un `<label>`, relié par `for` et `id`. Cliquer sur le texte place alors le curseur dans le champ, et un lecteur d'écran sait annoncer à quoi il sert.

## La page du classement

On crée un dossier `web/` à la racine du projet.

```text
web/
├── index.html
└── style.css
```

```html
<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Classement - BestGameOfTheYear</title>
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <header>
      <h1>BestGameOfTheYear</h1>
      <nav>
        <a href="index.html">Classement</a>
        <a href="regles.html">Règles</a>
      </nav>
    </header>

    <main>
      <h2>Classement</h2>
      <p>Les parties gagnées en le moins de tours.</p>

      <table class="scores">
        <caption>Les dix meilleures parties</caption>
        <thead>
          <tr>
            <th scope="col">Rang</th>
            <th scope="col">Joueur</th>
            <th scope="col">Tours</th>
          </tr>
        </thead>
        <tbody>
          <tr class="first">
            <td>1</td>
            <td>Bob</td>
            <td>30</td>
          </tr>
          <tr>
            <td>2</td>
            <td>Alice</td>
            <td>42</td>
          </tr>
        </tbody>
      </table>
    </main>

    <footer>
      <p>Un jeu de stratégie en Python et Pygame.</p>
    </footer>
  </body>
</html>
```

Pour la voir, on la sert avec le [serveur](/reseau/serveur) d'une ligne :

```bash
cd web
python3 -m http.server 8080
```

Puis `http://localhost:8080` dans le navigateur. La page s'affiche sans style, avec l'apparence par défaut du navigateur : c'est normal, et c'est le sujet du cours [CSS](/web/css).

### `class` et `id`

Deux attributs servent à désigner des éléments, pour CSS et JavaScript.

| Attribut | Règle | Exemple |
| --- | --- | --- |
| `class` | Partagé par autant d'éléments qu'on veut | `class="scores"`, `class="first"` |
| `id` | Unique dans la page | `id="player"` |

## Les outils du navigateur

Clic droit sur la page, puis Inspecter. L'onglet des éléments montre l'arbre HTML tel que le navigateur l'a compris, et permet de le modifier en direct. C'est l'équivalent d'un débogueur pour la page.

Le navigateur est tolérant : une balise mal fermée ne provoque pas d'erreur, il devine. Ce qu'il devine n'est pas toujours ce qu'on voulait. Le [validateur du W3C](https://validator.w3.org) signale ces fautes.

## Les limites de cette page

Les scores sont écrits à la main dans le fichier. Pour afficher ceux de l'API, il faut du JavaScript : demander `/scores`, puis construire les lignes du tableau. C'est ce que fait le cours [React](/web/react).

## À retenir

- HTML dit ce qu'est le contenu, pas à quoi il ressemble.
- Choisir la balise pour son sens : `<nav>`, `<main>`, `<table>`, `<button>`.
- Un `<label>` par champ, un `alt` par image, un seul `<h1>`.
- `class` se partage, `id` est unique.
- L'inspecteur du navigateur montre ce qui a réellement été compris.

## Exercices

1. Créer `web/index.html`, le servir, et l'ouvrir. Ajouter trois lignes au classement.
2. Créer `web/regles.html` à partir de la page Les règles de la documentation du jeu : titres, listes, un tableau des unités.
3. Ajouter une image du jeu, prise dans `assets`, avec un `alt` qui la décrit vraiment.
4. Dans l'inspecteur, supprimer la balise `<thead>` et observer ce que cela change. Recharger la page : que constate-t-on ?
5. Passer la page au validateur du W3C et corriger ce qu'il signale.
6. Ouvrir l'inspecteur sur une page de cette documentation. Retrouver `<header>`, `<nav>` et `<main>`.
