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:
- Define the VersionManager class as a subclass of
Widget
. If using version 1.13 or earlier, useVersion Manager Base
. For later versions,Version Manager Widget
is recommended.Version Manager - Assign the VersionManager instance to the widget class or function property
version
, like thisManager Widget.version
.Manager = new Widget Version Manager();
In the VersionManager class that extends from Base
, 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 use
or output
, you can extend the Widget
class.
The VersionManager that extends from Widget
is very similar to the VersionManager that extends from Base
, but the version object supports one more property, upgrade
.
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 Widget
:
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.
import { versionManager } from '../version-manager'
export default function Widget (props) {
//...
}
Widget.versionManager = versionManager