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:
- If you haven't already done so, create a web app template.
- Create a configuration file to define the configuration properties you want.
- Set up the template to read the configuration properties and apply them to the app.
- 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 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. 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. Sample output |
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. Sample output |
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. Sample output |
Options | Creates a drop-down list with a series of choices. Sample output |
Color Picker | Displays a color picker for choosing a color from a palette, or to specify hex, rgb, or hsv values. Sample output |
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:
Sample output |
Group dialog | Displays a dialog box to browse or search for a new group to display in the app. Sample output |
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. Sample output |
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. Sample output |
Radio | Creates a radio button where only one option can be selected at a time. The selected option will be set to true. Sample output |
Basemaps | Displays a drop-down list of all the named Esri basemaps. Sample output |
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. |
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. Sample output |
ScaleList | Displays a list of predefined scale levels a user can choose from. For example, Countries, States, State, Counties, County, Metro, City, Town, Neighborhood. Example output |
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.
- If you haven't already done so, add the app template as a new app item.
- On the app template's item page, click the Settings tab and find the Web Mapping Application section.
- From the Purpose drop-down menu, select Configurable.
- 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.
- 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.