A method of writing a widget that can be used both within Experience Builder or a regular React app.
When building a custom widget for Experience Builder, if your primary goal is to use the widget within Experience Builder, building it directly using the standard workflows is the best and quickest way to success.
But what if you need to create a widget that works in both a plain React app and within Experience Builder? With a little bit of extra work on top of the standard workflows, you can write a React component (widget) that can be included in both places!
One method to do this is:
npm install
the Component into the client
folder of Experience Builder.Pretty simple in theory. In practice, it can get a little complex, so I'll step through the details below.
TSDX is a "zero-config CLI that helps you develop, test, and publish modern TypeScript [React components] with ease." Create a new directory and in a terminal, run:
npx tsdx create my-widget cd my-widget npm start
Make sure you choose "react" for your template.
This will give you a folder structure of supporting files -- which is the infrastructure where you can build out your widget functionality as a React Component. Check out the TSDX documentation for more details on how to develop your component. TSDX comes with a "playground" React app under the example
folder that you can use to see your component within the context of an example application during development. During development you will typically be running npm start
in both the root directory (to build the widget) and also npm start
within the example
directory to run the app to see the component output.
By default, the template exports a React component named Thing
. The first change I make is to export the component as the default export so importing is a bit more clean later on. So make these changes to my-widget\src\index.tsx
and my-widget\example\index.tsx
. Then after running npm start
in both the root directory and the example
directory, and browse to http://localhost:1234, you should be able to see your working component (just a single line of text):
npm install
the Component into Experience BuilderNow you have a React Component that is running in a React App (that's what's running at http://localhost:1234
above), so let's move on to showing our Component within Experience Builder.
First, install Experience Builder per the instructions here.
Then open a terminal and browse to the client
directory in the Experience Builder unzipped files. Run npm install <PATH>
where <PATH>
is the local path to your React component. For example if you run the npm tsdx create ...
command at C:\code\my-widget
, you'll run npm install C:\code\my-widget
.
(Tip: include --no-audit
in the npm install...
command to skip auditing all of Experience Builder's files)
Now that it's installed, you can include this Component in any custom Experience Builder widgets. If you don't yet have a widget, you can copy the simple
widget from client/sample-widgets/simple
to client/your-extensions/widgets
to start.
Within client\your-extensions\widgets\simple\src\runtime\widget.tsx
, import your component by inserting an import statement near the top of the file:
import MyWidget from 'my-widget';
You can then use that component in the JSX near the bottom of the file. Replace the render()
function with this:
render() {
return (
<div className="widget-demo jimu-widget m-2">
<MyWidget></MyWidget>
</div>
);
}
Remember to make sure
npm start
is running in theclient
directory so Experience Builder will re-build your widget and make it available.
After these changes, go into Experience Builder and add the Simple Widget
to an Experience, and your component is now visible!
Now you have a React Component that is working with the context of a React app and Experience Builder. This is a basic example - the next step is how to use widget configuration options and map modules. I'll dig into that in the next post - go here: https://community.esri.com/people/GRehkemper-esristaff/blog/2020/07/01/the-one-widget-part-2
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.