Migrating from Web AppBuilder

Introduction

Experience Builder is different from Web AppBuilder in a variety of ways. Because of these differences, directly converting custom widgets and themes from Web AppBuilder to Experience Builder is not possible. Even though it is a manual process, here are some tips, techniques, and recommended practices to consider as you are re-building your widget or theme for Experience Builder.

Tip

This is not meant to be an exhaustive list, and the process is still a manual re-write process for the developer. These steps are provided to help with preparation and planning when re-building a widget within Experience Builder.

Getting Started

First, review the Experience Builder documentation, and learn TypeScript, React, JSX, and Jimu per the Getting Started documentation.

Create a New Widget

Once you are familiar with the core technology concepts, create a blank/starter Experience Builder widget and make sure you have the build environment setup correctly. Then start moving code over from your Web AppBuilder custom widget into your new Experience Builder custom widget, taking note of the following:

  1. Both widgets have a manifest.json, but Experience Builder's is slightly different, review the new format of manifest.json and update as appropriate.

  2. Any dojo-specific modules must be replaced - for example, if using dojo/domClass module's domClass function like this:

     
    domClass.contains(domNode, "myClassName");

    ... you should now re-write that with non-dojo alternatives, in this case:

     
    domNode.classList.contains("myClassName");
Tip

Dojo handles standardizing browser support for you, but using native JavaScript functionality does not, so you should check browser support for features you're using with sites like MDN or CanIUse. In this case, for example, CanIUse says that classList is supported in all major browsers.

  1. Widget life cycle methods do not work the same. In general, widget life cycle methods that happen at the widget startup (constructor, postMixinProperties, buildRendering, postCreate) can probably moved into the componentDidMount() function (or equivalent useEffect() if using hooks).
  2. The template that used to be in widget.html will now be converted to JSX in the render() function of your custom Experience Builder widget (React component).
    • If you are naming DOM nodes with data-dojo-attach-point, an equivalent in React is Refs.
    • If you are using NLS for internationalization/translation, in your template (Example: <div>${nls.label1}.</div>) you'll now use the "translations folder" pattern).
  3. Accessing a Map/Scene object - If you are using this.map, this pattern does not work exactly the same in Experience Builder since you can now have multiple maps or scenes in a single experience (where you could only have one map per Web AppBuilder app). See JimuMapViewSelector and JimuMapViewComponent.
  4. If you have a custom Setting panel (in the /setting folder), the equivalent of that is in src/setting in your custom Experience Builder widget. More info on creating a setting UI.