Create a starter widget

Overview

You will learn: how to build the base implementation for a widget.

ArcGIS Experience Builder allows you to choose from a variety of widgets and build applications interactively. These applications are called experiences. If you would like to give users more options, you can create your own custom widgets and add them to Experience Builder. The type of widget you build depends on the functionality you are after. You can build widgets that interact with the map or widgets that perform an operation outside of ArcGIS. Once a widget is created and installed, Experience Builder will automatically detect the widget and make it available for users.

In this tutorial, you will create a folder and the main files required to create a new widget. These files will be used as a starter for other widget tutorials.

Prerequisites

Steps

Create a new folder

The first step to create a new widget is to create a folder for the widget files.

1. In your file browser, go to the folder where Experience Builder was extracted.

   More info

   For detailed instructions on how to install the developer addition of Experience Builder, please see the documentation.

2. In the Experience Builder folder, expand the following path: /client/your-extensions/widgets.

3. In the widgets folder, create a new folder called starter-widget. Your folder path should look like this: /client/your-extensions/widgets/starter-widget.

   More info

   Widget folders cannot include spaces. Learn more about building widgets in the documentation.

Create a manifest file

A manifest file is required to define the widget's properties. These are read by Experience Builder when it loads.

1. In the starter-widget folder, create a file named manifest.json. Add the following JSON object to define the widget:

   More info

   It is important that the name property of the manifest.json matches the name of the folder for your widget. You can also update the other metadata in the manifest.json file at this time, like the description of the widget, the author, etc.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
    {
      "name": "starter-widget",
      "type": "widget",
      "version": "1.14.0",
      "exbVersion": "1.14.0",
      "author": "Your Name",
      "description": "A hello world starter widget",
      "copyright": "",
      "license": "",
      "properties": {},
      "translatedLocales": [
        "en"
      ],
      "defaultSize": {
        "width": 800,
        "height": 500
      }
    }

Implement component

The main logic for the widget should be implemented in a React component in widget.tsx. This file will export a single function - the React component.

1. In the starter-widget folder, create a new folder called src. In this folder, create another folder called runtime.

2. In the runtime folder, create a file named widget.tsx. Add the following code to create the React component.

   More info

   The first line imports React from the jimu-core module.

   To implement the widget you need to create a function that is the React component. This function returns the JSX (in this example, a div element and some text), an HTML-like syntax which is what will be shown to the user.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   import { React, AllWidgetProps } from "jimu-core";
   
   const Widget = (props: AllWidgetProps<any>) => {
     return <div className="widget-starter jimu-widget">This is your starter widget!</div>;
   };
   
   export default Widget;

3. In the terminal, stop (ctrl + c) and re-start the npm start script that is running in the client folder.

Test your widget

Once the folder and main files are in place, you can test your widget by running Experience Builder and adding it to a new page. The Builder will automatically detect the widget and make it available.

1. In a web browser, go to Experience Builder. e.g. https://localhost:3001

   More info

   If the Builder did not open a tab for you, browse to https://localhost:3001. If you get a "Invalid SSL Certificate" issue, click "Proceed Anyway".

2. In Experience Builder, click Create New to create a new experience page.

3. Click the Create button on the Blank scrolling template.

4. The Insert widget panel is opened for you. From there, drag your new starter-widget widget on to the experience.

   More info

   The widget will be located in the "Custom" section near the bottom of the widgets list. The widget may have an invalid icon right now. That's ok - you have not created one yet! If your widget is not showing up, double-check that you have run npm start in the client folder per the original setup instructions.

5. In the Experience Builder toolbar, click Save then Preview and the experience will open in a new browser tab with your custom widget.

Congratulations, you're done!

Compare your widget with our completed widget. To add some functionality to your widget, check out the next tutorial.