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 ArcGIS 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, ArcGIS 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

  1. Be sure to download, install, and configure ArcGIS Experience Builder.

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 ArcGIS Experience Builder was extracted.

    For detailed instructions on how to install ArcGIS ArcGIS Experience Builder for Developers, please see the documentation.

  2. In the ArcGIS 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.

    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 ArcGIS 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:

    It is important that the name property of the manifest.json matches the name of the folder for your widget.

                      
    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.3.0",
       "exbVersion": "1.3.0",
       "author": "Your Name",
       "description": "A hello world starter widget",
       "copyright": "",
       "license": "",
       "properties": {},
       "translatedLocales": [
         "en"
       ],
       "defaultSize": {
         "width": 800,
         "height": 500
       }
     }
    

Implement the base class

The main logic for the widget should be implemented in the widget.tsx. This file needs to implement the BaseWidget class.

  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 implement the BaseWidget class.

    The first line imports AllWidgetProps, BaseWidget, and jsx from the jimu-core module.

    To implement the widget you need to extend the BaseWidget class. In the body, the render function returns a simple div element and some text. The render function is a special React concept that returns JSX, an HTML-like syntax which is what will be shown to the user.

            
    1
    2
    3
    4
    5
    6
    7
    8
    /** @jsx jsx */
    import { AllWidgetProps, BaseWidget, jsx } from "jimu-core";
    
    export default class Widget extends BaseWidget<AllWidgetProps<any>, any> {
      render() {
        return <div className="widget-starter jimu-widget">This is your starter widget!</div>;
      }
    }
    
  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 ArcGIS 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 ArcGIS Experience Builder. e.g. https://localhost:3001

    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 ArcGIS 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.

    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 ArcGIS 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.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.