Utiliser les paramètres URL

Objectif

Cette recette montre comment ouvrir Geoviewer 5.x sur une emprise, un point, une adresse ou une parcelle, restaurer un partage et ajouter des services. Elle fournit aussi la correspondance avec les paramètres historiques de Geoviewer 4.x.

Les paramètres fonctionnels sont placés dans le fragment de l’URL, après #. Geoviewer 5.x n’utilise pas les anciens paramètres de query string comme ?agsDynUrls=....

Pré-requis

Les ancres BBOX, COOR/COORD, ADR, CAD, ADD et PANIER sont traitées par le widget UrlQuery. Il doit être présent et actif :

{
    "widgetId": "url-query",
    "widgetClass": "UrlQuery",
    "active": true,
    "config": {}
}

La configuration par défaut active toutes les ancres usuelles. Si vous remplacez explicitement config.anchors, seules les entrées déclarées restent disponibles.

Paramètres supportés en 5.x

Ancre	Format principal	Effet
`BBOX`	`xmin,xmax,ymin,ymax[,srid]`	Zoome sur une emprise et la resynchronise ensuite dans l’URL.
`COOR` ou `COORD`	`x,y[,srid]`	Zoome sur un point. `COOR` est le nom historique ; `COORD` est alias.
`ADR`	texte encodé	Recherche une adresse et zoome sur le premier résultat.
`CAD`	référence cadastrale	Recherche une parcelle et zoome sur le premier résultat.
ancre personnalisée	valeur définie par l’intégrateur	Interroge une couche ArcGIS selon la configuration `CUSTOM`.
`ADD`	sous-paramètres séparés par `\|`	Ajoute un ou plusieurs services à la carte.
`PANIER`	tableau JSON 4.x encodé	Compatibilité de lecture ; utilisez `ADD` pour les nouveaux liens.
`SHARE`	jeton de partage	Restaure l’emprise, les services et les fonds enregistrés.
`VIEWER`	code de viewer	Support partiel lors d’un changement de hash après l’initialisation.

Les ancres de recherche ordinaires sont lues sans distinction de casse. En revanche, ADD, ses sous-paramètres, SHARE et VIEWER sont sensibles à la casse : utilisez les noms en majuscules.

Aucun paramètre de la query string (?PARAM=...) n’est lu par le cœur 5.x. Les options JavaScript loadingOptions configurent le chargement du viewer ; ce ne sont pas des paramètres de page.

Ordre de priorité des paramètres

Une seule demande de positionnement est retenue

Avec la configuration par défaut de UrlQuery, la priorité est la suivante, de la plus forte à la plus faible :

Priorité	Ancre	Si plusieurs demandes sont présentes
1	`CAD`	La recherche de parcelle l’emporte sur `ADR`, `COOR`/`COORD` et `BBOX`.
2	`ADR`	La recherche d’adresse l’emporte sur `COOR`/`COORD` et `BBOX`, en l’absence de `CAD`.
3	`COOR` ou `COORD`	Le point l’emporte sur `BBOX`, en l’absence de `CAD` et d’`ADR`.
4	`BBOX`	L’emprise est appliquée si aucune demande plus prioritaire n’est présente.

C’est l’ordre de config.anchors, et non l’ordre des paramètres dans l’URL, qui fixe cette priorité. Parmi les ancres configurées et présentes avec une valeur non vide dans le fragment, la dernière entrée de config.anchors est retenue. L’ordre par défaut est BBOX, COOR, ADR, CAD, puis ADD ; ADD est traité séparément.

Ainsi, #BBOX=150000,152000,116000,118000#ADR=Namur et #ADR=Namur#BBOX=150000,152000,116000,118000 exécutent tous deux la recherche d’adresse. De même, #COORD=151379,116739#BBOX=150000,152000,116000,118000 retient le point.

COOR et COORD sont deux orthographes de la même demande, pas deux niveaux de priorité. Si les deux figurent dans un lien, la valeur de COOR est lue en priorité ; utilisez une seule orthographe par lien.

ADD et PANIER se cumulent avec le positionnement

ADD et l’ancien PANIER ne concurrencent pas les ancres de positionnement. Le viewer ajoute les services demandés, attend la résolution des fiches Metawal éventuelles, puis lance la seule demande de positionnement retenue. Leur place dans le fragment ne change pas cette règle.

Par exemple, #BBOX=150000,152000,116000,118000#ADD|METADATAID=385d8e9c-2c01-41c7-a38c-911f746c8877 ajoute la donnée et applique l’emprise. Plusieurs blocs ADD, ainsi qu’un éventuel PANIER, sont cumulés ; ils ne suivent pas la règle « une seule ancre retenue ». La configuration doit conserver l’entrée ADD, y compris pour lire PANIER.

Cette composition est disponible à partir de la 5.0.1 : dans les versions antérieures, ADD pouvait empêcher l’application du positionnement.

Modifier la priorité et intégrer une ancre CUSTOM

Une ancre CUSTOM n’a pas de rang fixe : sa position dans config.anchors détermine sa priorité, comme pour les ancres usuelles. Une entrée CUSTOM placée après CAD l’emporte sur la recherche cadastrale si les deux ancres sont présentes ; placée avant BBOX, elle a une priorité plus faible que toutes les demandes usuelles.

Vous pouvez aussi modifier l’ordre des ancres usuelles. Cette configuration donne, par exemple, priorité à ADR sur CAD :

{
    "anchors": [{ "type": "BBOX" }, { "type": "COOR" }, { "type": "CAD" }, { "type": "ADR" }, { "type": "ADD" }]
}

Une liste explicite remplace la liste par défaut : une ancre absente de cette liste n’est plus traitée. Pour une ancre CUSTOM, fournissez aussi son nom anchor et sa configuration de recherche queryConfig, comme dans l’exemple plus bas.

Il faut distinguer l’emprise enregistrée dans le partage et une ancre #BBOX=... ajoutée au lien. Le partage restaure ses couches, ses fonds de plan et sa propre emprise ; celle-ci remplace l’emprise initiale de la configuration du viewer.

Combinaison	Comportement actuel
Configuration seule	Le viewer utilise l’emprise initiale de sa configuration.
`SHARE` valide, sans autre ancre de positionnement	L’emprise enregistrée dans le partage remplace celle de la configuration.
`SHARE` valide avec `BBOX`, `COOR`/`COORD`, `ADR`, `CAD` ou `CUSTOM`	Le partage fournit l’emprise initiale et `UrlQuery` exécute aussi l’ancre retenue selon son propre classement. La priorité finale entre ces deux positionnements n’est pas garantie actuellement.

Cette dernière combinaison n’est pas un niveau supplémentaire du classement CAD > ADR > COOR/COORD > BBOX. Le zoom initial issu du partage et le positionnement du widget peuvent démarrer en parallèle, sans contrat qui impose lequel s’applique en dernier. Il ne faut donc pas considérer qu’un BBOX explicite gagne systématiquement sur l’emprise du partage, ni l’inverse.

Le lecteur du jeton s’arrête sur &, mais pas sur une nouvelle ancre #. Ainsi, #SHARE=mon-jeton#BBOX=150000,152000,116000,118000 peut faire lire mon-jeton#BBOX=... comme jeton et empêcher la restauration du partage.

Placer BBOX avant SHARE permet de lire les deux valeurs, mais ne règle pas l’absence de priorité garantie entre les deux zooms. Remplacer le second # par & n’est pas une solution : UrlQuery attend une ancre #BBOX=.

Pour un lien fiable, utilisez SHARE seul, sans lui ajouter une demande de positionnement. Ajustez la vue puis générez un nouveau partage si une autre emprise doit être enregistrée. La même prudence s’applique à un BBOX ajouté automatiquement au fragment lors de la navigation : ce lien mixte n’est pas un contrat de restauration stable dans la version actuelle.

VIEWER et BBOX synchronisé

VIEWER relève du choix ou du changement de contexte, pas du classement des ancres de positionnement de UrlQuery.

Le BBOX ajouté ou mis à jour automatiquement après la navigation décrit la vue courante. Sa présence dans l’URL ne signifie pas qu’il a été prioritaire au démarrage : le viewer peut avoir retenu une adresse, une parcelle ou un point, puis synchronisé l’emprise obtenue. Lorsqu’un SHARE est également présent, appliquez les limites de composition décrites ci-dessus.

Ouvrir une emprise avec BBOX

Le format historique est :

https://example.be/ma-carte#BBOX=150000,152000,116000,118000

L’ordre est xmin,xmax,ymin,ymax. Sans cinquième valeur, les coordonnées sont lues en Lambert 72 (EPSG:31370) par défaut. Un SRID explicite peut être ajouté :

https://example.be/ma-carte#BBOX=649328,665262,650000,666000,3812

Une emprise de largeur ou de hauteur nulle est traitée comme un point. La forme ponctuelle produite par certains systèmes métier sous la forme de deux couples XY identiques est également reconnue :

https://example.be/ma-carte#BBOX=151379.836000003,116739.138999999,151379.836000003,116739.138999999

Après la navigation, le widget remplace ou ajoute BBOX avec l’emprise réellement affichée et son SRID. Cette synchronisation peut être désactivée avec syncToUrl: false. Dans une iframe de même origine, useParentWindowHash: true permet de lire et d’écrire le fragment de la page hôte.

Ouvrir un point avec COOR ou COORD

COOR est l’orthographe documentée et implémentée en 4.x. Geoviewer 5.x accepte aussi COORD, souvent utilisé spontanément par les intégrateurs :

https://example.be/ma-carte#COOR=151379.836000003,116739.138999999
https://example.be/ma-carte#COORD=151379.836000003,116739.138999999

Sans SRID, le défaut est Lambert 72. Pour des coordonnées WGS84 :

https://example.be/ma-carte#COOR=4.3675,50.8466,4326

Rechercher une adresse, une parcelle ou une valeur métier

Encodez les caractères réservés dans les valeurs :

https://example.be/ma-carte#ADR=avenue%20des%20Boutons%20d%27Or%204900%20Spa
https://example.be/ma-carte#CAD=92074A0010%2F00B000

Pour une recherche métier, déclarez une ancre CUSTOM dans le widget :

{
    "anchors": [
        {
            "type": "CUSTOM",
            "anchor": "DOSSIER",
            "queryConfig": {
                "type": "ESRI",
                "url": "https://example.be/arcgis/rest/services/Dossiers/MapServer",
                "layerId": 0,
                "queryString": "IDENTIFIANT = '{{VALUE}}'",
                "displayField": "{{IDENTIFIANT}}",
                "maxRecordsCount": 50
            }
        }
    ]
}

Le lien devient alors #DOSSIER=ABC-123.

Afficher le résultat

Les ancres COOR/COORD, ADR, CAD et CUSTOM acceptent les sous-paramètres suivants, séparés par | :

Sous-paramètre	Défaut	Effet actuel
`SHOW`	`false`	Affiche le résultat dans la couche graphique du widget.
`TOOLTIPTITLE`	`Informations`	Titre de la popup.
`TOOLTIPTEXT`	vide	Contenu complémentaire de la popup.
`TOOLTIPOPEN`	`false`	Ouvre la popup au chargement.
`ALLOWDELETE`	`true`	Autorise la suppression du graphique affiché.
`SCALE`	`500`	Conservé au parsing pour compatibilité, mais non appliqué en 5.0.0.

Exemple :

https://example.be/ma-carte#COOR=183482,127892|SHOW=true|TOOLTIPTITLE=Localisation|TOOLTIPOPEN=true

Il n’existe pas encore d’équivalent URL à SCALE en 5.0.0. Pour imposer un niveau de zoom précis, pilotez la carte après son initialisation via l’API JavaScript.

Ajouter des services ou restaurer un partage

Un bloc ADD est répétable et accepte les clés URL, METADATAID, TYPE, VISIBLE, OPACITY, LABEL et DESCRIPTION :

https://example.be/ma-carte#ADD|URL=https%3A%2F%2Fexample.be%2FMapServer|TYPE=ARCGIS_DYNAMIC|LABEL=Mon%20service

Utilisez soit URL, soit METADATAID, jamais les deux. Le type par défaut est ARCGIS_DYNAMIC. Pour un service ajouté directement par URL, DESCRIPTION est actuellement analysé mais non appliqué. La compatibilité PANIER nécessite que l’ancre ADD soit conservée dans config.anchors.

Pour ADD, PANIER et SHARE, consultez les recettes dédiées :

Avec le lecteur de partage actuel, utilisez SHARE seul : le jeton peut absorber une ancre placée après lui et la priorité entre son emprise et un positionnement explicite n’est pas garantie. Voir Priorité entre SHARE et BBOX.

Migration depuis Geoviewer 4.x

L’inventaire ci-dessous distingue les paramètres du cœur 4.x et ceux qui dépendaient d’un widget optionnel.

Paramètre 4.x	État en 5.x	Équivalent ou migration recommandée
`#BBOX`	supporté	Même ordre historique ; SRID optionnel et synchronisation URL ajoutés. Les BBOX ponctuelles fonctionnent.
`#COOR`	supporté	Même ancre ; SRID optionnel. `#COORD` est également accepté comme alias.
`#ADR`	supporté	Ancre `ADR` du widget `UrlQuery`.
`#CAD`	partiel	Une référence est supportée. Les listes de capakeys 4.x séparées par virgules ne sont pas équivalentes.
`#<champ>` ou `?<champ>` métier	partiel	Déclarer une entrée `CUSTOM`. Les usages 4.x incluaient `codeSiteNatura`, `CAPAKEY` et `CODECARTO`. La query string et le suffixe `\|\|layerId` ne sont pas repris ; configurez `layerId`.
`#SHARE`	supporté	Utiliser le widget de partage 5.x. Ne pas combiner le jeton 5.0.0 avec d’autres ancres.
`#PANIER` / `#panier`	compatibilité	Lecture limitée des anciens services ; préférer un ou plusieurs blocs `#ADD`.
`#MAP_SERVICES`	non	Utiliser `#ADD`, un partage, ou la configuration du viewer.
`#BASEMAPS`	non	Utiliser un partage ou la configuration `baseMap.json`.
`#MSS` / `#BMS`	non	Formats rétrocompatibles 4.x uniquement ; utiliser un partage ou la configuration 5.x.
`#ADU`	non	Utiliser `#ADD\|URL=...\|TYPE=ARCGIS_DYNAMIC`.
`?ADU` / `?agsDynUrls`	non	Même remplacement par `#ADD`; la query string 4.x n’est plus lue.
`#ATU`	non	Utiliser `#ADD\|URL=...\|TYPE=ARCGIS_TILED`.
`#WMS`	non	Utiliser `#ADD\|URL=...\|TYPE=WMS`. La sélection de sous-couches doit passer par la configuration ou l’API.
`#VIEWER`	partiel	Le gestionnaire de contextes 5.x réagit aux changements de hash. Pour l’initialisation, utilisez `loadingOptions` de type `api`.
`#CTX`, `?configContext`, `?internalContext`	non	Utiliser `loadingOptions` de type `url`/`api` ou les contextes configurés en 5.x.
`#TOC`	non	Utiliser un partage pour conserver l’état des services et de la table des matières.
`#MY_MAP_ID`	non	Aucun équivalent URL générique ; migrer vers le partage ou un parcours métier dédié.
`?batchToken`	non	Paramètre d’un widget 4.x spécifique, sans équivalent générique en 5.x.

Paramètres de la ressource d’inclusion 4.x

Ces paramètres ne pilotaient pas directement l’état de la carte. Ils étaient placés sur l’URL du script ou de la feuille de style 4.x :

Paramètre 4.x	État en 5.x	Migration recommandée
`lang`	non	Configurez l’internationalisation du viewer et de la page hôte ; le script 5.x ne lit pas ce query param historique.
`theme`	non	Utilisez les styles et variables de thème 5.x.
`colors`	non	Utilisez la configuration de thème 5.x ; la syntaxe `color1=...` à `color6=...` disparaît.
`t`	non	Ancien jeton d’inclusion 4.0 ; utilisez `loadingOptions` ou l’endpoint API 5.x prévu par votre intégration.

Paramètres propres à Imajnet

Le widget Imajnet 4.x embarquait une seconde grammaire d’URL, distincte des ancres Geoviewer : wid, tgid, pos, locale, image, loc, time, map, zoom et trace, séparés par ;. Ces valeurs ne constituent pas un contrat URL général de Geoviewer et n’ont pas d’équivalent générique en 5.x. Si votre application les utilise, migrez-les dans le parcours du composant ou service Street View retenu.

Encodage et composition

Encodez les valeurs avec encodeURIComponent, surtout les adresses, URLs, libellés et textes de popup.
N’utilisez qu’une ancre de positionnement (BBOX, COOR/COORD, ADR, CAD ou CUSTOM) par lien.
ADD et son équivalent historique PANIER peuvent être combinés avec une ancre de positionnement. Le viewer ajoute d’abord tous les services, y compris ceux chargés depuis Metawal, puis applique le positionnement demandé.
Si plusieurs ancres de positionnement sont malgré tout présentes, appliquez les règles de la section Ordre de priorité des paramètres : CAD, puis ADR, COOR/COORD et enfin BBOX avec la configuration par défaut.
Répétez #ADD|... pour ajouter plusieurs services.
Les liens sont interprétés au chargement. Modifier le hash après coup ne relance pas automatiquement toutes les recherches UrlQuery.

Dépannage

Symptôme	Vérification rapide
La carte garde son emprise par défaut	Vérifiez le widget `UrlQuery`, l’ordre BBOX, les nombres et le SRID.
`COOR` ou `COORD` est ignoré	Vérifiez que l’ancre correspondante n’a pas été retirée de `config.anchors`.
Une adresse ne produit aucun résultat	Encodez la valeur et vérifiez le service de géocodage configuré.
Une parcelle ne produit aucun résultat	Testez une capakey unique et encodez `/`.
Un service n’est pas ajouté	Vérifiez l’ancre `ADD`, `TYPE`, l’encodage de `URL` et le CORS.
Un partage est déclaré invalide	Placez `SHARE` seul dans le fragment et vérifiez que le jeton existe encore.