Skip To Content

Create app templates

To create your own custom web app template, you can download and modify one of the existing configurable apps, update an existing app to work with content from ArcGIS Online, or build a new app using one of the ArcGIS Web APIs. Regardless of how you create your own app, you'll work with URL parameters and maps. You may work with groups if you are creating a group-based app 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). You'll also add your item to ArcGIS Online and, if your organization plans to use your template in one of its app galleries, share it with one of your organization's app groups.

Tip:

For a starter app that includes all the code you need to build an app, download the Application Boilerplate on GitHub.

This topic covers how to create a web app template. It assumes you have privileges to create content and share to groups in your organization. Once you've created your template, you can make it configurable. Configurable templates allow users to customize the appearance and behavior of the app.

URL parameters

When you use a template, you specify which 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/OnePane/basicviewer/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/OnePane/basicviewer/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 will also need to handle a URL parameter named appid, which defines the configuration settings.

Web maps

App templates are designed to work with the currently displayed map in Map Viewer. 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.

Register the app template

If you are working with secure items in your app template, you will first want to register them with the platform. To do this, add a new Web Mapping Application item and set the URL to the app template hosted on your web server.

After you add your items, you need to register the app. Since this is a web app, keep the type set to Browser with the Redirect URI pointing to the template app URL.

Once you register your app, you should now have a unique app ID.

If you are using the Application Boilerplate template, set the configurable oauthappid property in the config/defaults.js file.

//sample

 "oauthappid": “h4xZWhfz0an0TvqC"

If you are not using the Application Boilerplate template, you need to work with the Identity Manager so that it recognizes the registered app ID. For more information, see the OAuth Basic and OAuth Popup samples.

Group

Group templates display content from the specified group as 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('http://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 different 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 the template to ArcGIS Online

Once you've created the template and hosted it on your web server, add the template to ArcGIS Online as a web app item and specify the URL to the app. For the purpose, choose Configurable. For the API, choose JavaScript. You can also add the item through ArcGIS REST API .

Be sure to include a descriptive title and summary because this information is displayed when users hover over the thumbnail in the app gallery. Optionally, you can create a ZIP file that contains your app files and attach it to the item to provide download capability.

Use the template in your organization's app gallery

If you want to use the template in your organization's Map Viewer app gallery or group app gallery, share the item to the group being 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.