Añadir parámetros configurables a plantillas

Las plantillas personalizables permiten a los usuarios personalizar la apariencia y el comportamiento de la aplicación. Hacer que una plantilla sea configurable es un proceso de cuatro pasos:

1. Crea una aplicación de plantilla si todavía no lo has hecho.
2. Crea un archivo de configuración.
3. Configura la plantilla para que lea las propiedades de configuración y aplícalas a la aplicación.
4. Asocia el archivo de configuración con el elemento de la plantilla personalizada.

Los pasos para añadir parámetros de configuración a tu aplicación de plantilla personalizada se describen en detalle a continuación. Para información sobre cómo se crea una plantilla, consulta Crear plantillas de aplicación Web.

Crear un archivo de configuración

El archivo de configuración es un archivo JSON que define el diálogo de entrada de la plantilla personalizada. Este archivo contiene una o más secciones que categorizan las opciones de personalización.

La propiedad fieldName debe ser única dentro de los ajustes de configuración.

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

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

Especifica las opciones de configuración utilizando los tipos de campo que se muestran en la tabla siguiente.

Tipo de campo	Descripció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 (cuadro de texto), textarea (área de texto) y richtext (texto con formato). Textbox es el valor predeterminado y consiste en un cuadro de texto con una sola línea. El área de texto muestra un campo de texto mayor para introducir datos. El texto con formato muestra un editor de texto con formato que permite a los usuarios aplicar algunos formatos, como 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" }
Boolean	Crea un cuadro de texto para especificar valores verdaderos o falsos. { "type": "boolean", "fieldName": "displaytitle", "label": "Show Title", "tooltip": "" }
Number	Crea un campo que acepta valores numéricos. Si el campo debe aceptar únicamente un intervalo de valores específico, puedes utilizar el ajuste de restricción para delimitar el rango de valores específico que se puede introducir o para dar formato a los valores introducidos. Más información sobre cómo crear restricciones con Dojo NumberTextBox { "type": "number", "fieldName": "range", "label": "Range:", "tooltip": "", "constraints" :{min:0,max:10,places:0} }
Options	Crea 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" }] }

Archivo de configuración de ejemplo

A continuación hay un ejemplo de un archivo de configuración completo y el panel de configuración que resulta.

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

El panel de configuración del código de ejemplo:

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

Si la plantilla va a ser configurable, entonces es necesario que la aplicación acepte un ID de aplicación como parámetro en la URL. Este ID de aplicación (appid) se utiliza para solicitar una solicitud asíncrona a fin de recuperar las propiedades de configuración de la aplicación. En la API de ArcGIS para JavaScript, se puede usar esri.request para recuperar los detalles de configuración de la aplicación.

En este ejemplo, esri.arcgis.utils.arcgisUrl va a parar a 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 solicitado sobre la aplicación, utilizando el panel de configuración. A continuación, puedes recuperar los cambios y aplicarlos a la aplicación. La aplicación debería definir los valores predeterminados de las opciones de configuración a fin de manejar las situaciones en las cuales la plantilla no se haya configurado.

{
    "source": "15a34e2c161b4364860854fbc84262c5",
    "folderId": "5705faa4594a4fd09edf01742c16e523",
    "values": {
        "webmap": "32f1438789d34b5e8125f0f7c64b8d63",
        "layer":"http://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 personalizada

Después de crear el archivo de configuración, estás listo para asociarlo todo con tu plantilla personalizada y hacer que la aplicación sea configurable. En primer lugar, si no lo has hecho ya, añade la plantilla como nuevo elemento de la Web Mapping Application en ArcGIS Online. Para obtener más información sobre cómo se añade un elemento a ArcGIS Online, consulta Añadir aplicaciones. A continuación, abre la página de detalles del elemento correspondiente a tu aplicación Web, haz clic en el botón Editar y copia y pega el código de JSON desde tu archivo de configuración al cuadro Parámetros de configuración situado al final de la página de detalles del elemento.

Haz que tu plantilla sea configurable añadiéndole la información del archivo de configuración dentro del campo Parámetros de configuración, dentro de los detalles del elemento de plantilla.

Ahora hay una sección de parámetros en el modo de Edición del elemento de aplicación Web de ArcGIS Online.

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 JSON Lint a fin de garantizar que tengas un JSON bien formateado y libre de errores.

Si quieres utilizar la plantilla configurable en la galería de plantillas de representación cartográfica en la red de tu organización o en una galería de plantillas de grupos, comparte el elemento con el grupo que se esté utilizando para las plantillas. A continuación, el administrador de tu organización puede configurar el mapa o configurar grupos para usar el grupo que incluya la plantilla.