Skip to content
GeoViewer 5

UrlQuery

UrlQuery

Nom fonctionnel: Paramètres URL

Pour construire un lien et retrouver les correspondances 4.x vers 5.x, consultez la recette Utiliser les paramètres URL.

Priorité entre les paramètres

Avec la configuration par défaut, une seule ancre de positionnement est exécutée, selon l’ordre de priorité CAD > ADR > COOR/COORD > BBOX. L’ordre des paramètres dans l’URL ne change pas ce classement ; c’est la dernière entrée correspondante dans config.anchors qui l’emporte. Les ancres CUSTOM suivent la même règle selon leur place dans cette liste.

À partir de la 5.0.1, ADD et PANIER sont traités séparément : ils ajoutent les services puis laissent s’appliquer le positionnement retenu. Consultez les règles de priorité et leurs exemples, notamment pour modifier cet ordre, combiner les paramètres ou comprendre l’absence de repli après une recherche sans résultat.

Le partage SHARE contient sa propre emprise. Elle remplace celle de la configuration, mais sa priorité face à un BBOX explicite ou une autre ancre de positionnement n’est pas garantie actuellement. Utilisez SHARE seul et consultez les limites de composition dans la recette.

À quoi sert ce widget ?

Lit et applique des paramètres URL pour ouvrir le viewer dans un état prédéfini.

Conseil: un viewer “trop outillé” devient vite bruyant. Activez ce widget uniquement s’il sert un parcours utilisateur clair.

Quand l’activer

  • Quand l’utilisateur doit piloter sa vue (zoom, couches, plein écran, repérage).
  • Quand vous voulez des contrôles cohérents et immédiatement compréhensibles, quel que soit le moteur cartographique.
  • Quand vous cherchez à réduire les frictions (moins de clics, moins d’aller-retour, plus de lisibilité).

En clair

  • Côté utilisateur: Le confort d’usage augmente fortement dès la première prise en main.
  • Côté intégration: Vérifiez la cohérence entre projection, échelle, coordonnées et basemaps.

Prise en main

Accéder au widget

  • Ouvrez le widget depuis la barre d’outils (ou via son bouton dédié).
  • Vérifiez son emplacement et sa lisibilité (desktop et mobile).

Le configurer sans se tromper

  • Choisissez un conteneur adapté (toolbar, drawer, dialog) pour éviter de masquer la carte.
  • Validez les interactions avec les autres widgets (raccourcis, activation simultanée, conflits).

Ce que l’utilisateur voit

  • Lecture des paramètres URL au chargement du viewer.
  • Application des filtres et états transmis dans l’adresse.
  • Support des liens profonds pour ouvrir une vue ciblée.

Parcours utilisateur (le plus courant)

  • Construisez une URL avec les paramètres utiles à votre scénario.
  • Ouvrez la carte depuis ce lien pour vérifier l’état reconstitué.
  • Utilisez ce mécanisme dans vos emails, tickets et portails métier.

Ajouter des services par URL

Pour ouvrir le viewer avec des services déjà ajoutés, utilisez l’ancre #ADD.

Exemples:

  • #ADD|METADATAID=<uuid> pour ajouter une donnée depuis sa fiche catalogue.
  • #ADD|URL=<url-encodee>|TYPE=ARCGIS_DYNAMIC|LABEL=<label-encode> pour ajouter un service depuis son endpoint.
  • #ADD|METADATAID=<uuid>#ADD|URL=<url-encodee>|TYPE=WMS pour ajouter plusieurs services.

Voir la recette complète: Ajouter des services par URL.

Synchroniser l’emprise dans l’URL

L’ancre BBOX est mise à jour automatiquement après un zoom ou un déplacement de la carte. Cette synchronisation est activée par défaut et permet de rouvrir le viewer au même endroit en copiant son URL.

Le format lu est xmin,xmax,ymin,ymax[,srid]. Sans SRID dans l’URL, readWkid est utilisé ; il vaut Lambert 72 (EPSG:31370) par défaut afin de conserver la compatibilité avec les favoris WOM 4.x.

Une emprise de largeur ou de hauteur nulle est traitée comme un point. La forme x,y,x,y, produite par certains systèmes pour représenter deux couples XY identiques, est également reconnue lorsqu’elle décrit un point.

Exemples :

  • #BBOX=199604,214839,132322,139551 est lu en Lambert 72 avec la configuration par défaut.
  • #BBOX=649328,665262,650000,666000,3812 est lu dans la projection indiquée par le cinquième nombre.
{
    "type": "BBOX",
    "readWkid": 31370,
    "syncToUrl": true
}

À l’écriture, le SRID est toujours ajouté. Par défaut, le widget écrit dans la projection courante de la carte. Définissez writeWkid pour imposer une autre projection :

{
    "type": "BBOX",
    "readWkid": 31370,
    "writeWkid": 3812,
    "syncToUrl": true
}

Pour une projection métrique, la partie décimale des coordonnées est supprimée afin de garder une URL compacte :

#BBOX=199604,214839,132322,139551,31370

Utilisez syncToUrl: false pour désactiver ce comportement. Dans une iframe, configurez useParentWindowHash: true pour lire et synchroniser le hash de la fenêtre parente. Si celle-ci est d’une autre origine, le widget utilise automatiquement l’URL de l’iframe.

L’ancienne option wkid reste acceptée pour compatibilité et configure simultanément les projections de lecture et d’écriture. Les nouvelles configurations doivent utiliser readWkid et writeWkid.

{
    "useParentWindowHash": true
}

Lire un point depuis l’URL

L’ancre historique est COOR. L’alias COORD est également accepté. Les deux suivent le même principe : x,y[,srid]. Sans troisième nombre, la projection par défaut est également Lambert 72 et peut être adaptée dans la configuration du widget :

{
    "type": "COOR",
    "queryConfig": {
        "type": "COORDS",
        "wkid": 4326
    }
}

Exemples : #COOR=199604,132322 et #COORD=199604,132322 utilisent le défaut configuré ; #COOR=4.3675,50.8466,4326 utilise explicitement WGS84. Le widget lit ces ancres mais ne les écrit pas lors de la navigation.

Exemples concrets

  • Accélérer la lecture de carte (moins de clics pour zoomer, afficher/masquer, contextualiser).
  • Donner un repère clair à l’utilisateur (échelle, coordonnées, état de la vue).
  • Réduire les frictions sur les actions répétitives (plein écran, recentrage, bascule de contexte).

Configuration (aperçu)

OptionTypeDéfautDescription
widgetIdstring-Identifiant unique de l’instance UrlQuery.
activebooleantrueActive le traitement des paramètres au démarrage.
inToolbarboolean ou objet ou stringfalseCe widget technique n’a pas de bouton par défaut.
containerstring ou objethiddenLe widget s’exécute sans interface visible.

Pour le détail complet (et toujours à jour), utilisez la référence technique et le schéma ci-dessous.

Liens techniques et code

Exemple minimal (copier-coller)

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

Exemple avancé

{
    "widgetId": "url-query-advanced",
    "widgetClass": "UrlQuery",
    "active": true,
    "handleOpenAtStartup": false,
    "inToolbar": {
        "type": "button",
        "toolbarId": "default-toolbar",
        "order": 10
    },
    "onActivate": {
        "deactivate": {
            "classes": []
        }
    },
    "config": {}
}

Points d’attention

  • Un bouton peut être bien configuré mais masqué par le conteneur.
  • La géolocalisation dépend des permissions navigateur et du HTTPS.
  • Le comportement peut différer légèrement entre moteurs cartographiques.

Dépannage

SymptômeVérification rapide
Le bouton est visible mais inactif.Vérifiez l’état active et les interactions concurrentes.
Le recentrage est imprécis.Contrôlez la projection et les coordonnées utilisées.

FAQ

Ces widgets sont-ils adaptés au mobile ?

Oui, avec des ajustements d’ergonomie selon la taille écran.

Peut-on les regrouper dans la même toolbar ?

Oui, c’est recommandé pour un parcours simple.

Captures à ajouter

  • (Capture à ajouter) /assets/screenshots/TODO/url-query-01.png: widget ouvert avec configuration standard.
  • (Capture à ajouter) /assets/screenshots/TODO/url-query-02.png: interaction principale et résultat attendu.

Liens PDF source

  • Aucun PDF de référence détecté automatiquement pour ce widget.

Aller plus loin