The app.json file

The app.json file is structured as follows:

{
  // the name of the app (optional)
  "appName": "traffic",

  // properties section (optional)
  // used to transport metadata
  "properties" : {
    "<propertyname>" : <value>,
  ...
  },

  // load section used to manipulate the loading behavior of an app
  "load": {
    "<propertyname>" : <value>
    ...
  },

  // bundles section used to overwrite or add any property defined by components in the manifest.json file of bundles
  "bundles": {
    "<bundle name>":{
      "<component name>": {
      "<propertyname>" : <value>
      },

      "<factory component name>": [
    {
      "<propertyname>" : <value>
      },
    ...
    ],
    ...
    },
  ...
  }
}

properties

The "properties" section is optional and used to transport metadata.

You can, for example, access all values of the properties section directly in template.html files using the appProps variable:

Access properties values in template.html

<div ... >
  <div ...>${appProps.title}</div>
</div>

title

App title picked up by the design template (optional).

Example: "title" : "${apptitle}"

logging

Overwrites the globally configured log level in an app (optional).

Use this property to control the detail and amount of log messages that are printed to the browser console. The value must be one of DEBUG, INFO, WARN, ERROR, or OFF.

Example: "logging" : "DEBUG"

Manager properties

If an app is provided by the map.apps Manager, the following properties are available, too:

Manager properties

{
  ...
  "properties" : {
    "id": "sample",                     // app id
    "title": "Sample",                  // title
    "description": "Sample app",        // description of the app
    "editorState": "PUBLISHED",         // editor state
    "createdBy": "admin",               // user who created the app
    "createdAt": 1354314261408,         // timestamp when the app was created
    "modifiedBy": "admin",              // user who last modified the app
    "modifiedAt": 1354314268706,        // timestamp when the app was last modified
    "templateFile": "poicache.zip",     // the uploaded filename of the app template
    "templateId": "13B536ACA54D56",     // ID of the app template
    "thumbnailFile": null               // preview image url
  },
  ...
}

load

The "load" section is optional but important. It defines which bundles are available in an app and where they are located. Some other properties of the "load" section are used to define the requirement of i18n loading and the loading of additional CSS files.

Example

{
  ...
  "load": {
    "allowedBundles": [
        "splashscreen",
        "map",
        "windowmanager",
        "system",
        "templatelayout",
        "templates",
        "themes",
        "reporttool@>=3.1.1"
      ],
    "require": ["${app}/app"],
    "i18n": ["bundle"],
    "styles": ["${app}:app.css"]
  }
}

Following bundle loading properties exist:

appRootName

ID of the DOM node that this app should be attached to. Normally you define this ID in the Launcher method and not in the app.json file.

Example: "appRootName": "applicationDomNodeId"

Default: ""

bundleLocations

An array of locations that should be searched for bundles.json files when an app is launched.

The information is used to load the required bundles for an app.

Bundle locations can be specified using string syntax or object syntax.

Example

[
  "bundles",              (1)
  {
    "name": "myprefix",   (2)
    "location": "myprefix/bundles-folder",
    "...": "..."
  }
]

1	String syntax
2	Object syntax

Visit the App Runtime documentation for a comprehensive explanation of possible bundle locations.

The first located bundle wins. This means that the order of bundle locations matters. Locations defined earlier have precedence. This can be changed by the explicit definition of bundle exclusions (using the "excludes" property).

The special string value "bundles" references the JS Registry of that map.apps instance, the boot.js file was loaded from.

Default: ["bundles"]

allowedBundles

List of bundles that are allowed to be used by this app.

If not specified, all available bundles are loaded (if they are not listed in "skipBundles" property). This property is interpreted by the BundleLocator.

A bundle can be bound to a specific version range. This is done by adding @ followed by a version range identifier to the bundle’s name. Version range identifiers are outlined in the Versioning reference . Any bundle not having a version range identifier is assumed to accept the latest available bundle version.

A typical scenario where version ranges are used is when an app should load a bundle of an extension. To ensure that a certain version of this extension is used, a version range identifier, for example @3.1.x, has to be added to the extension bundle.

Example

"allowedBundles":[
 "splashscreen",
 "map",
 "windowmanager",
 "system",
 "templatelayout",
 "templates",
 "themes",
 "reporttool@>=3.1.1"
 ]

Default: []

skipBundles

A list of bundles that should not be loaded by this app. This is an alternative to the recommended property "allowedBundles". This property is interpreted by the BundleLocator.

Example: "skipBundles": ["splashscreen"]

Default: []

start

A list of bundles that should be enabled on startup of this app. This might be useful to load several bundles that are activated later during runtime of the app, for example by using the bundletools bundle.

Example

"start": [
  "system",
  "splashscreen",
  "map",
  "templatelayout",
  "toolset",
  "toolrules"
]

Default: []

require

This property declares that the app needs to load further JavaScript files. A common use case is to define that the app.js must be loaded by setting "require": "${app}/app".

Example: "require": ["dijit/form/Button", …]

Default: []

i18n

This defines that i18n files exist in the app, which are named "bundle" (/nls/bundle.js).

Example: "i18n": ["bundle"]

Default: []

styles

This property defines that additional CSS file should be loaded. The property is interpreted by the themes bundle. The second declaration style allows to load app specific CSS files dependent on a special theme.

Example 1

"styles": ["${app}:app.css"]

Example 2

"styles": [{
  // style definition only required if a special theme is used
  "theme": "night",
  "file": "${app}:app.css"
}]

Default: []

bundles

Use the "bundles" section to set component properties for available bundles. This allows to overwrite the properties of components in an app to customize the behavior of a component.

A component may define properties with values that are objects in contrast to simple type like string, number or boolean. When overwriting property values that are object, you need to define all required sub-properties, as the app configuration replaces the object value of the component configuration. That is, the object value of a property set in the app configuration is not merged with the component configuration defined in a bundle.

If a component is a factory component, an array style definition is used to declare how many component instances should be created by the factory component. For a sample, see the following AGSStore.

app.json bundles section sample

{
  ...,

  "bundles" : {
    "map" : {                          // name of the bundle
      "MapState" : {                   // name of the component
        "initialExtent":{              // name of the property (if property has complex value, it must fully be redeclared)
          "xmin" : 267804.1562000003,
          "ymin" : 5565553.608100001,
          "xmax" : 544362.0157999999,
          "ymax" : 5832335.593900001,
          "spatialReference": {
            "wkid": 25832
          }
        }
      }
    },
    "agssearch": {
      "AGSStore": [         // sample of factory component, here an array style must be used
      {
        "id": "Helipads",
        "url": "http://...",
        ...
      },
      {
        "id": "LargeAirportPoints",
        "url": "http://...",
        ...
      }
      ]
    }

  ...
  }
}