Debugging widget development

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

Debugging tools

There are a variety of debugging tools available to you within your web browser that you can use to efficiently build your custom widget.

Browser developer tools

While in the Experience Builder authoring interface or in the preview mode, you can open the developer tools of your browser to access multiple debugging tools. To open the developer tools:

• In Chrome, click the Main Menu and then select More Tools > Developer Tools. (more info)
• In Firefox, click the Main Menu > Web Developer > Toggle Tools (more info)

DOM elements

In the browser developer tools, click the Sources (Chrome) or Debugger (Firefox) tab. Here you can explore the DOM of your custom widget to see the current status.

JavaScript source and breakpoints

In the browser developer tools, click the Elements (Chrome) or Inspector (Firefox) tab. Here you can browse the page's JavaScript code. Ensure your widget has been opened (if applicable), and in the left-hand file browser, browse to webpack and find your widget's widget.tsx file and double-click it. Alternatively, type ctrl + p to open the file command palette and type widget.tsx. The widget.tsx file you want will be the one with the ?zzzz (where zzzz is a number-letter combination) at the end of the filename.

Once you have your widget file open, you can see its TypeScript code. You can set breakpoints here by clicking on the line numbers (more info: Chrome, Firefox)

Global variables

When your code is stopped on a breakpoint, in the right-hand panel you can open the Scope pane to see variables that are currently in scope. Scroll down to Global, which is where Experience Builder places a few convenience variables that you can inspect to find out the current status of different things in your experience. Some of these variables include:

• _appState - a variety of properties on the current state of the experience.
• _dataSourceManager - current data sources in the widget.
• _widgetManager - a variety of properties about widgets, including if a widget is loaded or not.
• _sessionManager - can be used to see and manage the login information.

There are other, less commonly used global variables available too. To see the full list view the file client\jimu-core\lib\types\window.d.ts.

Debugging in the builder page

When debugging in the Builder Page, the Experience is loaded in an iframe. Because of this, there are two Javascript execution contexts: top and _appWindow. The top context is the builder context, and the _appWindow context is the Experience context. When you are inspecting global variables in the console, make sure you have the correct context selected in the dropdown list in the browser developer tools. When you are debugging using breakpoints, watch window.jimuConfig.isBuilder to determine the execution context - true means your code is within the builder context.

Network

In the browser developer tools, click the Network tab. Here you can see the network requests that are sent and received by your Experience.

Clear the cache

While debugging your code, you will likely be changing your code and reloading the page frequently. Sometimes the browser caches things unexpectedly, confusing you during development. Because of this, it is important to clear your cache every time you refresh the browser, or enable the Disable cache checkbox on the Network developer tools while you are doing development.

React dev tools

Experiences use the React JavaScript library. In addition to the DOM Elements browser above, you can install a browser extension that knows more about how React works and can show you even more information on your React components. Install the extension from your browser's extension store (Chrome, Firefox) and enable the tools. Now in your Browser Developer Tools you will have two additional tabs: Components and Profiler.

Click the Components tab. Use the search or the "Select Element" button to select your custom widget in the component tree. When it is selected, you can see your component's props and state in the right-hand info panel.