Creating web application templates

To create your own custom web application template, you can download and modify one of the existing templates, update an existing web application to work with content from your portal, or build a new web application using one of the ArcGIS Web APIs. Regardless of how you create your own template, you'll work with URL parameters and web maps. You may work with groups if you are creating a group template and you might consider additional requirements for working with Bing base maps, accessing nonpublic maps, and working with resources that require a proxy or Cross-Origin Resource Sharing (CORS). You'll also add your item to your portal and, if your organization plans to use your template in its template gallery, share it with one of your organization's template groups.

Portal for ArcGIS includes version 3.7 of the ArcGIS API for JavaScript. There is no need to host your own API and point the portal at the local version; the web application templates automatically reference the installed API. The locally installed API is typically available at https://webadaptor.domain.com/arcgis/jsapi/jsapi.

Caution:

Do not alter the web application template files that are provided with Portal for ArcGIS, 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.

This topic covers how to create a web application template. Once you've created your template, you can make it configurable. Configurable templates let users customize the appearance and behavior of the application. For more information about creating configurable templates, see Adding configurable parameters to templates.

URL parameters

When you use a template, you specify which web map or group to display by including the webmap or group ID as a parameter in the template URL. Web map IDs are specified using the webmap parameter, and group content is specified using the group parameter. In order for your custom template to work with the current web map or group, you need to include code in the application to extract the current web map or group id from the URL. For more information about web map parameters, see Using URL parameters.

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

To do this, start with the Basic Viewer URL:

http://www.arcgis.com/apps/OnePane/basicviewer/index.html

Copy the webmap= part of the Europe Basemap URL:

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

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

http://www.arcgis.com/apps/OnePane/basicviewer/index.html?webmap=5421a40574914458892efe74f0149025

The JavaScript API 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 application is configurable you will also need to handle a URL parameter named appid which defines the configuration settings. For more information about setting up the template to read the configuration file, see Adding configurable parameters to templates.

Web maps

Web map templates are designed to work with the currently displayed web map in the map viewer. Templates typically create a map based on the web map specified in the web map URL parameter. Each of the web API’s have 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.

Learn more about the Map class

Group

Group templates display content from the specified group as an application. For more information about creating gallery applications, see Creating applications with groups.

The 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://webadaptor.domain.com/arcgis/');
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

Templates 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 web maps you want to display use a Bing Maps basemap, you will need to include a Bing Maps key in your application. The Bing Maps key is provided as a parameter to the createMap method.

Identity Manager

The Identity Manager simplifies the process of working with secure resources. It handles the process of prompting the user for their credentials, generating a token, and appending it to the resource. By including the Identity Manager class in your template application, the template will work with public and private web maps.

Include the following line of code in your application to enable IdentityManager:

dojo.require("esri.IdentityManager");

Learn more about Identity Manager

Note:

You also need to configure SSL on the web server that hosts your application.

Proxy and CORS support

If your application will be making cross-domain requests, you will need to enable Cross-Origin Resource Sharing (CORS) or add a proxy to your application.

Adding the template to your portal

Once you've created the template and hosted it on your web server, add the template to your portal as a web mapping application item and specify the URL to the application. For the purpose, choose Configurable. For the API, choose JavaScript. For more information about adding applications on your portal, see Adding applications.

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

Using the template in your organization's gallery

If you want to use the 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.