Adding configurable parameters to templates
Configurable web application templates let users customize the appearance and behavior of an application. Making a template configurable is a four-step process:
- If you haven't already done so, create a web application template. For full instructions, see Creating web application templates.
- Create a configuration file.
- Set up the template to read the configuration properties and apply them to the application.
- Associate the configuration file with the item for your custom template.
To get started, see the sections below.
Create a configuration file
The configuration file is a JSON file that defines the input dialog for the template. This file contains one or more sections that categorize the customization options.
The fieldName property must be unique inside the configuration setting.
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.
Field type | Description |
|---|---|
Paragraph | Displays explanatory text in the configuration dialog box. |
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. Textbox is the default and is a single line text box. Text area displays a larger text box for entering data. Rich text displays a rich text editor that allows users to apply some formatting, such as setting the font to bold or italic to the text. |
Boolean | Creates a check box for specifying true or false values. |
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. Learn more about creating constraints with Dojo NumberTextBox |
Options | Creates a drop-down list with a series of choices. |
Example configuration file
Below is an example of a complete configuration file and the resulting configuration panel.
{
"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
}
}
 |
The resulting configuration panel for the example code |
Setting up the template to read the configuration file information
If the template is going to be configurable, then the application will need to accept an application ID as a URL parameter. This application ID (appid) is used to make an asynchronous request to retrieve the configuration properties for the application. In the ArcGIS API for JavaScript, you can use esri.request to retrieve the application 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 application using the configuration panel. You can then retrieve the changes and apply them to the application. The application 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":"http://sampleserver6.arcgisonline.com/arcgis/rest/services/Water_Network/MapServer/2",
"theme": "green",
"orgname": "Water Points",
"bufferdistance": 3
}
}
Associating the configuration file information with the item for your custom template
After you've created your configuration file, you are ready to associate it with your custom template and make the application configurable. First, if you haven't already done so, add the template as a new web mapping application item in ArcGIS Online. For more information on adding an application, see Adding applications. Then open the item details page of your web application, click the Edit button, and copy and paste the JSON code from your configuration file into the Configuration Parameters box at the bottom of the item details page.
 |
Make your template configurable by adding the configuration file information into the Configuration Parameters field of the template item details. |
A configuration parameters section is now available in the Edit mode of the web application item.
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.
If you want to use the configurable template in your organization's web mapping template gallery or group template gallery, share the item to the group being used for the templates. Then the administrator of your organization can configure the map viewer or configure groups to use the group that includes your template.