Migrate existing apps and bundles from map.apps 3 to map.apps 4

This page describes, how apps and bundles created for map.apps 3 can be migrated to map.apps 4.

Migrate apps

For some bundles the configuration structure used in the app.json file has changed with map.apps 4. The documentation of each bundles gives an overview of the new configuration.

Custom bundle development

Configuration properties for ArcGIS API for JavaScript are aligned

When using the ArcGIS API for JavaScript in map.apps 4, configuration properties are merged and synchronized from map.apps into the API provided by Esri. With map.apps 3 you can configure additional properties for the API by extending the properties section of an app. Because map.apps 4 uses version 4 of the ArcGIS API for JavaScript, the structure of these properties is changed. You find an overview of the new configuration structure at: https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html. We recommend to use the configuration provided in the application.properties.

Layout-Template mechanism is restructured

Layout-templates modern and desktop are no longer available with map.apps 4. If you used any of these templates in your app, consider switching to template-seasons.

The seasons template is decoupled from the templates bundle and moved to template-seasons. To use the seasons template, add the bundles templatelayout and template-seasons to your app.

Minimal example for app.json
{
    "load": {
        "allowedBundles" : [
            "system@^4.0.0",
            "templatelayout@^4.0.0",
            "template-seasons@^4.0.0",
            "theme-everlasting@^4.0.0",
            "map-init@^4.0.0"
        ]
    }
}

If only one template bundle is loaded in your app, it is not required to configure the selected template. To provide multiple templates in one app, the initially selected template must be configured as described in the templates bundle documentation.

common template is removed

The common template is used in map.apps 3.x to share common CSS statements between templates. Therefore, it is usually imported into other templates' CSS files using @import. These shared resources amount to one statement and do not justify an own template. In map.apps 4.13.1 the common template is removed and missing statements were added to the modern and seasons template. If you built your own template and imported bundles/base/templates/common you should remove this import and add the following statement to your file:

replace common.css import with
.fullwidthAndHeight {
    width:100%;
    height:100%;
    margin:0;
    padding:0;
}

Theme mechanism is restructured

Layout-themes pure, day and night are not included in map.apps 4. If you used one of these themes, consider switching to one of the new themes of map.apps 4. The following theme bundles are provided: theme-everlasting, theme-spring, theme-winter, theme-summer, theme-autumn.

The shipped themes are decoupled from the themes bundle and subdivided into standalone bundles.

WebFonts are moved to an own bundle

map.apps 4 themes are optimized to load required WebFonts from a separate bundle. If your theme uses these WebFonts, add the new bundle font-mapapps as a dependency to your theme’s manifest.json file.

manifest.json
...
"dependencies" : {
    "font-mapapps" : "^4.0.0"
},
...

The location of the WebFonts gallery has changed to js/bundles/layout/font-mapapps/index.html

Properties of manifest.json files are aligned to package.json file style

To help developers become familiar with the OSGi system, the style of manifest.json files is aligned to the popular npm package.json file markup. Bundles shipped with map.apps 4.13.1 are already adjusted to match the new pattern.

New Old

components

Components

name

Bundle-SymbolicName

activator

Bundle-Activator

vendor

Bundle-Vendor

keywords

Bundle-Category

startLevel

Bundle-StartLevel

version

Bundle-Version

dependencies

Require-Bundle

optionalDependencies

N/A

title

Bundle-Name

i18n

Bundle-Localization

layer

Bundle-Layer

requiredExecutionEnvironment

Bundle-RequiredExecutionEnvironment

excludedExecutionEnvironment

Bundle-ExcludedExecutionEnvironment

description

Bundle-Description

contactAddress

Bundle-ContactAddress

copyright

Bundle-Copyright

url

Bundle-DocURL

icon

Bundle-Icon

license

Bundle-License

layer

Bundle-Namespace

startLevel

Bundle-StartLevel

productName

Product-Name

autostartPolicy

Bundle-AutoStartPolicy

configBundleLocation

Config-Bundle-Loation

map.apps 4.13.1 still works with bundles that use the old pattern. However, it is recommend to align your manifest.json to the new pattern.

DataView is moved to an own bundle

With map.apps 4.13.1 all DataView components are provided within a standalone bundle dataview. To use the DataView in your custom bundle you must declare the following dependency in your manifest.json:

manifest.json
...
"dependencies" : {
    "dataview" : "^4.0.0"
},
...

Additionally, the implementing component must be aligned to the new location of the DataView:

manifest.json
{
    "name" : "ExampleDataView",
    "impl" : "dataview/DataView",
    "properties" : {
        ...
    }
}

For more information, see the dataview bundle documentation.

Data forms now support infield top aligned labels for text boxes

When migrating data forms to map.apps 4, adjust your text box definitions to match the new possibilities with infield top aligned labels.

Simple data form with text box in map.apps 3.x
{
   "dataform-version": "1.0.0",
   "size": {
      "h": 250,
      "w": 400
   },
   "type": "gridpanel",
   "showLabels": true,
   "cols": 1,
   "children": [
      {
         "type": "textbox",
         "title": "Text",
         "field": "text1"
      }
   ]
}

This data form definition results in the following widget:

dataform 3x

Because map.apps 4 displays text boxes differently, the use of infield top aligned labels is recommended for optimal user experience:

Data form using infield top aligned labels
{
   "dataform-version": "1.0.0",
   "cssClass": "form--responsive-labels",
   "size": {
      "h": 100,
      "w": 300
   },
   "type": "gridpanel",
   "showLabels": false,
   "cols": 1,
   "children": [
      {
         "type": "textbox",
         "placeHolder": "Text",
         "field": "text1"
      }
   ]
}

To achieve the new text box behavior…​

  • …​ add "cssClass": "form—​responsive-labels" property to your configuration.

  • …​ disable labels via "showLabels": false.

  • …​ use placeHolder instead of title in your child component configuration.

dataform 4x dataform 4x 2

Alignment configuration for elements in legend widget is removed

The legend widget is completely restructured and is now closely coupled with the ArcGIS API for JavaScript. Therefore, the configuration options alignmentLeft and showBaseLayer are no longer supported in mapp.apps 4.13.1. To change the visibility of a layer in the legend widget, adjust the layer configuration in the map-init bundle. For more information, see the legend and map-init bundle documentation.

GeometryService usage from AMD module is removed

To encourage the usage of the GeometryService provided through the OSGi runtime the synchronization of the geometry.service.url with the ArcGIS API for JavaScript on startup is removed in map.apps 4.13.1. This means if you use AMD module esri/task/GeometryService the configuration of the service’s URL is not applied. Instead, use the service by referencing the OSGi component in your manifest.json file.

manifest.json
{
    "name" : "MyComponent",
    "references" :[{
        "name" : "geometryService",
        "providing" : "geometryservice.GeometryService"
    }]
}

For more information, see the geometryservice bundle documentation.

Splash screen HTML layout has changed

The HTML of the splash screen inside the index.html has changed. If you use a custom index.html update it to use following splashscreen layout:

index.html
<div id="splashScreen" class="splashScreen">
    <div class="launch__animation">
        <div class="dot-outer">
            <div class="dot dot-1"></div>
        </div>
        <div class="dot-outer">
            <div class="dot dot-2"></div>
        </div>
        <div class="dot-outer">
            <div class="dot dot-3"></div>
        </div>
        <div class="dot-outer">
            <div class="dot dot-4"></div>
        </div>
        <div class="dot-outer">
            <div class="dot dot-5"></div>
        </div>
        <div class="dot-outer">
            <div class="dot dot-6"></div>
        </div>
    </div>
    <div class="launch__title">
        <h4 class="splashHeader">
            <span class="launchLog"></span>
        </h4>
    </div>
    <div class="launch__bundles">
        <p class="splashBundle">{nbsp}</p>
    </div>
</div>