Make widget backward compatible

As the ArcGIS Experience Builder evolves, the Jimu framework may introduce new features and breaking changes. When you need to use your widget in a new version of ArcGIS Experience Builder, you must test the widget in the new version. If you find that the widget is not working as expected, please read the release notes to see if there are any breaking changes that may affect your widget.

The configuration of each ArcGIS Experience Builder widget is stored in the app config. When you add additional functionality to a custom widget, you may need to modify the configuration format. To make the widget backward compatible with the previous configuration, you have two options: check the configuration format programmatically, or use VersionManager to upgrade the old format. The latter is strongly recommended due to the following advantages:

• The code is simpler, as it only processes the latest format.
• It is easier to track the changes, as they are put into one VersionManager file.

The first option is straightforward. Below is the guide to use VersionManager to make the widget backward compatible.

To use VersionManager, you need to take two steps:

1. Define the VersionManager class as a subclass of WidgetVersionManager. If using version 1.13 or earlier, use BaseVersionManager. For later versions, WidgetVersionManager is recommended.
2. Assign the VersionManager instance to the widget class or function property versionManager, like this Widget.versionManager = new WidgetVersionManager();.

In the VersionManager class that extends from BaseVersionManager, you need to define the versions property, which is an array of version objects. Each version object contains the version property and the upgrader function. The upgrader function is used to upgrade the configuration from the previous version to the current version. The upgrader function takes the configuration object as the parameter and returns the upgraded configuration object. If the configuration is not changed, you can skip the version in the versions array. If your VersionManager needs to upgrade more than the widget configuration, such as the useDatasources or outputDataSources, you can extend the WidgetVersionManager class. The VersionManager that extends from WidgetVersionManager is very similar to the VersionManager that extends from BaseVersionManager, but the version object supports one more property, upgradeFullInfo. When this property is set to true, the upgrader function will receive the full widget info object, then you should return the upgraded full widget info object.

Here is an example of a VersionManager class that extends from WidgetVersionManager:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { WidgetVersionManager, WidgetUpgradeInfo } from 'jimu-core'

class VersionManager extends WidgetVersionManager {
  versions = [{
    version: '1.6.0',
    description: 'Change property a to b. This demonstrates how to upgrade the widget config',
    upgrader: (oldConfig) => {
      if (!oldConfig) return oldConfig
      const newConfig = oldConfig.set('b', oldConfig.a).without('a')
      return newConfig
    }
  }, {
    version: '1.15.0',
    description: 'Upgrade the use data source.',
    upgradeFullInfo: true,
    upgrader: async (oldInfo: WidgetUpgradeInfo) => {
      const newWidgetJson = oldInfo.widgetJson.set('useDataSources', YOUR_NEW_USE_DATA_SOURCES)
      const widgetInfo = { ...oldInfo, widgetJson: newWidgetJson }
      return widgetInfo
    }
  }]
}

export const versionManager = new VersionManager()

We recommend that you put the VersionManager class in a separate file, such as version-manager.ts, and put it in the src folder.

Then, in your widget.tsx file, assign the VersionManager instance to the widget class or function.

1
2
3
4
5
6
7
import { versionManager } from '../version-manager'

export default function Widget (props) {
  //...
}

Widget.versionManager = versionManager