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:
- Click the
- Browse to the
clientfolder 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
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)
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.
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 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)
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:
_app- a variety of properties on the current state of the experience.
_data- current data sources in the widget.
_widget- a variety of properties about widgets, including if a widget is loaded or not.
_session- 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
top context is the builder context, and the
_app 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.jimu to determine the execution context -
true means your code is within the builder context.
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
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.