Back to Top

Create configurable app templates

In this topic

  1. Create and configure a web app template
  2. Add your template to ArcGIS Online
  3. Make your app configurable
  4. Feature your template in your organization's gallery

If you have privileges to create content, you can create a custom app template hosted on your web server. Once the custom app template is created and configured, make your app discoverable in ArcGIS by adding the template to ArcGIS Online. You can then make the app configurable to allow customizing its appearance and behavior. If your organization plans to feature your template in one of its galleries, you can share the template with an app template group.

Create and configure a web app template

To create a custom web app template, you can download and modify one of the existing ArcGIS Configurable Apps templates, update an existing web app to work with content from ArcGIS Online, or build a new web app using the code in a starter app you can download from GitHub.

Regardless of how you create the app, you'll work with URL parameters and maps. You may work with groups if you are creating a group-based app template, and you might consider additional requirements for working with Bing Maps basemaps, accessing nonpublic maps, and working with resources that require a proxy or Cross-Origin Resource Sharing (CORS).

After you create an app template, host it on your web server.

URL parameters

When you use a template, you specify the map or group to display by including the webmap or group ID as a URL parameter in the template. Web map IDs are specified using the webmap parameter, and group content is specified using the group parameter. For your custom template to work with the current map or group, you need to include code in the app to extract the current web map or group ID from the URL.

For example, you could display the Europe Basemap map in the Basic Viewer template.

To do this, start with the Basic Viewer URL:

https://www.arcgis.com/apps/View/index.html

Copy the webmap= part of the Europe Basemap URL:

https://www.arcgis.com/home/webmap/viewer.html?webmap=5421a40574914458892efe74f0149025

And add it to the end of the Basic Viewer URL:

https://www.arcgis.com/apps/View/index.html?webmap=5421a40574914458892efe74f0149025

ArcGIS API for JavaScript has a helper method esri.urlToObject that simplifies this process. This method converts the URL parameters to an object.

var webmap;
var urlObject = esri.urlToObject(document.location.href);

Once you have the URL parameters as an object, you can access the various inputs. For example, you could assign the value for the web map URL parameter to a variable named webmap_id.

var webmap_id = urlObject.query.webmap;
Note:

If the app is configurable, you also need to handle a URL parameter named appid, which defines the configuration settings.

Web maps

Note:

This functionality is only supported in Map Viewer Classic.

App templates are designed to work with the currently displayed map in Map Viewer Classic. Templates typically create a map based on the web map specified in the web map URL parameter. Each web API has a helper method that creates a map using information from the web map ID. For more information about using APIs to work with web maps, see ArcGIS API for JavaScript.

For example, you could use the ArcGIS API for JavaScript esri.arcgis.utils.createMap method to create a map based on the input ID. You could also include a callback function that executes when the synchronous request to esri.arcgis.utils.createMap is complete.

esri.arcgis.utils.createMap(webmap,"map",{
   mapOptions:{
     slider:false
   },
   bingMapsKey:bingMapsKey
}).then(function(response){
    map = response.map;
});
Note:

If any of your web maps include a Bing Maps basemap, you will need to specify a Bing Maps key when using the createMap method. There are several other map options you can specify, such as whether to display the slider, navigation, attribution, and more.

The callback function provides access to a response object that provides access to the map object, layers, and more. For more information about the Map class, see ArcGIS API for JavaScript.

Group

Group templates display content from the specified group in an app.

ArcGIS REST API provides access to content from ArcGIS Online. You can use it to retrieve group content based on the input group ID. For more information about working with ArcGIS REST API, see ArcGIS REST API overview.

In this example, you perform a query to find a group with the input ID.

var portal = new esri.arcgis.Portal('https://www.arcgis.com');
dojo.connect(portal, 'onLoad',function(){
    portal.queryGroup(groupid).then(function(response){
        var group = response.results[0];
     });
});

Once you find the group, you can query to retrieve items from the group.

In this example, you query the group to find five items of type Web Map or Web Mapping Application.

var queryParams = {
    q: 'type:"Web Map" -type:"Web Mapping Application"',
    num: 5
 };
group.queryItems(queryParams).then(function(response){
    var groupItems = response.results;
});

Additional considerations

Web apps are typically designed to work with many types of content, so you may need to set up the template to handle maps with Bing Maps basemaps, nonpublic content, and so on. Specific considerations are listed below.

Bing Maps key

If any of the maps you want to display use a Bing Maps basemap, you will need to include a Bing Maps key in your app. The Bing Maps key is provided as a parameter to the createMap method.

Proxy and CORS support

Since your app will be making cross-domain requests to ArcGIS Online, you will need to enable CORS or add a proxy to your app.

Add your template to ArcGIS Online

Once you create a web app template and host it on your web server, make the app discoverable in ArcGIS by adding your template to ArcGIS Online.

Add the template as an app item

Add the template to ArcGIS Online as a web app item and specify the URL to the app. For Purpose, choose Configurable. For API, choose JavaScript.

Once you add the template, the template item appears in your content and you can edit its details. Be sure to include a descriptive title and summary because this information is displayed when users view this item in the configurable app gallery. Optionally, you can create a .zip file that contains your app files and attach it to the item to provide download capability.

Register the app template

After adding the app template as an item, you must register the app. Registering your app gives you a unique app ID. Use the app ID in your app to collect usage statistics and to allow users to sign in to the platform with OAuth 2.0, a standardized authorization framework. The app ID also allows your app to work with user content associated with the organization and work with other ArcGIS Online capabilities such as geocoding, routing, and GeoEnrichment.

When you register your web app template, set type to Browser with Redirect URI pointing to the template app URL.

If you're using the ApplicationBase template, set the configurable oauthappid property in the config/defaults.js file.

//sample

 "oauthappid": “h4xZWhfz0an0TvqC"

If you're not using the ApplicationBase template, you must work with the Identity Manager so that it recognizes the registered app ID. For more information, see the OAuth Basic and OAuth Popup samples.

Make your app configurable

To allow customizing the appearance and behavior of your web app, you can make it configurable. For example, you can allow users to change the app colors or customize other settings for the app.

Making your app configurable involves creating a configuration file and associating the configuration file information with the app template item you created.

Create a configuration file

The app configuration file is a JSON file that defines the configuration options for the app template. For example, the configuration file for the Basic Viewer app is configurationPanel.js and can be found in the resources folder of the Esri Basic Viewer repository. 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.

Do the following to create a configuration file:

  1. Create one or more sections by specifying a category and set of fields for each section.
    {
    "configurationSettings": [
        {
            "category": "",
            "fields": []
        }
    ]
}
  2. 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. For information about creating constraints with Dojo Number TextBox, see the Dojo documentation.

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

    Sample output

    range:0.5

    Date and time

    Creates a date selector with a choice of dates. 

    {
     "type":"date",
     "fieldName" : "startDate",
     "label" : "Start Date"
}

    Creates a time selector with a choice of times. 

    {
     "type": "time",
     "fieldName": "startTime",
     "label": "Start Time"
}

    Sample output (in ISO-8601 format) for date and time

    Start Date and Time: 1970-01-01T21:30:00.000Z

    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. Also provides a transparency slider and a no color option.

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

    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"

    Web Scene dialog

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

    {
   "type": "webscene"
 }

    Sample output

    webscene:"ab41c86a588748128e6f5d80990a2395"

    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.

    Note:

    If editOnly is set to true, the field list will only include editable fields.

     {  
               "label":"Select search layers and fields",
               "fieldName":"searchLayers",
               "type":"multilayerandfieldselector",
               "editOnly":true,  
               "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.

    Note:

    If editOnly is set to true, the field list will only include editable fields.

      {  
               "type":"layerAndFieldSelector",
               "fieldName":"tableLayer",
               "label":"Layer to display in table",
               "tooltip":"Layer to display in table",
               "fields":[  
                  {  
                     "multipleSelection":true,
                     "editOnly":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”
}

    Sample output

    “customUrlLayerZoomScale”: 12000

    ExtentMap

    Creates a selector with map center and zoom level options.

    {
   "type":"extentMap",
   "label": "Select center and zoom",
   "fieldName": "mapExtent"
}

    Sample output

    mapExtent: {
  level: 2,
  coords: {
     latitude: 51.304,
     longitude: -98.7231
     }
}

Associate the configuration information with the template item

After you create the configuration file, you must associate the JSON configuration information with the app template to make it configurable.

  1. On the item page of the app template, click the Settings tab and click the Web Mapping Application link at the top.
  2. In the Configuration Parameters box, paste the JSON code from your configuration file.
    Note:

    The Configuration Parameters box 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.

  3. Save your settings.

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

Feature your template in your organization's gallery

If you want to use your template in your organization's Configurable Apps gallery or group apps gallery, share the item with everyone and with the group used for that 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 and configure a web app template
  2. Add your template to ArcGIS Online
  3. Make your app configurable
  4. Feature your template in your organization's gallery