Agregar parámetros configurables a plantillas

Después de crear una plantilla de aplicación web, tiene la opción de hacerla configurable. Las aplicaciones web configurables permiten a los usuarios personalizar la apariencia y el comportamiento de una aplicación. Hacer que una plantilla de aplicación sea configurable es un proceso de cuatro pasos:

  1. Si aún no lo ha hecho, cree una plantilla de aplicación web.
  2. Cree un archivo de configuración para definir las propiedades de configuración.
  3. Configure la plantilla para que lea las propiedades de configuración y las use en la aplicación.
  4. Asocia el archivo de configuración al elemento para la plantilla de aplicación.

Crear un archivo de configuración

El archivo de configuración es un archivo JSON que define las opciones configurables de la plantilla de aplicación. Vea un ejemplo completo de un archivo de configuración.

Nota:

Es una buena práctica ejecutar el código JSON mediante un validador como JSONLint a fin de garantizar que el JSON tenga un formato correcto y esté libre de errores.

Este archivo de configuración contiene una o más secciones que clasifican las opciones.

Cree las distintas secciones especificando una categoría y un conjunto de campos.

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

Especifique las opciones de configuración utilizando los tipos de campo que se muestran en la tabla siguiente. Al crear el archivo de configuración, asegúrese de que la propiedad fieldName sea única dentro del ajuste de la configuración.

Tipo de campoDescripción

Párrafo

Muestra texto explicativo en el cuadro de diálogo de configuración.

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

Cadena de caracteres

Acepta entrada de texto. Incluye la propiedad stringFieldOption, que especifica el tipo de cuadro de texto que se muestra en la pantalla. Los valores son textbox, textarea y richtext. La opción textbox es la predeterminada y consiste en un cuadro de texto con una sola línea. La opción textarea muestra un campo de texto más grande para introducir datos. La opción richtext muestra un editor de texto enriquecido que permite a los usuarios aplicar algunos formatos como, por ejemplo, establecer la fuente o aplicar negrita o cursiva al texto.

{
        "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"
}

Salida de muestra

description:"Bike Accidents"

Booleano

Cree un cuadro de texto para especificar valores true o false. Use condition para ver si el mapa contiene la funcionalidad esperada. Si el mapa no cumple la condición, el panel de configuración no muestra la casilla de verificación ni la etiqueta.

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

Salida de muestra

tool_bookmarks:false

Número

Cree un campo que acepta valores numéricos. Si el campo debe aceptar únicamente un rango de valores específico, puede utilizar el ajuste de constraints para delimitar el rango de valores específicos que se puede introducir o para dar formato a los valores introducidos.

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

Salida de muestra

range:0.5

Opciones

Cree una lista desplegable con una serie de opciones.

{
   "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"
   }]
 }

Salida de muestra

theme:"blue"

Selector de color

Muestra un selector de color para elegir un color de una paleta o especificar valores hexadecimales, RGB o HSV.

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

Salida de muestra

selectionColor:"#829254"

Diálogo de mapa web

Muestra un cuadro de diálogo para examinar o buscar un nuevo mapa para mostrarlo en la aplicación. Opcionalmente, especifique una condición para probar el mapa. Si esta condición no se cumple, el panel de configuración presenta un mensaje de validación que confirma que el mapa no cumple los requisitos. Las cadenas de condiciones son las siguientes:

  • time: el mapa tiene la función de tiempo habilitada
  • edit: la aplicación tiene al menos una capa editable
  • featurelayer: el mapa tiene al menos una capa de entidades
  • filter: el mapa tiene definido un filtro interactivo
  • 4x: el mapa contiene contenido que no se admite aún en la versión 4x de ArcGIS API for JavaScript
{
   “type”: “webmap”,
   “conditions”: [“time”, “edit”, “featurelayer”, “filter”, “4x”]
 }

Salida de muestra

webmap:"739ef0cf75de432995c77dd44ec8f652"

Cuadro de diálogo de Grupo

Muestra un cuadro de diálogo para examinar o buscar un nuevo grupo para mostrarlo en la aplicación.

{
   "type": "group"

 }

Salida de muestra

group:"449d00a4478d4849bbb65612355d6cd1"

Selector de varias capas y campos

Presenta una vista de árbol de las capas y campos del mapa que coinciden con los tipos admitidos y con los tipos de geometría. Permite a los usuarios finales de la aplicación seleccionar varias capas y varios campos en cada capa.

 {  
               "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"
                  ]
               }
            }

Salida de muestra

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

Selector de capas y campos

Muestra una lista desplegable de capas en el mapa filtrado por los tipos y geometrías enumerados. Opcionalmente, sirve para especificar uno o más selectores de campo para que los usuarios puedan seleccionar una capa y campos.

  {  
               "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"
                  ]
               }
            }

Salida de muestra

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

Radio

Permite crear un botón de radio con el que solo se puede seleccionar una opción cada vez. La opción seleccionada se establecerá en verdadera.

{
   "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
   }]
 }

Salida de muestra

customLayout:"fullmap"

Mapas base

Muestra una lista desplegable de todos los mapas base de Esri con nombre.

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

Salida de muestra

my_basemap:"satellite"

Condicional

Muestra u oculta contenido basándose en una condición con valor true o false. Por ejemplo, si una casilla de verificación Mostrar lista de capas está desactivada, la lista de capas y todas las opciones relacionadas (por ejemplo Incluir subcapas en la lista de capas) están ocultas.

   {
               "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"
                   }
               ]
            }
}

Buscar

Configura un panel de búsqueda para buscar entidades dentro de un campo de una capa de entidades o de direcciones utilizando un localizador. Si configura una búsqueda de entidades, los usuarios pueden elegir los campos de capa de entidades y búsqueda.

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

Salida de muestra

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

Muestra una lista de niveles de escala predefinidos entre los cuales se puede elegir. Por ejemplo, Países, Estados, Estado, Provincias, Provincia, Área metropolitana, Ciudad, Población, Vecindad.

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

Ejemplo de salida

“customUrlLayerZoomScale”: 12000

Archivo de configuración de ejemplo

A continuación se muestra un ejemplo de un archivo de configuración completo.

{
    "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
    }
}

Configurar la plantilla para leer la información del archivo de configuración

Para hacer que la plantilla sea configurable, la aplicación debe aceptar el Id. de elemento para una aplicación de representación cartográfica en la red como valor del parámetro de URL appid. Este Id. de aplicación se utiliza para realizar una solicitud asíncrona a fin de recuperar las propiedades de configuración de la aplicación. En la ArcGIS API for JavaScript, se puede usar esri.request para recuperar los detalles de configuración de la aplicación.

En este ejemplo, esri.arcgis.utils.arcgisUrl se resuelve como 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 respuesta incluirá los cambios que el usuario haya realizado en la aplicación utilizando el panel de configuración. A continuación, puede recuperar los cambios e implementarlos en la aplicación. La aplicación debe definir los valores predeterminados de las opciones de configuración a fin de gestionar las situaciones en las que la plantilla no se ha configurado.

 {
    "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
       }
 }

Asociar la información del archivo de configuración con un elemento de una plantilla de aplicación

Después de crear el archivo de configuración, estará listo para asociarlo a su plantilla de aplicación personalizada y hacer que la aplicación sea configurable.

  1. Si no lo ha hecho ya, agregue la plantilla de aplicación como nuevo elemento de aplicación.
  2. En la página de elementos de la plantilla de aplicación, haga clic en la pestaña Configuración y busque la sección Aplicación de representación cartográfica en la red.
  3. En el menú desplegable Propósito, seleccione Configurable.
  4. En el campo Parámetros de configuración, pegue el código JSON de su archivo de configuración.
    Nota:

    El campo Parámetros de configuración requiere un JSON válido. Es una buena práctica ejecutar el JSON mediante un validador como JSONLint a fin de garantizar que el JSON tenga un formato correcto y esté libre de errores.

  5. Haga clic en Guardar para guardar sus ajustes.

Si desea utilizar la plantilla configurable en la galería de aplicaciones de Map Viewer Classic de su organización o en la galería de aplicaciones de grupos, comparta el elemento con el grupo que se esté utilizando para la galería de aplicaciones. A continuación, el administrador de la organización puede configurar el mapa o configurar grupos para usar el grupo que incluya la plantilla.