Using developer edition of ArcGIS Experience Builder with the ArcGIS Maps SDK for JavaScript
By default, Experience Builder does not load the ArcGIS Maps SDK for JavaScript (JSAPI) when the app loads. There are two options to utilize JSAPI modules. See Modules in the ArcGIS Maps SDK for JavaScript for details.
Accessing the Map
from within a widget is demonstrated on the jimu-arcgis/
page of the API Reference.
Yes, generally you can use widgets from the ArcGIS Maps SDK for JavaScript within your custom Experience Builder widgets. See the Editor widget sample for an example.
Using view.ui.add()
from a custom Experience Builder widget is not recommended. We plan to provide similar functionality in Jimu
in the future.
When you add jimu-arcgis
, the ArcGIS Maps SDK for JavaScript gets loaded automatically.
When importing esri/config
from the ArcGIS Maps SDK for JavaScript, using esri
does not work. This happens because Experience Builder has added an interceptor that matches all URLs. To use interceptors, add your interceptor to the beginning of the interceptor list like this: esri
.
Node.js
The current LTS version of Node.js is supported. Check the LTS releases. See more information on the About release versions page.
The reason why we need to run 'npm ci' if the node version changes is that some thrid party libs ExB depends on may require a specific Node.js version. When you change or upgrade NodeJS version on your machine, it is recommended to run the command 'npm ci' again under the "server" and "client" folder of Experience Builder Developer edition, so that it reflects all the new changes from the new version of NodeJS installed.
ArcGIS Services
Because Experience Builder is data source based, Feature
data can be accessed in a few different ways.
- Examples of instantiating and making use of a
Feature
, see the View Layers Toggle sample, the Add Layers sample and the Clustering sampleLayer - For examples of making use of a
Feature
as aLayer Data
, see the Data Sources samples within Widgets on the Sample Code pageSource
To filter a Feature
, there are two basic ways, depending on how the data source is configured:
-
If the widget loads data, the recommended way is to use the
Data
like:Source Component Use dark colors for code blocks Copy <DataSourceComponent useDataSource={} widgetId={} query={}> { Your render method } </DataSourceComponent>
You can find an example of using the
Data
in the Message subscriber sample and the Server-side output data source sample.Source Component -
If the widget does not load data, you can use the
update
function of aQuery Params() Data Source
. See the Filter feature layer sample for an example.
The query
method is available for execution against a Feature
. Once you obtain the Feature
you wish to obtain the related features from, you can implement the query making use of the relationship
like in the ArcGIS Maps SDK for JavaScript Query Related Features sample.
Once you have the related features as explained in the "How to retrieve related features" question, you can use the apply
method on a Feature
. This is the same method that is used on a Feature
within the Editor and Table widgets, for example. A sample of this method's executions is available in the ArcGIS Maps SDK for JavaScript Update FeatureLayer using applyEdits() sample.
React
Please check the recommened React version in About release versions page.
Both styles work well in Experience Builder, so it's up to you - you can use whichever you prefer. It seems like the React community is moving toward functional style components as the future, but class-based style components are easy to start and understand.
Custom Widget Development
Please review the Widget communication guide page for details on how to communicate between widgets. Also, see the Control the widget state sample for insight on how to use the get
method and the app
module from the jimu-core
package.
An Experience Builder widget is a React component, so we don’t handle the widget instance object. Instead, we use state props to manage widget lifecycle. The state is saved in the app store and is mapped into widget props. A widget has three states defined by enum WidgetState: Opened, Active, Closed. When a widget is added into a page, it is opened by default; when a widget is added into the widget controller widget, the end user can open and close it. For performance reasons, when an end-user clicks a widget, we don’t make the widget's state Active. If a widget needs the Active state, it should declare needActiveState in manifest property, then its state will be changed to Active when the user clicks the widget.
Developers who are familiar with the developer edition of ArcGIS Web AppBuilder may expect to see callback functions like on
, on
, etc. Because the Experience Builder widget is a React component and the widget status is saved in the application store and is mapped to widget props, you should check props.status
instead.
When a widget is closed, the only thing that the framework does is to change the widget state to Closed. As a result, in React, instead of handling the instance, we hook it to the react component lifecycle, such as component
for class-based components or use
for functional components.
Yes, you may use React-redux. You can access it via import {
.
There are a few approaches to creating widgets that have no user interface. These include:
- Create the
widget.tsx
but returnnull
in the widget render. - Create a widget without a
widget.tsx
, providing functions through the: message action, data action, or extension.
When the app is loaded, it invokes the extension point App
. So, the widget can provide an extension for this extension and logic should be placed within the extension. Please see Extension points.
There is no way to add custom tools. We recommend that you create a custom widget that includes a map along with your custom tools.
Please see the Unit Testing page for instructions on how to do unit testing.
If your widget is in a custom web extension repo, 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. See Getting Started for more information.
Deployment
The Experience Builder deployable export is simply a JavaScript/HTML/CSS app so it can be deployed into any web server. See the Deployment page for more help on deploying.
Described below are two approaches. One is for developing custom widgets and custom themes only; the other is for the combination of custom widgets, custom themes, and app configurations.
Custom widgets and themes only
-
The key is to have a
manifest.json
file at the root of your repository. The following properties in your repo'smanifest.json
are necessary for your repo to be integrated in your development environment. Comments pertaining to necessary properties and values are included below.Use dark colors for code blocks Copy { "name": "exb-custom-widgets-themes-repo", // Required property "type": "exb-web-extension-repo", // Required property/value for the repo to be compiled by webpack within client "description": "This is a sample custom widgets and themes repo for the developer edition of ArcGIS Experience Builder.", // Required property "copyright": "", // Required property "license": "http://www.apache.org/licenses/LICENSE-2.0" // Required property }
-
Within your repo, any custom widgets must live within a
widgets
child directory. Similarly, any custom themes must live within athemes
child directory. -
Clone the repo into the
client
directory, then webpack will compile the widgets automatically when executingnpm start
.
Custom widgets, custom themes, and app configurations
This approach requires two code repositories. The first repo, as described above, is for the custom widgets and themes. The second repo is for containing the app configuration directories at the root level. To use the second repo, do the following:
- If an
./server/apps/
directory exists, you must rename it to something other than "apps", or remove it. - Your apps repo must be cloned into your installation's
./server/public
directory with the name "apps". Either:git clone git@web-based-repo-manager
or:username/repo-name.git apps git clone https
should do.://web-based-repo-manager/username/repo-name.git apps - The app names within the
apps
directory can be a string or an integer, so long as the app directory's name matches the value of theid
property withininfo.json
. - The app configurations will compile when executing
npm start
.
Theming
Jimu UI is the primary component library for Experience Builder, and you may want to use that first because it will keep your custom widgets and themes consistent with the rest of the Experience Builder theme. If you do have a requirement to use the Calcite Design System, you can do that - see the Calcite sample widget. Please note that you should import the Calcite components from calcite-components
instead of @esri/calcite-components
.
Other
Yes. ArcGIS Experience Builder will reach most of the functional parity of ArcGIS Web AppBuilder through incremental releases. For more information, see the functionality matrix for Web AppBuilder and Experience Builder.
An administrator account has the privilege to both access and update all applications across the organization.