Back to Top

Create configurable app templates

In this topic

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

If you have privileges to create content, you can create your own custom app template. Once the custom app template is created and configured, make your app discoverable in ArcGIS by adding your template to your portal. You then have the option of making 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 your 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 your portal, or build a new web app using one of the ArcGIS Web APIs.

Regardless of how you create your 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).

The ArcGIS Enterprise portal includes ArcGIS API 3.37 for JavaScript at 10.9.1. There's no need to host your own API and point the portal to the local version for newly created app templates; the web app templates automatically reference the installed API. The locally installed API is typically available at https://webadaptorhost.domain.com/webadaptorname/jsapi/jsapi.

Caution:

Do not alter the web app template files provided with ArcGIS Enterprise, as these files are managed by the portal, and any alterations you make to them may be subsequently overwritten by the portal. If you want to customize templates, do the following:

  1. Make a copy of the existing template file you want to customize.
  2. Place the copy in a different location on disk.
  3. Customize the copy of the template.
  4. Add it to your portal as a new template.

Web maps

Note:

This functionality is only supported in Map Viewer Classic (formerly known as Map Viewer).

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

Group

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

ArcGIS REST API provides access to content from your portal. You can use it to retrieve group content based on the input group ID.

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

var portal = new esri.arcgis.Portal('https://webadaptorhost.domain.com/webadaptorname/');
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

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

Add your template to the portal

Once you've created your web app template, make your app discoverable in ArcGIS by adding your template to your portal.

Add the template as an app item

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

Once you've added your 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 your app template as an item, you must register the app. You can register the OAuth 2.0-based apps you develop. Registering your app with the portal provides you with an app ID. The app ID is the foundation for distributing apps and getting usage reports.

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

Work with the Identity Manager so that it recognizes the registered app ID. For more information, see the OAuth Basic and OAuth Popup samples included with ArcGIS API for JavaScript.

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

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

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

    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've created the configuration file, you must associate the JSON configuration information with your app template to make it configurable.

  1. On the item page of your 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 the portal
  3. Make your app configurable
  4. Feature your template in your organization's gallery