Ajouter des paramètres configurables aux modèles

Une fois que vous avez créé un modèle d’application Web, vous pouvez le rendre configurable si vous le souhaitez. Les applications Web configurables permettent aux utilisateurs de personnaliser l'apparence et le comportement d'une application. La procédure permettant de rendre un modèle d'application configurable se compose de quatre étapes :

  1. Si vous ne l'avez pas déjà fait, créez un modèle d'application Web.
  2. Créez un fichier de configuration pour définir les propriétés de configuration souhaitées.
  3. Configurez le modèle pour lire les propriétés de configuration et appliquez-les à l’application.
  4. Associez le fichier de configuration à l’élément de votre modèle d’application.

Créez un fichier de configuration

Le fichier de configuration est un fichier JSON qui définit les options de configuration du modèle d'application. Consultez un exemple complet de fichier de configuration.

Remarque :

Il est recommandé d’exécuter votre code JSON via un outil de validation, tel que JSONLint, pour s’assurer que le code JSON est correctement formé et qu’il ne comporte pas d’erreur.

Le fichier de configuration contient une ou plusieurs sections qui classent les options.

Créez chaque section en spécifiant une catégorie et un ensemble de champs.

{
    "configurationSettings": [
        {
            "category": "",
            "fields": []
        }
    ]
}

Spécifiez les options de configuration à l’aide des types de champs répertoriés dans le tableau ci-dessous. Lorsque vous créez le fichier de configuration, veillez à ce que la propriété fieldName soit unique dans le paramètre de configuration.

Type de champDescription

Paragraphe

Affiche une explication dans la boîte de dialogue de configuration.

{
       "type": "paragraph",       "value": "* These menu items will appear in the application when the web map has layers that require them."
}

Chaîne

Accepte l'entrée de texte. Inclut la propriété stringFieldOption qui indique le type de zone de texte affiché à l'écran. Les valeurs sont textbox, textarea et richtext. L'option textbox est la valeur par défaut et une zone de texte uniligne. L'option textarea affiche une zone de texte plus grande afin d'y saisir des données. L'option richtext affiche un éditeur de texte enrichi qui permet aux utilisateurs d'appliquer une mise en forme au texte (par exemple mettre la police en gras ou en italique).

{
        "type": "string",        "fieldName": "description",        "label": "Description",        "tooltip": "",         "stringFieldOption": richtext || textarea || textbox,        "placeHolder": "Text that appears in the text box to provide a hint to users on text to enter"
}

Exemple de sortie

description:"Bike Accidents"

Booléen

Crée une case à cocher pour indiquer des valeurs true ou false. Utilisez condition pour voir si la carte contient la fonctionnalité spécifiée. Si la carte ne remplit pas la condition, la case à cocher et l’étiquette n’apparaissent pas dans le panneau de configuration.

{
       "type": "boolean",       "fieldName": "tool_bookmarks",       "condition": "bookmark",       "label": "Bookmarks",       "tooltip": ""
 }

Exemple de sortie

tool_bookmarks:false

Nombre

Crée un champ qui accepte des valeurs numériques. Si le champ ne doit accepter qu'une plage spécifique de valeurs, vous pouvez utiliser le constraints paramètre des contraintes pour limiter l'entrée dans une plage de valeurs donnée ou pour mettre en forme les valeurs en entrée.

{      "type": "number",
     "fieldName": "range",     "label": "Range:",     "tooltip": "",     "constraints" :{min:0,max:10,places:0}
}

Exemple de sortie

range:0.5

options

Crée une liste déroulante avec une série de choix.

{
   "type": "options",   "fieldName": "theme",   "tooltip": "Color theme to use",   "label": "Color Scheme:",   "options": [{
     "label": "Blue",     "value": "blue"
   }, {
     "label": "Green",     "value": "green"
   }, {
     "label": "Orange",     "value": "orange"
   }]
 }

Exemple de sortie

theme:"blue"

Sélecteur de couleurs

Affiche un sélecteur de couleurs permettant de choisir une couleur dans une palette ou de spécifier des valeurs hexadécimales, RVB ou TSL.

{
   "type": "color",    "label": "Choose a selection color",
   "fieldName": "selectionColor"
  
 }

Exemple de sortie

selectionColor:"#829254"

Boîte de dialogue Carte web

Affiche une boîte de dialogue qui permet de parcourir ou de recherche une nouvelle carte à afficher dans l’application. Vous pouvez également spécifier une condition pour tester la carte. Si la condition spécifiée n’est pas remplie, un message de validation apparaît dans le panneau de configuration pour confirmer que la carte ne répond pas aux exigences requises. Les chaînes de conditions valides sont les suivantes :

  • time - La carte est temporelle.
  • edit - L’application comporte au moins une couche modifiable.
  • featurelayer - La carte comporte au moins une couche d’entités.
  • filter - Un filtre interactif est défini pour la carte.
  • 4x - La carte comporte un contenu non encore pris en charge dans la version 4x de ArcGIS API for JavaScript.
{
   “type”: “webmap”,   “conditions”: [“time”, “edit”, “featurelayer”, “filter”, “4x”]
 }

Exemple de sortie

webmap:"739ef0cf75de432995c77dd44ec8f652"

Boîte de dialogue Groupe

Affiche une boîte de dialogue qui permet de parcourir ou de rechercher un nouveau groupe à afficher dans l’application.

{
   "type": "group"
 }

Exemple de sortie

group:"449d00a4478d4849bbb65612355d6cd1"

Sélection de plusieurs couches et champs

Présente une arborescence des couches et champs de la carte qui correspond aux types pris en charge et aux types de géométrie. Permet aux utilisateurs de l'application de sélectionner plusieurs couches et plusieurs champs pour chaque couche.

{  
               "label":"Select search layers and fields",
               "fieldName":"searchLayers",
               "type":"multilayerandfieldselector",
               "tooltip":"Select layer and fields to search",
               "layerOptions":{  
                  "supportedTypes":[  
                     "FeatureLayer"
                  ],
                  "geometryTypes":[  
                     "esriGeometryPoint",
                     "esriGeometryLine",
                     "esriGeometryPolyline",
                     "esriGeometryPolygon"
                  ]
               },
               "fieldOptions":{  
                  "supportedTypes":[  
                     "esriFieldTypeString"
                  ]
               }
            }

Exemple de sortie

searchLayers: [{
    "id":"Whittier_Hazards_821",    "fields":[],    "type":"FeatureLayer"
}]

Sélection de couches et de champs

Affiche une liste déroulante des couches de la carte filtrée selon les types et géométries répertoriés. Vous pouvez préciser un ou plusieurs sélecteurs de champ pour permettre aux utilisateurs de sélectionner une couche et des champs.

{  
               "type":"layerAndFieldSelector",
               "fieldName":"tableLayer",
               "label":"Layer to display in table",
               "tooltip":"Layer to display in table",
               "fields":[  
                  {  
                     "multipleSelection":true,
                     "fieldName":"hiddenFields",
                     "label":"Hide the selected fields",
                     "tooltip":"Fields to hide in table",
                     "supportedTypes":[  
                        "esriFieldTypeSmallInteger",
                        "esriFieldTypeInteger",
                        "esriFieldTypeSingle",
                        "esriFieldTypeDouble",
                        "esriFieldTypeString"
                     ]
                  }
               ],
               "layerOptions":{  
                  "supportedTypes":[  
                     "FeatureLayer"
                  ],
                  "geometryTypes":[  
                     "esriGeometryPoint",
                     "esriGeometryLine",
                     "esriGeometryPolygon"
                  ]
               }
            }

Exemple de sortie

tableLayer: {
    id: "2014CyclingAccidents_All_874",    fields: [{
        id: "urlField",        fields: ["Casualty_Severity"]       }]
}

Radio

Crée une case d'option pour laquelle une seule option peut être sélectionnée à la fois. L'option sélectionnée sera définie sur la valeur True.

{
   "type": "radio",   "fieldName": "layout",   "tooltip": "Custom Layout",   "label": "Custom Layout:",   "items": [{
     "label": "Sidebar",     "value": "sidebarmenu"
   }, {
     "label": "FullWidth",     "value": "fullwidth"
   }, {
     "label": "default",     "value": "Default",     "checked": true   }]
 }

Exemple de sortie

customLayout:"fullmap"

Fonds de carte

Affiche une liste déroulante de tous les fonds de carte Esri nommés.

{
  “type”: “basemaps”,   “fieldname” :”my_basemap”,   “label”: “Alternate Basemap”
}

Exemple de sortie

my_basemap:"satellite"

Conditions

Affiche ou masque le contenu selon une condition true ou false. Par exemple, si une case à cocher Afficher la liste des couches est désactivée, la liste des couches et toutes les options associées (par exemple Inclure les sous-couches dans la liste de couches) sont masquées.

{
               "type":"conditional",
               "condition": false,
               "fieldName":"showtitle",
               "label":"Display Map Title",
               "items":[
                 {
                    "placeHolder":"Defaults to web map title",
                    "label":"Title:",
                    "fieldName":"title",
                    "type":"string",
                    "tooltip":"Defaults to web map title"
                 },{
                      "type":"paragraph",
                      "value":"Enter a value to override the default title font size "
                   },
                   {
                      "type":"string",
                      "label":"Title font size",
                      "tooltip":"Specify title font size",
                      "fieldName":"titlefontsize",
                      "placeHolder":"20px"
                   }
               ]
            }
}

Rechercher

Configure un volet de recherche permettant de rechercher des entités dans un champ d'une couche d'entités ou des adresses à l'aide d'un localisateur. Si vous configurez une recherche d'entités, les utilisateurs peuvent choisir la couche d'entités et les champs de recherche.

{
“type”: “Search”,  “fieldName”: “searchConfig”, “label”: “Configure Search Options”
}

Exemple de sortie

searchConfig: {
sources: [{
locator: {
    url: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",    _url: {
        path: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",        query: null    },        normalization: true    },    url: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",    name: "ArcGIS World Geocoding Service",    enableSuggestions: true,    singleLineFieldName: "SingleLine",    enable: true,    id: "dojoUnique3"
}], activeSourceIndex: 0, enableSearchingAll: false
}

ScaleList

Affiche une liste des niveaux d'échelle prédéfinis que l'utilisateur peut sélectionner. Par exemple, Pays, Etats, Etat, Comtés, Comté, Métropole, Ville, Commune, Quartier.

{
    “type”: “scaleList”,    “fieldName”: “customUrlLayerZoomScale”,     “label”: “Choose zoom level”
}

Exemple de sortie

“customUrlLayerZoomScale”: 12000

Exemple de fichier de configuration

Vous trouverez ci-dessous un exemple de fichier de configuration complet.

{
    "configurationSettings": [        {
            "category": "General Settings",            "fields": [                {
                    "type": "options",                    "fieldName": "theme",                    "tooltip": "Color theme to use",                    "label": "Color Scheme:",                    "options": [                        {
                            "label": "Blue",                            "value": "blue"
                        },                        {
                            "label": "Green",                            "value": "green"
                        },                        {
                            "label": "Orange",                            "value": "orange"
                        }
                    ]                },                {
                    "type": "string",                    "fieldName": "layer",                    "label": "Analysis Layer",                    "tooltip": "Feature Layer with Facilities to search"
                },                {
                    "type": "string",                    "fieldName": "orgname",                    "label": "Organization Name:",                    "tooltip": "",                    "stringFieldOption": "richtext",                    "placeHolder": "Organization Name"
                },                {
                    "type": "number",                    "fieldName": "bufferdistance",                    "label": "Search Distance (miles)",                    "value": "1"
                }
            ]        }
    ],    "values": {
        "theme": "orange",        "bufferdistance": 1    }
}

Paramétrer le modèle pour lire les informations du fichier de configuration

Pour que le modèle soit configurable, l’application doit accepter l’ID d’élément d’une application cartographique Web comme valeur du paramètre URL appid. Cet ID permet d'effectuer une requête asynchrone visant à extraire les propriétés de configuration de l'application. Dans ArcGIS API for JavaScript, vous pouvez utiliser esri.request pour extraire les détails de configuration de l'application.

Dans cet exemple, esri.arcgis.utils.arcgisUrl est résolu en www.arcgis.com/sharing/content/items.

var requestHandle = esri.request({
    url: esri.arcgis.utils.arcgisUrl + "/" + appid + "/data",
    content: {
        f: "json"
     },
    callbackParamName: "callback",
    load: function (response) {
     for (var key in response.values){
      if(response.values[key]!==undefined)configOptions[key]=response.values[key];
      }
    }, 
});

La réponse inclura les modifications apportées par l'utilisateur à l'application à l'aide du volet de configuration. Vous pouvez ensuite extraire les modifications et les appliquer à l'application. L'application doit définir les valeurs par défaut des options de configuration pour gérer les situations dans lesquelles le modèle n'est pas configuré.

{
    "source": "15a34e2c161b4364860854fbc84262c5",    "folderId": "5705faa4594a4fd09edf01742c16e523",    "values": {
        "webmap": "32f1438789d34b5e8125f0f7c64b8d63",        "layer":"https://sampleserver6.arcgisonline.com/arcgis/rest/services/Water_Network/MapServer/2",        "theme": "green",        "orgname": "Water Points",        "bufferdistance": 3       }
 }

Associer des informations du fichier de configuration à l'élément de votre modèle d'application

Après avoir créé votre fichier de configuration, vous êtes prêt à l’associer à votre modèle d’application personnalisé et à rendre l’application configurable.

  1. Si tel n’est pas encore le cas, ajoutez le modèle d’application comme nouvel élément d’application.
  2. Dans la page des éléments du modèle d’application, cliquez sur l’onglet Settings (Paramètres) et recherchez la section Web Mapping Application (Application cartographique Web).
  3. Dans le menu déroulant Purpose (Objet), sélectionnez Configurable.
  4. Dans le champ Configuration Parameters (Paramètres de configuration), collez le code JSON issu de votre fichier de configuration.
    Remarque :

    Le champ Paramètres de configuration requiert un code JSON valide. Il est recommandé d'exécuter votre JSON via un validateur, tel que JSONLint pour s'assurer que le code JSON est correctement formé et qu'il ne comporte pas d'erreurs.

  5. Cliquez sur Save (Enregistrer) pour enregistrer vos paramètres.

Si vous souhaitez utiliser le modèle configurable dans la bibliothèque d'applications Map Viewer Classic ou la bibliothèque d'applications de groupes de votre organisation, partagez l'élément avec le groupe utilisé pour cette bibliothèque d'applications. L'administrateur de votre organisation pourra ensuite configurer la carte ou configurer les groupes de façon à utiliser le groupe qui comprend votre modèle.