Back to Top

Add configurable parameters to templates

In this topic

  1. Create a configuration file
  2. Set up the template to read the configuration file information
  3. Associate the configuration file information with the item for your app template

Once you've created a web app template, you have the option of making it configurable. Configurable web apps allow users to customize the appearance and behavior of an app. Making an app template configurable is a four-step process:

  1. If you haven't already done so, create a web app template.
  2. Create a configuration file to define the configuration properties you want.
  3. Set up the template to read the configuration properties and apply them to the app.
  4. Associate the configuration file with the item for your app template.

Create a configuration file

The configuration file is a JSON file that defines the configuration options for the app template. See a complete example of a configuration file.

Note:

It’s a good practice to run your JSON code through a validator such as JSONLint to ensure that you have well-formed, error-free JSON.

The configuration file contains one or more sections that categorize the options.

Create each section by specifying a category and set of fields.

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

Specify the configuration options using the field types listed in the table below. When creating the configuration file, ensure that the fieldName property is unique within the configuration setting.

Field typeDescription

Paragraph

Displays explanatory text in the configuration dialog box.

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

String

Accepts text input. Includes the stringFieldOption property, which specifies the type of text box displayed on the screen. Values are textbox, textarea, and richtext. The textbox option is the default and is a single-line text box. The textarea option displays a larger text box for entering data. The richtext option displays a rich text editor that allows users to apply some formatting, such as setting the font to bold or italic to the text. 

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

Sample output

description:"Bike Accidents"

Boolean

Creates a check box for specifying true or false values. Use condition to see if the map contains the specified functionality. If the map doesn't meet the condition, the check box and label are not displayed in the configuration panel.

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

Sample output

tool_bookmarks:false

Number

Creates a field that accepts numeric values. If the field should only accept a specific range of values, you can use the constraints setting to restrict the input to a particular range of values or to format the input values. 

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

Sample output

range:0.5

Options

Creates a drop-down list with a series of choices.

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

Sample output

theme:"blue"

Color Picker

Displays a color picker for choosing a color from a palette, or to specify hex, rgb, or hsv values.

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

Sample output

selectionColor:"#829254"

Web Map dialog

Displays a dialog box to browse or search for a new map to display in the app. Optionally specify a condition to test the map. If the specified condition is not met, a validation message appears on the configuration panel confirming that the map doesn't meet the requirements. Valid conditions strings are as follows:

  • time—Map is time-enabled
  • edit—App has at least one editable layer
  • featurelayer—Map has at least one feature layer
  • filter—Map has an interactive filter defined
  • 4x—Map contains content that is not yet supported in version 4x of ArcGIS API for JavaScript
{
   “type”: “webmap”,
   “conditions”: [“time”, “edit”, “featurelayer”, “filter”, “4x”]
 }

Sample output

webmap:"739ef0cf75de432995c77dd44ec8f652"

Group dialog

Displays a dialog box to browse or search for a new group to display in the app.

{
   "type": "group"

 }

Sample output

group:"449d00a4478d4849bbb65612355d6cd1"

Multiple Layer and Field Selector

Presents a tree view of the layers and fields in the map that match the supported types and geometry types. Allows app end users to select multiple layers and multiple fields for each layer.

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

Sample output

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

Layer and Field Selector

Displays a drop-down list of layers in the map filtered by the listed types and geometries. Optionally specify one or more field selectors to allow users to select a layer and fields. 

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

Sample output

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

Radio

Creates a radio button where only one option can be selected at a time. The selected option will be set to 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
   }]
 }

Sample output

customLayout:"fullmap"

Basemaps

Displays a drop-down list of all the named Esri basemaps.

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

Sample output

my_basemap:"satellite"

Conditional

Displays or hides content based on a true or false condition. For example, if a Display layer list check box is unchecked, the layer list and all related options (for example Include sublayers in layer list) are hidden. 

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

Search

Configures a search pane for finding features within a field of a feature layer or addresses using a locator. If you configure a feature search, users can choose the feature layer and search fields.

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

Sample output

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

Displays a list of predefined scale levels a user can choose from. For example, Countries, States, State, Counties, County, Metro, City, Town, Neighborhood. 

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

Example output

“customUrlLayerZoomScale”: 12000

Example configuration file

The following is an example of a complete configuration file:

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

Set up the template to read the configuration file information

To make the template configurable, the app must accept the item ID for a Web Mapping Application as the value for the appid URL parameter. This ID is used to make an asynchronous request to retrieve the configuration properties for the app. In ArcGIS API for JavaScript, you can use esri.request to retrieve the app configuration details.

In this example, esri.arcgis.utils.arcgisUrl resolves to 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];
      }
    }, 
});

The response will include the changes the user made to the app using the configuration pane. You can then retrieve the changes and apply them to the app. The app should define default values for the configuration options to handle situations where the template is not configured.

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

Associate the configuration file information with the item for your app template

After you've created your configuration file, you're ready to associate it with your custom app template and make the app configurable.

  1. If you haven't already done so, add the app template as a new app item.
  2. On the app template's item page, click the Settings tab and find the Web Mapping Application section.
  3. From the Purpose drop-down menu, select Configurable.
  4. In the Configuration Parameters field, paste the JSON code from your configuration file.
    Note:

    The Configuration Parameters field requires valid JSON. It’s a good practice to run your JSON through a validator such as JSONLint to ensure that you have well-formed, error-free JSON.

  5. Click Save to save your settings.

If you want to use the configurable template in your organization's Map Viewer app gallery or the group app gallery, share the item to the group being used for that app gallery. Then the administrator of your organization can configure the map or configure groups to use the group that includes your template.

Feedback on this topic?

In this topic
  1. Create a configuration file
  2. Set up the template to read the configuration file information
  3. Associate the configuration file information with the item for your app template