GeoLeaf — Configuration des plugins dans un profil

Version : 2.1.5 Dernière mise à jour : avril 2026

Vue d'ensemble

Certaines clés de configuration dans profile.json et ui.json n'ont d'effet que lorsque le plugin correspondant est chargé. Sans le plugin, la clé est lue sans erreur et ignorée silencieusement. Cette conception permet de définir les configurations à l'avance et de charger les plugins optionnellement selon l'environnement.

Clé de profil	Plugin requis	Effet quand le plugin est chargé
`ui.showCacheButton`	`@geoleaf-plugins/storage`	Affiche le bouton de gestion du cache offline
`ui.showAddPoi`	`@geoleaf-plugins/addpoi`	Affiche le bouton d'ajout de POI
`storage`	`@geoleaf-plugins/storage`	Configure le cache offline (tiles, profil)
`poiAddConfig`	`@geoleaf-plugins/addpoi`	Configure le formulaire d'ajout de POI
(aucune clé)	`@geoleaf/connector`	Intercepteur fetch — auto-activé à l'import
(aucune clé)	`@geoleaf-plugins/file-import`	Active l'API `GeoLeaf.FileImport.*`
(aucune clé)	`@geoleaf-plugins/flatgeobuf`	Active l'API `GeoLeaf.FlatGeobuf.*`
(aucune clé)	`@geoleaf-plugins/cog`	Active l'API `GeoLeaf.COG.*`
(aucune clé)	`@geoleaf-plugins/websocket`	Flux temps réel POI via WebSocket (roadmap)
(aucune clé)	`@geoleaf-plugins/realtime-layer`	Couches à rafraîchissement automatique (roadmap)

Note : @geoleaf-plugins/storage, @geoleaf-plugins/addpoi et @geoleaf-plugins/cog sont des plugins commerciaux distribués via npm.pkg.github.com. @geoleaf/connector, @geoleaf-plugins/file-import et @geoleaf-plugins/flatgeobuf sont MIT et distribués via npmjs.org.

Plugin Storage — `@geoleaf-plugins/storage`

Activer le bouton cache

Dans ui.json → section ui :

json

{
    "ui": {
        "showCacheButton": true
    }
}

Sans ce flag à true, le bouton n'apparaît pas même si le plugin est chargé.

Bloc `storage` dans `profile.json`

Configure le comportement du cache offline :

json

{
    "storage": {
        "enableOfflineDetector": true,
        "enableServiceWorker": false,
        "cache": {
            "enableProfileCache": true,
            "enableTileCache": true
        }
    }
}

Clé	Type	Défaut	Description
`enableOfflineDetector`	boolean	`false`	Surveille la connectivité réseau et affiche un indicateur offline
`enableServiceWorker`	boolean	`false`	Active la mise en cache via Service Worker (complémentaire à IndexedDB)
`cache.enableProfileCache`	boolean	`true`	Met en cache les fichiers du profil (JSON de config, taxonomie, etc.)
`cache.enableTileCache`	boolean	`true`	Met en cache les tuiles cartographiques (raster + vecteur)

Cache par couche (dans `basemaps.json`)

La configuration du cache peut être affinée au niveau de chaque fond de carte :

json

{
    "basemaps": {
        "osm": {
            "label": "OpenStreetMap",
            "type": "tile",
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
            "offline": true,
            "cacheMinZoom": 8,
            "cacheMaxZoom": 16,
            "offlineBounds": {
                "north": 48.9,
                "south": 48.8,
                "east": 2.4,
                "west": 2.3
            }
        }
    }
}

Clé	Description
`offline`	Autorise la mise en cache offline pour ce fond de carte
`cacheMinZoom`	Niveau de zoom minimum à précharger
`cacheMaxZoom`	Niveau de zoom maximum à précharger
`offlineBounds`	Emprise géographique à mettre en cache (`north`, `south`, `east`, `west`)

Plugin AddPOI — `@geoleaf-plugins/addpoi`

Activer le bouton d'ajout

Dans ui.json → section ui :

json

{
    "ui": {
        "showAddPoi": true
    }
}

Bloc `poiAddConfig` dans `profile.json`

Configure le comportement du formulaire d'ajout de POI :

json

{
    "poiAddConfig": {
        "enabled": true,
        "defaultPosition": "geolocation"
    }
}

Clé	Type	Valeurs	Description
`enabled`	boolean	`true` / `false`	Active ou désactive la fonctionnalité d'ajout
`defaultPosition`	string	`"geolocation"` / `"center"`	Position initiale du nouveau POI : position GPS de l'utilisateur ou centre de la carte

Configuration avancée : Le formulaire d'ajout, les champs personnalisés et l'endpoint d'envoi sont configurés directement dans le plugin. Voir la documentation @geoleaf-plugins/addpoi pour les options complètes.

Plugin Connector — `@geoleaf/connector`

Licence : MIT | Registre : npmjs.org | Statut : Disponible

@geoleaf/connector est un intercepteur fetch universel qui ajoute automatiquement les headers d'authentification (Bearer token, API key, cookie) aux requêtes vers les sources de données GeoLeaf. Il ne nécessite aucune clé de profile.json — il s'active dès qu'il est importé.

Installation

bash

npm install @geoleaf/connector

Utilisation

import "@geoleaf/core";
import "@geoleaf/connector"; // intercepteur actif immédiatement

// Configurer l'authentification pour une source
GeoLeaf.Connector.configure({
  baseUrl: "https://api.example.com",
  auth: {
    type: "bearer",
    token: () => localStorage.getItem("access_token"),
  },
});

Paramètres de configuration

Paramètre	Type	Description
`baseUrl`	string	URL de base à intercepter
`auth.type`	string	`"bearer"` / `"apikey"` / `"cookie"`
`auth.token`	string/fn	Token statique ou fonction retournant le token dynamiquement
`auth.headerName`	string	Nom du header (défaut : `"Authorization"` pour bearer, configurable)

L'option auth.token accepte une valeur statique ou une fonction synchrone/asynchrone — utile pour les tokens à renouvellement automatique.

Plugin File Import — `@geoleaf-plugins/file-import`

Licence : MIT | Registre : npmjs.org | Statut : Disponible (~70 KB gzip)

Permet l'import de fichiers géographiques côté client (GPX, KML/KMZ, CSV, TopoJSON) et leur conversion en GeoJSON. Les données importées peuvent être affichées directement comme couche sur la carte.

Installation

bash

npm install @geoleaf-plugins/file-import

API principale

import "@geoleaf/core";
import "@geoleaf-plugins/file-import";

// Convertir un fichier File en GeoJSON
const geojson = await GeoLeaf.FileImport.convert(file, {
  type: "auto", // détection automatique — ou "gpx", "kml", "csv", "topojson"
});

// Importer et afficher comme couche sur la carte
const layer = await GeoLeaf.FileImport.importAsLayer(file, {
  layerId: "imported-data",
  style: { color: "#e74c3c", weight: 2 },
});

Formats supportés

Format	Extension	Notes
GPX	`.gpx`	Tracks, routes, waypoints → GeoJSON
KML/KMZ	`.kml`, `.kmz`	KMZ décompressé automatiquement
CSV	`.csv`	Colonnes lat/lon configurables
TopoJSON	`.json`, `.topojson`	Conversion automatique → GeoJSON

Options `importAsLayer`

Option	Type	Défaut	Description
`layerId`	string	généré	Identifiant de la couche résultante
`style`	object	défaut	Style MapLibre GL JS appliqué à la couche
`type`	string	`"auto"`	Force le format (`"gpx"`, `"kml"`, `"csv"`, etc.)

Plugin FlatGeobuf — `@geoleaf-plugins/flatgeobuf`

Licence : MIT | Registre : npmjs.org | Statut : Disponible (~20 KB gzip)

Chargement streaming de fichiers FlatGeobuf avec filtrage spatial par bounding-box (HTTP Range + index R-tree). Idéal pour des jeux de données volumineux sans serveur intermédiaire.

Installation

bash

npm install @geoleaf-plugins/flatgeobuf

API principale

import "@geoleaf/core";
import "@geoleaf-plugins/flatgeobuf";

// Chargement complet
const geojson = await GeoLeaf.FlatGeobuf.load("https://example.com/data.fgb");

// Chargement par bbox (HTTP Range — seules les features dans la bbox sont téléchargées)
const geojson = await GeoLeaf.FlatGeobuf.loadBbox(
  "https://example.com/data.fgb",
  { minX: 2.2, minY: 48.8, maxX: 2.5, maxY: 49.0 }
);

Configuration de source dans `layers.json`

json

{
  "layers": {
    "ma-couche-fgb": {
      "label": "Données terrain",
      "type": "flatgeobuf",
      "url": "https://cdn.example.com/data.fgb",
      "bbox": true
    }
  }
}

Clé	Type	Défaut	Description
`url`	string	—	URL du fichier `.fgb` (HTTPS, supporte CORS)
`bbox`	boolean	`false`	Active le chargement partiel via HTTP Range + R-tree

Plugin COG — `@geoleaf-plugins/cog`

Licence : Commercial | Registre : npm.pkg.github.com | Statut : Disponible (~156 KB gzip)

Lecture et affichage de Cloud Optimized GeoTIFF (COG) directement dans MapLibre GL JS. Supporte les images multi-bandes, les colorMaps LUT et l'injection de source raster personnalisée.

Installation

bash

# Accès restreint — npm.pkg.github.com (token GitHub requis)
npm install @geoleaf-plugins/cog

API principale

import "@geoleaf/core";
import "@geoleaf-plugins/cog";

// Ajouter une couche COG sur la carte
await GeoLeaf.COG.addLayer("https://example.com/ortho.tif", {
  layerId: "ortho",
  bands: [1, 2, 3],
  colorMap: "viridis",
  opacity: 0.85,
});

// Supprimer la couche
GeoLeaf.COG.removeLayer("ortho");

Options `addLayer`

Option	Type	Défaut	Description
`layerId`	string	généré	Identifiant de la couche MapLibre
`bands`	number[]	`[1,2,3]`	Bandes raster à afficher (RGB)
`colorMap`	string	`null`	LUT : `"viridis"`, `"gray"`, `"rdbu"`, etc.
`opacity`	number	`1`	Opacité de la couche (0–1)
`nodata`	number	`null`	Valeur nodata à masquer

Plugin WebSocket — `@geoleaf-plugins/websocket`

Statut : Roadmap Q3 2026 — Plugin MIT prévu pour le suivi POI en temps réel.

Ce plugin permettra la mise à jour en temps réel des POI via WebSocket — positions live, alertes géographiques, flux IoT. La documentation de configuration sera disponible à la release.

Plugin Realtime Layer — `@geoleaf-plugins/realtime-layer`

Statut : Roadmap Q3 2026 — Plugin MIT pour les couches à rafraîchissement automatique.

Ce plugin permettra de définir dans layers.json des couches avec intervalle de rafraîchissement automatique (polling HTTP ou flux WebSocket). La documentation de configuration sera disponible à la release.

Exemple : profil avec les deux plugins activés

`profile.json`

json

{
    "id": "mon-profil",
    "label": "Mon Profil",
    "version": "1.0.0",

    "map": {
        "center": [48.8566, 2.3522],
        "zoom": 12
    },

    "Files": {
        "taxonomyFile": "taxonomy.json",
        "layersFile": "layers.json",
        "basemapsFile": "basemaps.json",
        "uiFile": "ui.json"
    },

    "clusteringConfig": {
        "enabled": true,
        "strategy": "by-layer",
        "maxClusterRadius": 80,
        "disableClusteringAtZoom": 16
    },

    "storage": {
        "enableOfflineDetector": true,
        "enableServiceWorker": false,
        "cache": {
            "enableProfileCache": true,
            "enableTileCache": true
        }
    },

    "poiAddConfig": {
        "enabled": true,
        "defaultPosition": "geolocation"
    }
}

`ui.json`

json

{
    "ui": {
        "theme": "auto",
        "language": "fr",
        "showLayerManager": true,
        "showFilterPanel": true,
        "showLegend": true,
        "showTable": true,
        "showThemeSelector": true,
        "enableGeolocation": true,
        "showCacheButton": true,
        "showAddPoi": true,
        "permalink": {
            "enabled": true,
            "mode": "hash"
        }
    },
    "search": {
        "title": "Filtrer",
        "searchPlaceholder": "Rechercher...",
        "filters": [
            {
                "id": "searchText",
                "type": "search",
                "label": "Recherche textuelle",
                "placeholder": "Nom...",
                "searchFields": ["properties.name"]
            }
        ]
    }
}

Chargement des plugins (ESM)

import "@geoleaf/core";
import "@geoleaf/connector"; // optionnel — si API auth requise
import "@geoleaf-plugins/storage"; // débloque showCacheButton + storage.*
import "@geoleaf-plugins/addpoi"; // débloque showAddPoi + poiAddConfig.*

GeoLeaf.init({
    map: { target: "map" },
    data: {
        activeProfile: "mon-profil",
        profilesBasePath: "./profiles/",
    },
});
GeoLeaf.boot();

Ordre d'import : les plugins doivent être importés après @geoleaf/core. Voir PLUGIN_DEVELOPMENT_GUIDE.md → section "Ordre de chargement".

Règle fondamentale : dégradation silencieuse

Les clés storage, poiAddConfig, showCacheButton et showAddPoi sont toujours valides dans le schéma de configuration de GeoLeaf. Les plugins sans clé de profil (connector, file-import, flatgeobuf, cog) ne nécessitent aucune configuration JSON — ils s'activent dès l'import. Si le plugin correspondant n'est pas chargé :

Aucune erreur n'est levée
La clé est lue et ignorée
Le bouton ou la fonctionnalité n'apparaît pas

Ce comportement est intentionnel : il permet de maintenir un profil unique pour différents environnements (avec ou sans plugins commerciaux).

Vérifier l'état des plugins au runtime

// Liste des plugins chargés
GeoLeaf.PluginRegistry.getLoadedPlugins();
// → ["core", "connector", "storage", "addpoi", "file-import", "flatgeobuf", "cog"]

// Vérifier un plugin spécifique
GeoLeaf.PluginRegistry.isLoaded("storage");     // → true / false
GeoLeaf.PluginRegistry.isLoaded("file-import");  // → true / false
GeoLeaf.PluginRegistry.isLoaded("flatgeobuf");   // → true / false
GeoLeaf.PluginRegistry.isLoaded("cog");          // → true / false

Voir aussi

PLUGIN_DEVELOPMENT_GUIDE.md — développer un plugin custom
CONNECTOR_GUIDE.md — authentification HTTP avec @geoleaf/connector
PROFILES_GUIDE.md — structure complète d'un profil
config/POI_CONFIG.md — configuration détaillée du clustering POI
ui/PERMALINK.md — configuration du permalink
GETTING_STARTED.html — guide de démarrage rapide

GeoLeaf — Configuration des plugins dans un profil ​

Vue d'ensemble ​

Plugin Storage — @geoleaf-plugins/storage ​

Activer le bouton cache ​

Bloc storage dans profile.json ​

Cache par couche (dans basemaps.json) ​

Plugin AddPOI — @geoleaf-plugins/addpoi ​

Activer le bouton d'ajout ​

Bloc poiAddConfig dans profile.json ​

Plugin Connector — @geoleaf/connector ​

Installation ​

Utilisation ​

Paramètres de configuration ​

Plugin File Import — @geoleaf-plugins/file-import ​

Installation ​

API principale ​

Formats supportés ​

Options importAsLayer ​

Plugin FlatGeobuf — @geoleaf-plugins/flatgeobuf ​

Installation ​

API principale ​

Configuration de source dans layers.json ​

Plugin COG — @geoleaf-plugins/cog ​

Installation ​

API principale ​

Options addLayer ​

Plugin WebSocket — @geoleaf-plugins/websocket ​

Plugin Realtime Layer — @geoleaf-plugins/realtime-layer ​

Exemple : profil avec les deux plugins activés ​

profile.json ​

ui.json ​

Chargement des plugins (ESM) ​

Règle fondamentale : dégradation silencieuse ​

Vérifier l'état des plugins au runtime ​

Voir aussi ​

GeoLeaf — Configuration des plugins dans un profil

Vue d'ensemble

Plugin Storage — `@geoleaf-plugins/storage`

Activer le bouton cache

Bloc `storage` dans `profile.json`

Cache par couche (dans `basemaps.json`)

Plugin AddPOI — `@geoleaf-plugins/addpoi`

Activer le bouton d'ajout

Bloc `poiAddConfig` dans `profile.json`

Plugin Connector — `@geoleaf/connector`

Installation

Utilisation

Paramètres de configuration

Plugin File Import — `@geoleaf-plugins/file-import`

Installation

API principale

Formats supportés

Options `importAsLayer`

Plugin FlatGeobuf — `@geoleaf-plugins/flatgeobuf`

Installation

API principale

Configuration de source dans `layers.json`

Plugin COG — `@geoleaf-plugins/cog`

Installation

API principale

Options `addLayer`

Plugin WebSocket — `@geoleaf-plugins/websocket`

Plugin Realtime Layer — `@geoleaf-plugins/realtime-layer`

Exemple : profil avec les deux plugins activés

`profile.json`

`ui.json`

Chargement des plugins (ESM)

Règle fondamentale : dégradation silencieuse

Vérifier l'état des plugins au runtime

Voir aussi