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
File
menu. - Click
Open Folder
. - 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:
_app
- a variety of properties on the current state of the experience.State _data
- current data sources in the widget.Source Manager _widget
- a variety of properties about widgets, including if a widget is loaded or not.Manager _session
- can be used to see and manage the login information.Manager
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 _app
. The 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.
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.