Add custom widgets

Beginning with ArcGIS Enterprise 11.0, you can add custom Experience Builder widgets to a portal. This means you can choose custom widgets in the builder environment when you create an app. Before you can use a custom widget, it must be hosted on a web server and registered to a portal. For security reasons, only portal administrators can register custom widgets. Custom widgets you share publicly can be used in public apps for anonymous user access.

Note:

After upgrading to ArcGIS Enterprise 11.1, if you find that your custom widget localized language does not work, check whether the first line of the localized language file is define({. If it is, you must update the file in the following way:

Previous code

define({

// strings

})

New code

System.register([], function (_export) {return {execute: function () {_export({

// strings

})}}});

Host a custom widget on a web server

Hosting a custom widget on a web server is no different than hosting any web app. You must install and configure a web server. Common web servers include IIS and Apache HTTP Server.

To host custom widgets on a web server, complete the following steps:

1. Enable anonymous access to the virtual directory that is hosting your widgets.

   The hosting location must be anonymously accessible.

2. Enable HTTPS.

   Enable HTTPS access in your web server to avoid creating mixed content. Experience Builder does not allow mixed active content caused by loading HTTP under an HTTPS connection. In addition, your server should have a valid SSL certificate issued by a certificate authority to establish the HTTPS connection.

3. Enable Cross-Origin Resource Sharing (CORS).

   Experience Builder runs under your portal domain, which may be different from the domain of the web server hosting your custom widget. You need to enable CORS in the web server so that access from your portal domain is allowed.

4. Add a JSON handler to your web server.

   Each widget consists of a JSON manifest file that describes widget properties. Some web servers do not recognize the JSON file extension by default. In such cases, you need to add it to your server as a new MIME type at the application level or a higher level. The MIME type should have .json as the file extension and application/json as the MIME type.

5. Compile the custom widget.

   Before you can host a custom widget, you must compile it. To do that, first install the developer edition if you have not already. Copy the custom widget into the arcgis-experience-builder/client/your-extension/widgets directory. Then, in the terminal, run npm run build:prod for the client directory. Once you do, the compiled widget appears in the client/dist-prod/widgets directory.

6. Deploy the custom widget to your web server.

   You can copy the client/dist-prod/widget/ folder to the web server. After deployment, you need to obtain the URL path to the manifest file of your custom widget. An example of a URL path to a manifest file is <server.domain.com>/<my widget>/manifest.json.

   Note:

   If your custom widget uses the import() function to dynamically load modules, the dynamically loaded modules are compiled and placed into the widgets/chunks folder. You must ensure that the chunks folder is in the widgets folder when you deploy the widget. You can view an example of a custom widget with the chunks folder on GitHub.

   If you are developing multiple widgets, you may need them to share code. When you deploy widgets that share code, you must ensure that the widgets and either the shared-code folder or chunks folder are in the widgets folder on your server. You can view an example of custom widgets with the shared-code folder on GitHub.

   Learn more about sharing code between Experience Builder widgets

Register a custom widget

You must register each custom widget in your portal. Portal administrator privileges are required to register a custom widget.

1. In a browser window, sign in to your portal.
2. Click the My Content tab of the content page.
3. Click Add Item and choose An application.
4. Choose Experience Builder widget, and provide the URL to your manifest file.

   An example of a URL path to a manifest file is <server.domain.com>/<my widget>/manifest.json.

5. Click the Title box.

   The title of the item automatically populates from the manifest file. Optionally, you can manually edit the title.

6. Add tags in the Tags box.
7. Click Add Item.

   The custom widget is now available on the My Content tab of the content page as an Experience Builder widget type.

Share a custom widget

As a portal administrator, you can share custom widgets with groups in an organization that need access, with the entire organization, or publicly if necessary.

Caution:

An app will only load the custom widget that is registered in the same organization as the users who have permissions to access the app.

In My Content, locate the custom widget and share it. When you open Experience Builder, the custom widget displays in the Custom group on the Insert widget tab.

Caution:

If you receive a 404 error when loading the custom widget, ensure that the widget does not require modules using the widget's package name. Instead, use a relative path to load modules.

Update a custom widget

You cannot update a custom widget in the portal. However, you can update the HTML structure and JavaScript code of the hosted custom widget in the web server. If you do, apps that include the custom widgets automatically update to include the latest changes.

Tip:

If you do not see updates to your custom widget when you launch an app, it may be because your web browser is caching the previous version of the custom widget. To avoid this, you can set caching directives for your web server.