Getting started with widget development

ArcGIS Experience Builder is built with React and the ArcGIS Maps SDK for JavaScript. It allows you to create custom widgets for your specific workflows. To create your own widgets, you will need a basic understanding of the following:

• TypeScript is a superset of JavaScript. TypeScript is the language used to develop widgets.
• React is a JavaScript library for creating user interfaces. React is an abstraction away from the DOM; it encourages you to think of your application and UI in various states and render those states to make it easy to keep your UI consistent.
• JSX is a JavaScript extension syntax that allows you to describe what the widget's UI’s should look like through React.
• Jimu is Experience Builder’s JavaScript library used to create widgets.

Installation

Experience Builder is available as a ZIP file for installation. For more details, please review the installation page.

Setting up a widget development environment

For developing a custom widget, you can use any IDE or text editor that you are comfortable with. Visual Studio Code is a good option because it has TypeScript awareness built-in by default.

The custom widget that you build will be located within a directory in the client folder of the ArcGIS Experience Builder file structure. Within Visual Studio Code, open the client folder as a project:

1. Click the File menu.
2. Click Open Folder.
3. Browse to the client folder within the extracted Experience Builder files you unzipped when you started Experience Builder for the first time.

This will make all the files in the client folder (including your custom widget files) available in the left-hand VS Code Explorer tab. Visual Studio Code will also scan the entire contents of the client folder for TypeScript definitions of the Experience Builder libraries, enabling TypeScript validation and autocomplete while writing your custom widget.

Visual Studio Code

If you are using Visual Studio Code as a text editor, there is an extension marketplace you can use to add functionality to the text editor. In addition to any React extensions that you may want to install, these extensions are recommended (not required) for Experience Builder custom widget development:

• IntelliSense for CSS class names in HTML - CSS class name completion for the HTML class attribute based on the definitions found in your workspace.
• vscode-styled-components - Syntax highlighting for styled-components
• ESLint - Integrates ESLint into VS Code.

Widget

A widget is a configurable and sharable functional unit in Experience Builder. Basically, a widget is a React component injected with these common properties by the jimu framework:

• Configurations for widget, such as id, label, config, etc.
• Runtime information about the widget including state, isClassLoaded, etc.
• Local language strings
• Data source instance and status information
• URL parameter information

Widget location

Custom widgets are placed within an Experience Builder web extension repo. A web extension repo is a folder within the client folder that contains a manifest.json file with contents:

1
2
3
4
5
6
7
{
  "name": "my-web-extension-repo",
  "type": "exb-web-extension-repo",
  "description": "This is a sample extension repository.",
  "copyright": "",
  "license": ""
}

Developer edition of Experience Builder comes with an example web extension repo located at client/your-extensions. You may use this one or create your own. Using your own may work better when utilizing source code repository systems like Git. When creating your own, you may see errors reported by your code editor, like missing type declarations for Jimu modules. To fix this, add the folder of the web extension repo to the include array within the tsconfig.json file like this:

1
2
3
4
5
6
7
8
9
10
{
  "include": [
    "dist/widgets",
    "your-extensions",
    "types",
    "jimu-core/lib/types",
    /** ADD the name of your web extension repo folder: **/
    "my-web-extension-repo"
  ],
}

Widget files

At the root of the web extension repo are two folders: widgets and themes. To create a custom widget, create a new folder within the widgets folder with the name of the custom widget. All the files for the custom widget will be placed into this new folder.

1
2
3
4
5
- my-web-extension-repo/
    - manifest.json
    - themes/
    - widgets/
        - my-custom-widget/

Within the widget folder, a valid widget must contain a manifest.json file and other required files.

• For more details on the manifest.json file, see widget manifest.
• For more details on other required files and general widget development, learn about widget implementation.
• To get started quickly with the minimal set of files required, see the simple widget in the your-extensions\widgets folder.

Just the Basics

If you're new to Experience Builder development and want to understand the basic concepts, check out the following:

• Core concepts
• If you learn best by looking at code, review our samples and clone the repo.