esri/application-boilerplate-3x-js

Starter application that simplifies the process of building templates for the ArcGIS.com template gallery.

ArcGIS Configurable Apps will be retired in 2025. The ArcGIS Configurable Apps source code repro is deprecated and will not receive further updates. In addition, this repository will be removed in October 2025, along with the October 2025 ArcGIS Online update.

Looking for 4.x? See the ArcGIS JS API Base Class

application-boilerplate-js

The Application Boilerplate is a starter application for building custom templates with the ArcGIS API for JavaScript.

Features

This bare-bones app includes all the code you need to build an ArcGIS Online template. It will save you time when:

• Making an ArcGIS Online compatible template.
• Using your ArcGIS Online webmap to power the template.
• Localizing your application in different languages.
• Capturing URL parameters and using them in your application.
• Using settings from your ArcGIS Online organization or configured application.
• Enabling your application to sign-in to ArcGIS Online using OAuth 2.0.

View it live

Getting Started

Review the following ArcGIS.com help topics for details on Templates:

• Writing your first application
• Make your first app
• Create apps from maps
• Add configurable parameters to templates

Folders and Files

The template consists of the following folders and files:

/config/: A folder for your application's configuration files.

• defaults.js: Define the default configuration information for the template. You can use this file to specify things like a default web map id, a proxy url, default services, a Bing maps key, default color theme and other template-specific settings.

• templateConfig.js: Options file for configuring your template to query for specific resources and items. You can edit this file and your template can enable or disable querying for things such as localization files, ArcGIS group information, group items, custom url parameters, etc.

• demoMap.js: This map file can be used as a substitute for an arcgis.com hosted webmap. It contains webmap JSON that can be used to configure a map locally. To use this file instead of an online hosted webmap, set the useLocalWebmap option to true in templateConfig.js. Make sure the option localWebmapFile is pointing to this file location.

/css/: Contains the CSS files for the application.

• main.css This file contains the map styles that set the margin, padding and initial height (100%).

/images/: Contains images used by the application.

/js/: Contains JavaScript files:

• /nls/: The nls folder contains a file called resources.js that contains the language strings used by the application. If the application needs to be supported by multiple locales you can create a folder for each locale and inside that folder add a resources.js file with the translated strings. See the resources.js file in the nls/fr folder for an example of this in French.
• main.js: Creates the map based on configuration info. You will write all your main application logic in here.
• template.js: Module that takes care of "template"-specific work like retrieving the application configuration settings by appid, getting the url parameters (web map id and appid), handling localization details and retrieving organization specific info if applicable. You will most likely not need to modify this file. Also sets the proxy and geometry service if the url's have been provided in the defaults.js file or are available from the org. Once executed you'll have access to an object that contains properties that give you access to the following:
  • Template specific properties
  • appid
  • webmap
  • helperServices: geometry, print, locator service urls
  • i18n: Strings and isRightToLeft property that can be used to determine if the application is being viewed from a language where text is read left-to-right like Hebrew or Arabic.
  • proxy url

index.html: The default html file for the application.

/resources/: Contains helpful files for your application.

• resources/configurationPanel.js Default configuration panel settings for the template. This is only applicable to configurable templates. This example will create a configuration panel with one dropdown list that contains three template color choices (seaside, chrome, pavement). When the templateConfig.js module retrieves any configurable settings you'll get the theme name back in a parameter named theme. Then you can apply the necessary css to your application to apply the new colors - like change the border color etc. See the Adding configurable parameters to templates help topic for more details.

Instructions

1. Download and unzip the .zip file or clone the repository.
2. Web-enable the directory.
3. Access the .html page.
4. Start writing your template!

New to Github? Get started here.

Deploying

1. To deploy this application, download the template from Portal/ArcGIS Online and unzip it.
2. Copy the unzipped folder containing the web app template files, such as index.html, to your web server. You can rename the folder to change the URL through which users will access the application. By default the URL to the app will be http://<Your Web Server>/<app folder name>/index.html
3. Change the sharing host, found in defaults.js inside the config folder for the application, to the sharing URL for ArcGIS Online or Portal. For ArcGIS Online users, keep the default value of www.arcgis.com or specify the name of your organization.

• ArcGIS Online Example: "sharinghost": "https://" + “<your organization name>.maps.arcgis.com
• Portal Example where arcgis is the name of the Web Adaptor: "sharinghost": "https://" + "webadaptor.domain.com/arcgis"

4. If you are using Portal or a local install of the ArcGIS API for JavaScript, change all references to the ArcGIS API for JavaScript in index.html to refer to your local copy of the API. Search for the references containing "https://js.arcgis.com/3.13" and replace this portion of the reference with the url to your local install.

• For example: "https://webadaptor.domain.com/arcgis/jsapi/jsapi" where arcgis is the name of your Web Adaptor.

5. Copy a map or group ID from Portal/ArcGIS Online and replace the default web map ID in the application’s index.html page. You can now run the application on your web server or customize the application further.

Note: If your application edits features in a feature service, contains secure services or web maps that aren't shared publicly, or generate requests that exceed 200 characters, you may need to set up and use a proxy page. Common situations where you may exceed the URL length are using complex polygons as input to a task or specifying a spatial reference using well-known text (WKT). For details on installing and configuring a proxy page see Using the proxy. If you do not have an Internet connection, you will need to access and deploy the ArcGIS API for JavaScript documentation from developers.arcgis.com.

Requirements

• Text or HTML editor.
• A little background with JavaScript.
• Experience with the ArcGIS JavaScript API would help.

Resources

• Community
• ArcGIS for JavaScript API Resource Center
• ArcGIS Blog
• twitter@esri

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing

Copyright 2013 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's license.txt file.

[](Esri Tags: ArcGIS ArcGIS Online Web Application boilerplate template widget dijit Esri JavaScript application) [](Esri Language: JavaScript)

application-boilerplate-3x-js's Issues

Get oAuth callback working

Locally hosted template incorrectly overrides helperServices in default.js

When this template is hosted locally the helperServices settings in default.js are incorrectly overridden in template.js _mixinAll function.

Require webscene and webmap and pass back the class

Require webscene and webmap and pass back the class

4.x: Use JSON instead of dojo object

Is there any chance we can use JSON instead of a dojo to describe the app configuration for the 4.x version of the boilerplate? It looks like the webmap version is already taking that approach anyhow.

https://github.com/Esri/application-boilerplate-js/blob/master/application_boilerplate/config/demoMap.js
vs
https://github.com/Esri/application-boilerplate-js/blob/4.0master/webscene_application_boilerplate/config/demoScene.json

@kellyhutchins @driskull

Return createMap deferred from startup.

Return the createMap deferred from main.startup()
It is useful to have a the startup() function return a Deferred
so that calling code can wait for the webmap to load before
adding application-specific functionality to the map.

Issue originated in map tools repo:
https://github.com/Esri/map-tools-template/pull/9/commits

Design error page

@kellyhutchins can you work with @asangma to get a design for the template error page?

Abstract main.js functions into class

Abstract main.js functions into class app.js?

GroupID Configured from App values is not honoured in boilerplate

HI @driskull ,

GroupID Configured from App values is not honoured in boilerplate.
This can be fixed by adding following code in the method _queryApplicationConfiguration in template.js at line #382

//Get the groupID from the app values
if (response.itemData.values.group !== "") {
 this.config.group = response.itemData.values.group;
}

Support locally hosted webmap

Support locally hosted webmap in the boilerplate.

cc @kellyhutchins

4x enh: strong decoupling between boilerplate and app that uses it

The boilerplate main program does necessary app setup (setting direction, creating the webmap/webscene/group gallery), but is subject to change as the JSAPI evolves. If the boilerplate's main file includes the app's customizations, it can be difficult to re-graft an app onto the updated boilerplate--a careful line-by-line merge is required.

The proposed enhancement separates the main file into two main files:

• the boilerplate's main, responsible for its current activities
• the app's main, responsible for app-specific setup and running

The boilerplate main would be coupled as little as possible with the app's main; so far, a single entrypoint has been sufficient for a 3D 4.x app: a run function that's called after the dom, map (WebMap or WebScene), and view (MapView or SceneView) are ready and resolved; this function is given the boilerplate's config object, the map, and the view. (I've not explored what the run function should be like for group apps.)

Two other entrypoints might be useful. For both, if the app's main provides the function, it's called; otherwise, the boilerplate runs as it does now.

• an initialization function that provides the boilerplate's config object to the app to permit it to tweak the config before the webmap/webscene/group gallery is created
• a notification function for the notification part of the boilerplate's main file's reportError function

It does not appear to be necessary to add the i18n resources to the config object or the run() signature: the app's main file can simply include the i18n invocation without incurring another network fetch because the boilerplate's main program has already loaded the i18n resources.

With this setup, if the boilerplate very rarely changes the contract between the two main files, it becomes possible to re-graft an app onto an updated boilerplate in the time it takes to copy files.

Strip HTML from url parameters

Strip html from url parameters to avoid raising flags when app is checked for xss problems.

Dbl click causes a strange "flash/jump"

When viewing the map here in Chrome: http://esri.github.io/application-boilerplate-js/application_boilerplate/

I see a strange "jump" or "flash" thats hard to describe. If you double click on the map you see the issue.

I also see it when clicking on zoom in/out buttons.

Add an "error" event for the Template class

The Template class uses Deferreds that get resolved but when something fails there is no way to report that. My app needs to know when there was an error to stop the loading spinner and display the error. It would be nice if the Deferreds were rejected on error and a 'error' event was emitted. @kellyhutchins What do you think?

4 spaces instead of tabs

Currently the code has a mix of spaces and tabs, I think it would be better if all tabs would be replaced with spaces.
Currently some lines use both spaces and tabs, e.g. https://github.com/Esri/Application-Boilerplate/blob/master/application_boilerplate/index.html#L37-L45

Clean up bingmapskey vs bingkey

Clean up bingmapskey vs bingkey.

Ability to pass in config object like the settings from index

Ability to pass in config object like the settings from index

Upgrade to support reading units from the self call.

More documentation for the esriEnvironment

More documentation for the esriEnvironment to false. Explain what it is and when to set it. More clear documentation.

Do we still need commonConfig file?

@kellyhutchins Do we still need commonConfig file? Would there be a better way to do this via some rest service?

GroupID Configured from Application configuration panel is not honoured in Boiler Plate

Hi @driskull,

@MikeTschudi , @NikkiGolding , @ScottOppmann

If a group template has a default group configured in default.js, then we are seeing that the boiler plate fetches groupinfo and groupitems of this default group even after publishing an app and changing the group using application configuration panel(Displayed on right hand side).

This is occurring since in the code (located at line no 115 in "template.js") all the configs are mixed after getting group info and group items.

So to fix this issue can we mixin "this.config", "this.commonConfig", "this.appConfig" once the app config is available at line no 100 in "template.js".

We have added this code lang.mixin(this.config, this.commonConfig, this.appConfig); at line 100 in template.js and it is solving the issue.
Should I send a pull request?

Please let us know if we are missing something obvious.

Thanks,
Sumit Zarkar

Update loading spinner

4.1: IdentityManager console error

Good news: The IdentityManager is styled and no other .css refs are required. Yeah!
Bad news: IdentityManager is throwing a console error in the boilerplate.js.

Just swap the 4.0 refs to 4.1 and you should see:

init.js:153 Error: User is not signed in.(…) "Error: User is not signed in.
    at Error (native)
...

4x boilerplate: Add support for reading app values from local storage

I'd like to add support for reading app values from local storage so we can take advantage of this capability in the app config panel. If the app was able to read app values from local storage we'd be able to support live preview and undo/redo capability in the default template config panel.
The app could use the values from app storage to provide live preview and then once the save button was hit on the config panel we'd write out the appid and clear local storage.

@driskull thoughts?

Update template.js to prompt for log-in before we retrieve org specific settings

Update template.js to prompt for log-in before we retrieve org specific settings. In cases where the web map is not public we needed to prompt for log-in before retrieving org specific settings to ensure that settings were retrieved for the logged in user.

Modify the way the template.js code checks to see if app is hosted.

Currently we check if the apps are located in a folder with app or home. This is brittle and causes issues for downloaded apps deployed in location with those folder names.

Add support for reading extent set by application item

Get only items with type="Web Map" in group

I want to get only items with type="Web Map" in group, I don't see any options to change the query in groupParams. Where should i update the parameter to get only webmaps.

Add option to specify getting either webmap item or group item

broken link in readme

The "About web application templates" link in the Getting Started section points to a broken link.

Use Meriyo font for Japanese

Request submitted:
Would it be possible to change default font to "meiryo"? Or technically speaking, our request is to add "meiryo" font as first font-family like "font-family: meiryo, Arial, Helvetica, sans-serif;".

Possible option
http://www.w3.org/International/questions/qa-css-lang

Allow ordering of the mixin from templateConfig.js

Some users may want to mixing resources differently. Should we allow this by a configuration option in templateConfig.js?

Add webmap option to configuration panel

4x boilerplate sanity check

Could you go over the 4x boilerplate in the "4master" branch and provide feedback on:

• Layout, structure, and organization
• Naming of things
• Code quality
• Readme.md documentation

If anything doesn't make sense, needs additional documentation or is missing anything... _Just add it!_

https://github.com/Esri/application-boilerplate-js/tree/4master

Standardize support for url params

Add a new class that handles supporting map params like center, zoom, level, extent.

4: Identity dijit needs 3.x reference

I know this will be fixed soon but if you want styling for the identity manager to login, you'll need this stylesheet from 3.x:

<!DOCTYPE html>
<html>

<head>
  <meta charset="utf-8">
  <!-- Define the versions of IE that will be used to render the page. See Microsoft documentation for details. Optional. -->
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <!-- Responsive -->
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
  <meta name="mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-status-bar-style" content="default">
  <!-- End Responsive -->
  <!-- Use protocol relative urls that way if the browser is viewing the page via HTTPS the js/css file will be requested using the HTTPS protocol -->
  <link rel="stylesheet" href="//js.arcgis.com/4.0/esri/css/main.css">
  <!-- Load any application specific styles -->
  <link rel="stylesheet" href="css/boilerplate.css">

  <!-- Calcite - only for IdentityManager -->
  <link rel="stylesheet" href="https://js.arcgis.com/3.17/esri/themes/calcite/dijit/calcite.css">

</head>

<body class="calcite boilerplate--loading">
  <div class="boilerplate-loading-indicator">
    <div class="boilerplate-loading-message" id="loading_message"></div>
  </div>
  <div id="viewDiv" class="boilerplate-view"></div>
  <script type="text/javascript" src="js/dojoConfig.js"></script>
  <script type="text/javascript" src="//js.arcgis.com/4.0/"></script>
  <script type="text/javascript">
    require([
      "boilerplate",
      "dojo/text!boilerplate/settings.json",
      "application"
    ], function (
      Boilerplate,
      boilerplateSettings,
      applicationMain
    ) {

      // create my main application. Start placing your logic in the main.js file.
      var mainApp = new applicationMain();

      // create the template. This will take care of all the logic required for template applications.
      new Boilerplate(JSON.parse(boilerplateSettings)).always(function (boilerplate) {
        mainApp.init(boilerplate);
      });

    });

  </script>
</body>

</html>

4x boilerplate: Support shared theming

Add support for shared theming to the 4x boilerplate.
https://github.com/SpatialAgent/local-perspective/pull/28/files

Sample theme: https://opendatadev.arcgis.com/api/v2/sites/594

Should template.js be put in the API?

Should template.js be put in the API? It may make sense at some point.

cc @jbartley @kellyhutchins

Changing group from configuration panel has no effect

@driskull
Steps to reproduce:

1. Share group "A" using a gallery template app
2. Open configuration panel, it correctly displays group "A" that was used to publish the app
3. Now change the group to "B" using configuration panel
4. Notice that the app reloads and shows group "B"
5. Click Save and Done and launch the app again from the app item
6. Notice that the app launches and displays group "A" instead of group "B"
7. Changing the group has no effect

We see that when a gallery app is published, the app url contains the groupid of the group that was used to publish the app. When a different group is chosen using the configuration panel, it is saved to app configuration. However, the app url still retains the original groupid that was used to publish the app. Hence, when the app launches, boilerplate gives highest priority to URL parameters and ignores the groupid that was saved to app configuration.

We don't think this is a boilerplate issue, since we are of the opinion that url parameters must always be given highest priority. What would be ideal is that the configuration app (configureApp.html) should update the app url with the new groupid when the group is changed.

Please suggest a solution or a workaround that will reflect the changed group.

document boilerplate class API

document boilerplate class API

Save organization's default basemap group

@kellyhutchins Let me know if you want me to do this. 👍

Create 4.x helper class for URL params

Create a 4.x helper class to convert all the common url params like extent and such to their appropriate classes. In the 3x boilerplate, this was called map params.

I think in the new boilerplate it should be called urlHelper or something similar since it will work for scene and webmap.

Add configuration boolean option for when the template is hosted/used in portal vs not

Instead of looking for /apps in the URL, there should be a configuration option that can be enabled when the template is hosted or in portal.

Update to use editable option of arcgis/utils/createMap

@driskull

Add support for boolean url parameters to template.js

Many of the url params I use in templates are boolean but when retrieved as url params they are strings. I think we should add some logic into the _getUrlParamValues function to handle the conversion. Something like this?

var item = urlObject.query[items[i]];
obj[items[i]] = item === "true" || (item == "false" ? false : item);

@driskull thoughts?

Webmap JSON editing tool to edit webmap

Webmap JSON editing tool to edit webmap

'on' is not defined

small issue in js/main.js:

JSHint notes: "'on' is not defined." Line 49.

define(["dojo/on"],function(on){...

Approach to get GroupInfo of the Private Group

@driskull ,

When using boilerplate for developing a gallery app, we see that it does not get the group info and does not invoke identity manager too in case of private groups.

It is required in our case to show the identity manager on app load, hence we are invoking it after boilerplate runs. As the group is private, and boilerplate did not provide the detailed group info, we want to now get the group info again after user signs in.

We are able to get the groupInfo by using method _queryGroupInfo(). However, we think this is a private method of the boilerplate.

Please suggest if this approach is OK.

getViewProperties() shouldn't take string array

We might not want to depend on splitting an incoming string for ui components because UI doesn't support loading all widgets (components) by string - just zoom, compass and attribution. Furthermore, the location e.g. top-right of the ui component should also be passed in so I think we need to re-think this structure.

https://github.com/Esri/application-boilerplate-js/blob/4master/js/boilerplate/UrlParamHelper.js#L56

Here's how I handle it in config.json and and use main.js to set up the UI.

{
  "appid": "",
  "group": "",
  "title": "",
  "subtitle": "",
  "about": "",
  "webmap": "de5fe9b1be9b43a9aa195164438b557f",
  "webscene": "",
  "uiComponents": {
    "zoom": {
      "visible": true,
      "position": "top-left"
    },
    "attribution": {
      "visible": true,
      "position": "top-left"
    },
    "search": {
      "visible": true,
      "position": "custom"
    }
  },
...

Issue when appID is set in default.js, not in url

template.js
_queryApplicationConfiguration functions

if (!esriLang.isDefined(webmapParam.webmap) && response.itemData.values.webmap && this.config.webmap)
{
this.config.webmap = response.itemData.values.webmap;
}

Command Window of the values:

? response.itemData.values.webmap
"40f993fccee34ebb9e9c1c6ecc9bf9fb"
? this.config.webmap
""
? esriLang.isDefined(webmapParam.webmap)
false

After signing in, the call to groupInfo() always looks for the group in the same organization where app is published

@driskull,

When we publish a gallery app based on boilerplate and configure a group that is public but from a different organization then we see that,

1. If you do not sign in, everything works fine
2. If you sign in, then it doesnt find the group

This is because after signing in, the call to groupInfo() is automatically appending the orgId in the query parameters and thus trying to look for that group in the same organization.

This is what gets sent before signing in and it finds the group despite it being from different organization

This is what gets sent after signing in and it doesnt find the group inspite it being public. Notice the orgid appended in the query parameters