Skip To Content
ArcGIS Developer

Make widgets backward compatible

The configuration of each ArcGIS Web AppBuilder widget is stored in the app. When a widget evolves with new functions, you 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 version manager file.
  • The BaseVersionManager class can be inherited by completing the following steps:

    1. Add the “hasVersionManager” property to the widget manifest.json file, and set it to true.
      "properties": {
        	"hasVersionManager": true
    2. Create a new file named VersionManager.js.
      function(BaseVersionManager) {
        function VersionManager(){
          this.versions = [{
            version: '1.0',
            upgrader: function(oldConfig){
              return oldConfig;
            version: '1.1',
            upgrader: function(oldConfig){
              var newConfig = oldConfig;        
              return newConfig;
        VersionManager.prototype = new BaseVersionManager();
        VersionManager.prototype.constructor = VersionManager;
        return VersionManager;

    When inheriting from the BaseVersionManager class, keep the following rules in mind:

    • Because BaseVersionManager runs in both the browser and Node.js, and Dojo classes are not imported into Node.js, any Dojo classes should not be used.
    • Put all your versions into the versions property.
    • For the upgrader function, the input is the old configuration and the output is the new configuration.