Skip To Content

Create app templates

To create your own custom web app template, you can download and modify one of the existing 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 template, you'll work with URL parameters and maps. You may work with groups if you are creating a group 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).

Once you've created your web app template, you can add your app item to your portal. If your organization plans to use your template in one of its app galleries, you can also share it with one of your organization's template groups. To allow users to customize the appearance and behavior of your custom web app, you can make it configurable.

Portal for ArcGIS includes ArcGIS API 3.15 for JavaScript. There is 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 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 app template. It assumes you have privileges to create content and share to groups in your organization.

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

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.

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

Group

Group templates display content from the specified group as 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 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

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

Add 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 app item and specify the URL to the app. For the purpose, choose Configurable. For the API, choose JavaScript.

Be sure to include a descriptive title and summary because this information is displayed when users hover over the template item in the template 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.