IGSN Map

Plugin WordPress qui affiche sur une carte les échantillons publiés dans un catalogue IGSN (par défaut https://igsn.cnrs.fr), via un bloc « Carte IGSN » ou le shortcode [igsn_map].

Ce fichier s'adresse aux développeurs. La documentation pour les utilisateurs du plugin est dans readme.txt.

Démarrer

Le dépôt contient un devcontainer avec WordPress, MariaDB, WP-CLI, Node et Xdebug.

1. Ouvrez le dépôt dans VS Code, puis « Reopen in Container ».
2. Attendez la fin de .devcontainer/setup.sh : il installe WordPress et active le plugin.
3. Ouvrez http://localhost:8000 (administration : admin / admin).

Le dépôt est monté dans wp-content/plugins/wordpress-igsn-map : une modification de fichier se voit au rechargement de la page.

WP_DEBUG et SCRIPT_DEBUG sont activés, et les erreurs PHP sont aussi écrites dans wp-content/debug.log. Pour déboguer le PHP, lancez la configuration « Écouter Xdebug » de VS Code (port 9003).

Pour tester rapidement, créez une page contenant une carte :

wp post create --post_type=page --post_status=publish --post_title="Carte" --post_content='<!-- wp:igsn-map/map /-->'

Organisation du code

Il n'y a pas d'étape de build : les fichiers du dépôt sont ceux qui sont livrés.

Les bibliothèques (Leaflet, MapLibre GL, maplibre-gl-leaflet, Supercluster) sont chargées depuis jsDelivr. Leurs versions sont fixées par les constantes IGSN_MAP_*_VERSION en tête de igsn-map.php. MapLibre doit rester en 5.x : la 6 n'est publiée qu'en module ES, sans la globale maplibregl dont maplibre-gl-leaflet a besoin.

Fonctionnement

Rendu d'une carte

Le bloc et le shortcode produisent le même HTML : igsn_map_render_block() convertit les attributs du bloc et appelle igsn_map_render_shortcode(). Celle-ci charge les scripts et renvoie un simple div :

<div class="igsn-map" style="height:500px" data-lat="20" data-lng="0" data-zoom="2"
     data-filters='{"affiliationLaboratory":"UMR6524"}'></div>

Dans le navigateur, igsn-map.js crée une carte Leaflet dans chaque .igsn-map.

Le bloc est rendu côté serveur (save renvoie null). Le contenu enregistré ne contient donc que le commentaire du bloc et ses attributs, et une modification du rendu s'applique aux pages existantes sans les réenregistrer.

Fond de carte

Il est réglable dans Réglages > IGSN Map (options igsn_map_tiles_url et igsn_map_tiles_attribution), lu par igsn_map_tiles() et transmis au JavaScript dans igsnMapConfig.tiles. addBaseLayer() choisit le rendu selon l'URL :

• une URL contenant {z} est un modèle de tuiles raster, affiché par L.tileLayer ;
• toute autre URL est un style MapLibre (tuiles vectorielles), rendu par MapLibre GL dans une couche Leaflet (maplibre-gl-leaflet). latinLabelsOnly() modifie le style au chargement pour n'afficher que les noms de lieux en alphabet latin, comme sur le site IGSN.

Par défaut, c'est le même fond que sur le site IGSN : le style vectoriel OpenFreeMap « liberty » (IGSN_MAP_DEFAULT_TILES_URL), avec son attribution. L'attribution réglée n'est utilisée qu'avec une URL réglée.

MapLibre a besoin de WebGL. Sans WebGL, la création de la couche lève une erreur et la carte entière échoue, échantillons compris. Les tuiles raster n'ont pas cette limite.

Échantillons

La carte appelle une seule fois GET {URL du site}/api/service/samples/map, avec les filtres de data-filters en paramètres. L'API renvoie une FeatureCollection GeoJSON de points (igsn, name) et ne fait aucun regroupement.

Les points sont indexés avec Supercluster. À chaque moveend, renderSamples() ne dessine que les groupes et les points visibles. Le chargement n'a lieu qu'une fois : déplacer ou zoomer la carte n'envoie aucune requête.

Supercluster est réglé avec extent: 256 car Leaflet utilise des tuiles de 256 pixels (la valeur par défaut, 512, ferait se chevaucher les groupes).

Ordre de grandeur : sans filtre, l'API renvoie environ 500 000 points, soit 16 Mo compressés, et l'affichage prend une vingtaine de secondes. Avec un filtre, c'est quasi immédiat.

Le nom d'un échantillon peut contenir du balisage : il est toujours inséré comme texte (textContent), jamais comme HTML.

Couleurs

Les couleurs des pastilles (fond et nombre, pour moins de 100, moins de 10 000, 10 000 échantillons ou plus) et des échantillons seuls sont réglables dans Réglages > IGSN Map (option igsn_map_colors, valeurs par défaut dans IGSN_MAP_DEFAULT_COLORS). Le PHP les transmet au JavaScript dans igsnMapConfig.colors. applyColors() les pose en variables CSS sur chaque carte (--igsn-map-small, --igsn-map-small-text, --igsn-map-medium, --igsn-map-medium-text, --igsn-map-large, --igsn-map-large-text, --igsn-map-sample : les _ des clés deviennent des -), et igsn-map.css les utilise.

Les réglages couvrent les besoins courants. Pour un cas plus poussé (taille, police, ombre…), un thème peut surcharger les classes .igsn-map-cluster, .igsn-map-cluster--small, --medium, --large et .igsn-map-sample. La feuille de style du plugin est chargée en pied de page, donc après celle du thème : préfixez les sélecteurs pour qu'ils l'emportent, par exemple body .igsn-map .igsn-map-cluster--small { background: … }.

URL du site IGSN

Elle est réglable dans Réglages > IGSN Map (option igsn_map_base_url) et lue par igsn_map_base_url(). Laissée vide, elle dépend de l'environnement WordPress (wp_get_environment_type(), voir igsn_map_default_base_url()) :

• local ou development : https://igsn.insu.fr, le site de développement. C'est le cas du devcontainer (WP_ENVIRONMENT_TYPE vaut local dans compose.yml) ;
• staging ou production (valeur par défaut de WordPress) : https://igsn.cnrs.fr, le site de production.

Les réglages vides sont enregistrés tels quels, et non remplacés par la valeur par défaut : un site garde ainsi l'URL de son environnement.

Elle sert à trois choses :

• l'API des échantillons : {URL}/api/service/samples/map ;
• les liens « Voir la fiche » : {URL}/samples/{igsn} ;
• les listes du bloc (voir ci-dessous).

Le PHP la transmet au JavaScript dans window.igsnMapConfig, avec le fond de carte et les textes traduisibles affichés sur la carte.

Listes du bloc

Le bloc propose des listes de laboratoires, OSU, organismes et groupes d'échantillons. Les routes de l'API qui les fournissent (/laboratories, /osus, /organizations, /manual-groups) n'envoient pas d'en-tête CORS : l'éditeur ne peut pas les appeler directement.

La route REST GET /wp-json/igsn-map/v1/lookups (igsn_map_rest_lookups()) les lit côté serveur et les renvoie sous la forme { laboratories: [{ value, label }], osus: [...], organizations: [...], manualGroups: [...] }. Elle est réservée aux utilisateurs ayant le droit edit_posts.

Le résultat est gardé 12 heures dans un transient dont le nom dépend de l'URL du site IGSN. Pour forcer le rechargement :

wp transient delete --all

Filtres

Les filtres acceptés sont listés dans la constante IGSN_MAP_FILTERS. Ils reprennent les noms des paramètres de l'API (documentation : https://igsn.cnrs.fr/api/service/docs).

WordPress met en minuscules les noms d'attributs des shortcodes : igsn_map_render_shortcode() retrouve le nom attendu par l'API à partir de sa version en minuscules.

Pour ajouter un filtre :

• au shortcode : ajoutez son nom à IGSN_MAP_FILTERS ;
• au bloc : ajoutez aussi l'attribut dans block.json, puis le champ correspondant dans SamplesPanel (igsn-map-block.js). igsn_map_render_block() transmet automatiquement tout attribut dont le nom figure dans IGSN_MAP_FILTERS.

Mettez ensuite à jour la section « Tous les critères » de readme.txt.

API JavaScript

Chaque carte expose ses objets sur son élément et y déclenche deux événements :

document.querySelector( '.igsn-map' ).addEventListener( 'igsn-map:loaded', ( event ) => {
    const { map, samples, features } = event.detail;
    console.log( `${ features.length } échantillons affichés` );
} );

• el.igsnMap : { map, samples }, la carte Leaflet et la couche des échantillons ;
• igsn-map:ready : la carte est créée, les échantillons ne sont pas encore chargés ;
• igsn-map:loaded : les échantillons sont affichés. event.detail.features contient les points GeoJSON.

Ces événements sont déclenchés pendant le chargement de la page : enregistrez vos écouteurs dans un script chargé avant igsn-map.js, par exemple en le déclarant comme dépendance.

Conventions

• Code PHP et JavaScript au format WordPress (tabulations, espaces dans les parenthèses).
• Commentaires et textes en français. Les textes visibles passent par les fonctions de traduction avec le domaine igsn-map (__() en PHP, wp.i18n.__() dans le bloc).
• PHP 8.1 minimum, WordPress 6.5 minimum.

Publier une version

1. Mettez le même numéro de version dans l'en-tête Version: et la constante IGSN_MAP_VERSION de igsn-map.php, et dans Stable tag: de readme.txt.
2. Complétez la section == Changelog == de readme.txt.
3. Poussez un tag v suivi du numéro, par exemple v0.2.0.

Le workflow release.yml vérifie que les numéros correspondent au tag, construit igsn-map-x.y.z.zip avec git archive et crée la release GitHub. Les fichiers de développement (.devcontainer, .github, .vscode, ce README…) sont exclus de l'archive par .gitattributes.