Atlas

Mettre une carte Atlas dans votre page

Trois étapes, sans serveur de cartes à monter. Ce guide dit l’essentiel ; le contrat complet (commandes, événements, limites mesurées) est dans la documentation du dépôt.

Étape 1 : charger le composant

Une ligne dans votre page. L’adresse publique suit toujours la dernière version ; pour une version figée, copiez le dossier d’Atlas chez vous et visez-le.

HTML

<script type="module" src="https://nic01asfr.github.io/Widgets-Grist/atlas/lib/bi/atlas-bi-element.js"></script>

Étape 2 : poser la carte

La balise <atlas-bi> reçoit l’adresse d’Atlas, et ce qui décrit votre carte : une charte (couleurs, caractères), des données, éventuellement un manifeste. Chaque morceau s’écrit en bloc dans la page, ou par l’adresse d’un fichier JSON que votre page lit.

Sans manifeste, le composant déduit les couches, les identifiants, la clé métier et les couleurs de vos données, et dit ce qu’il a décidé (événement atlas-bi-configure).

HTML

<atlas-bi src="https://nic01asfr.github.io/Widgets-Grist/atlas/index.html" fond="plan" style="display:block; height:480px">
  <script type="application/json" data-atlas="charte">
    { "version": "atlas-charte/0.1",
      "graines": { "principal": "#b4452c", "secondaire": "#3d6670", "fond": "#faf6ee", "encre": "#2b2118" },
      "texte": { "famille": "serif" } }
  </script>
  <script type="application/json" data-atlas="donnees">
    { "sites": [ { "type": "Feature", "id": 1, "properties": { "nom": "Mairie", "categorie": "Culture" },
                   "geometry": { "type": "Point", "coordinates": [-1.678, 48.113] } } ] }
  </script>
</atlas-bi>

Étape 3 : servir la page

Votre page doit être servie en http ou https, depuis n’importe quel site statique, GitHub Pages compris. Un fichier ouvert directement depuis le disque (file://) n’est pas accepté : Atlas ne répond qu’à une page dont l’origine est déclarée.

L’élément déclare lui-même l’origine de votre page à Atlas (attribut hote pour la changer). Une page qui ne s’est pas déclarée ne reçoit rien : une carte inconnue reste muette.

Les attributs de la balise

Attributs de <atlas-bi>
Attribut	Ce qu’il fait
`src`	L’adresse d’Atlas (obligatoire).
`donnees`, `manifeste`, `charte`	L’adresse d’un fichier JSON que votre page lit (http ou https, 16 Mo au plus), ou un bloc `<script type="application/json" data-atlas="…">` : l’un ou l’autre, jamais les deux.
`charte="herite"`	La carte prend les couleurs et la famille de caractères de votre page.
`fond`	`atlas`, `voile`, `uni`, `plan`, `plan-ign` ou `photo`.
`base="aucune"`	Aucun fond de carte ni service extérieur au démarrage (avec `fond="uni"`). Sans cet attribut, le fond vient d’OpenFreeMap.
`cadrage="aucun"`	Garde la caméra par défaut au lieu de cadrer la carte sur vos données.
`profil="complet"`	L’application entière (rail, panneaux, 3D) au lieu de la carte seule.
`evenements-api`	Fait remonter aussi l’effet de vos propres commandes.
`ratio-max`	Plafonne la finesse de dessin sur un écran à fort ratio de pixels (de 1 à 4).

Piloter la carte

Chaque commande est une promesse : elle se résout par l’accusé de la carte, ou se rejette avec une erreur. batch envoie jusqu’à 100 ordres en un aller-retour. Les gestes de la personne reviennent comme des événements : atlas-bi-select, atlas-bi-hover, atlas-bi-filter, atlas-bi-camera, atlas-bi-time, atlas-bi-erreur.

C’est votre page qui détient l’état (filtres, sélection, temps) : la carte l’applique, le dessine et vous le dit.

JavaScript

const carte = document.querySelector('atlas-bi');
await carte.setScene(manifeste, donnees);              // les commandes attendent la connexion
carte.addEventListener('atlas-bi-select', (e) => ouvrirFiche(e.detail.charge.key));
await carte.setFilter('f-type', ['a', 'b']);           // l'hôte détient les filtres

Les commandes du socle
Commande	Ce qu’elle fait
`setScene`	Pose les couches, la légende, les contrôles ; `fusion: true` ne remplace que les couches listées.
`setFilter`, `setLayerVisibility`	Applique l’état complet d’un contrôle ; montre ou masque une couche.
`select`, `highlight`	Sélectionne un objet par son identifiant ; entoure plusieurs objets.
`flyTo`, `fitTo`	Déplace la caméra ; cadre sur une couche ou des objets.
`setTheme`, `setFond`, `getTheme`	Applique une charte, change le fond de carte, relit le thème mesuré.
`getLegend`, `getRows`	Lit la légende ou les lignes affichées.
`setTime`, `play`, `pause`	Pilote la dimension de temps (une carte de chaleur qui avance, par exemple).

Ce qu’il faut savoir

Au-delà de 100 000 objets par couche, agrégez avant d’envoyer (hexagones, grille ou unités administratives).
Le composant n’utilise que des polices du système : une police propre à votre site est ramenée à la famille la plus proche.
La carte ne se rafraîchit pas seule : votre page renvoie ses données quand elles changent.
Les fichiers que votre page lit doivent en autoriser la lecture (CORS) s’ils sont hébergés ailleurs.
Ce qui n’est pas un contrat : l’adresse publique suit la dernière version. Les hôtes qui veulent une version figée copient le dossier.

Aller plus loin

Essayer l’atelier de style Voir une application alimentée en direct Le guide complet du développeur Le contrat de la carte (commandes et événements)