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

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

  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.

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:

    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.15.0",
       "exbVersion": "1.15.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.

    Use dark colors for code blocksCopy
    1
    2
    3
    4
    5
    6
    7
     import { React, type 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

  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.

  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.

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