Add layers to a map

Overview

You will learn: how to add layers to a map from a custom widget.

The map widget in ArcGIS Experience Builder automatically loads layers based on what web map it is configured to load. Depending on your workflow, you may want a custom widget to dynamically add a layer to the map based on user interaction with the widget.

In this tutorial, you will add a button to the widget to add a feature layer to the map.

Prerequisites

Steps

Get the starter widget

1. Download the Starter Widget template here.

   More info

   If you have already completed the create a starter widget tutorial, you can start with that. Duplicate the widget folder within /client/your-extensions/widgets.

2. In the ArcGIS Experience Builder folder, extract the zip into the following path: /client/your-extensions/widgets.

Change the widget name

1. In the terminal where the npm start is running in the client folder, stop the script by pressing ctrl + c.

2. In your file browser, go to the folder where Experience Builder was extracted.

3. In the Experience Builder folder, expand the following path: /client/your-extensions/widgets.

4. In the widgets folder, rename the starter-widget folder to add-layers-to-a-map.

5. In the newly-renamed add-layers-to-a-map folder, open the manifest.json file in the code editor.

6. In the code editor, modify the name property to add-layers-to-a-map.

   More info

   It is important that the name property of the manifest.json matches the name of the folder for your widget. You can also update the other metadata in the manifest.json file at this time, like the description of the widget, the author, etc.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
    {
      // *** UPDATE  ***
      // "name": "starter-widget",
      "name": "add-layers-to-a-map",
      "type": "widget",
      "version": "1.16.0",

7. After the version property in manifest.json, add a jimu-arcgis dependency. Declaring this allows the usage of ArcGIS Maps SDK for JavaScript modules within the widget.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   {
      "name": "add-layers-to-a-map",
      "type": "widget",
      "version": "1.16.0",
      // *** ADD ***
      "dependency": ["jimu-arcgis"],

Implement the settings panel

A settings panel can be implemented to allow Experience authors to customize the widget. The settings panel appears in the right-hand sidebar when a widget is selected in ArcGIS Experience Builder. To create the panel, create a React component.

1. In the widget root folder, create a config.json file that contains an empty object.

   More info

   At a later time, widget configuration parameters can be added to this object to store widget setting values.

   Use dark colors for code blocksCopy

   1
   {}

2. In the src folder, create another folder called setting.

3. In the setting folder, create a setting.tsx file.

4. Open the setting/setting.tsx file and include the following import statements.

   Use dark colors for code blocksCopy

   1
   2
   import { React } from 'jimu-core'
   import { type AllWidgetSettingProps } from 'jimu-for-builder'

5. Add code to implement the component.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   const Setting = (props: AllWidgetSettingProps<any>) => {
   return <div className="widget-setting-demo">This is your starter widget setting area!</div>
   }
   
   export default Setting

6. In the terminal, stop (ctrl + c) (if applicable) and start the npm start script in the client folder.

Enable selecting a map view data source

In ArcGIS Experience Builder, there can be more than one Map Widget on the page at a time. Because of this, a custom widget must have a section of its Settings Panel that allows the author to choose which map widget to use.

1. In the setting/setting.tsx file, include the MapWidgetSelector module from the jimu library.

   Use dark colors for code blocksCopy

   1
   import { MapWidgetSelector } from 'jimu-ui/advanced/setting-components'

2. Within the component, define the onMapWidgetSelected function.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   // *** ADD ***
   const onMapWidgetSelected = (useMapWidgetIds: string[]) => {
     props.onSettingChange({
       id: props.id,
       useMapWidgetIds: useMapWidgetIds
     })
   }
   
   return <div className="widget-setting-demo">This is your starter widget setting area!</div>;

3. In the return() statement, add a tag representing the MapWidgetSelector.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   return (
     <div className="widget-setting-demo">
       <MapWidgetSelector useMapWidgetIds={props.useMapWidgetIds} onSelect={onMapWidgetSelected} />
     </div>
   )

Access the map

In the previous step, the settings panel was enhanced to allow the Map widget to be selected. The map object can be accessed using the JimuMapViewComponent.

1. In the widget.tsx file, add the JimuMapViewComponent and JimuMapView types from the jimu-arcgis library, and destructure the React variable to get access to the getState import.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   import { React, type AllWidgetProps } from 'jimu-core'
   /** ADD: **/
   import { JimuMapViewComponent, type JimuMapView } from 'jimu-arcgis'
   const { useState } = React

3. To add the layer to the Map, a reference to the Map must be saved into the component state. Within the component, set up the state using useState().

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   const { useState } = React
   
   const Widget = (props: AllWidgetProps<any>) => {
    // *** ADD ***//
   const [jimuMapView, setJimuMapView] = useState<JimuMapView>()
   
   return (

4. In the return section, add the JimuMapViewComponent to the JSX markup.

   More info

   The first two lines of the added code ({props.useMapWidgetIds &&...) are how to use conditionals in JSX. This is basically saying "only add the JimuMapViewComponent if the Experience author has chosen a valid map widget in the settings panel."

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   return (
     <div className="widget-starter jimu-widget">
       {props.useMapWidgetIds && props.useMapWidgetIds.length === 1 && (
         <JimuMapViewComponent useMapWidgetId={props.useMapWidgetIds?.[0]} onActiveViewChange={activeViewChangeHandler} />
       )}
     </div>
   )

5. Define the activeViewChangeHandler function, just below the setState commands. This function will be called once - when the map is ready. In this function, update the jimuMapView state.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   /** ADD: **/
   const activeViewChangeHandler = (jmv: JimuMapView) => {
     if (jmv) {
       setJimuMapView(jmv)
     }
   }

Add the button

Add a button to the UI of the widget that when clicked will add the layer to the map.

1. In the code editor, add form and input tag elements in the existing div in the render function.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   return (
     <div className="widget-starter jimu-widget">
       {props.useMapWidgetIds && props.useMapWidgetIds.length === 1 && (
         <JimuMapViewComponent useMapWidgetId={props.useMapWidgetIds?.[0]} onActiveViewChange={activeViewChangeHandler} />
       )}
   
       {/* *** ADD: *** */}
       <form onSubmit={formSubmit}>
         <div>
           <button>Add Layer</button>
         </div>
       </form>
     </div>
   )

2. Within the component, create a new function called formSubmit. This function will get called when the user clicks the Add Layer button.

   More info

   evt.preventDefault prevents the page from reloading when the form is submitted.
   Use dark colors for code blocksCopy

   1
   2
   3
   4
   const formSubmit = (evt) => {
     evt.preventDefault()
     // More here soon
   }

Add a layer

When the button is clicked, add the layer to the map.

1. At the top of widget.tsx, import the FeatureLayer class.

   Use dark colors for code blocksCopy

   1
   import FeatureLayer from 'esri/layers/FeatureLayer'

2. In the formSubmit function, update the code to create the Trailheads (points) feature layer and add it to the map.

   More info

   jimuMapView.view is an instance of MapView, so you can use any of those methods and properties, like the add() method here.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   const formSubmit = (evt) => {
     evt.preventDefault()
   
     // *** ADD ***
     // create a new FeatureLayer
     const layer = new FeatureLayer({
       url: 'https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads_Styled/FeatureServer/0'
     })
   
     // Add the layer to the map (accessed through the Experience Builder JimuMapView data source)
     jimuMapView.view.map.add(layer)
   }

Test the widget

Once the code changes have been made, you can test your widget by running Experience Builder and viewing your experience.

1. In a web browser, go to Experience Builder. e.g. https://localhost:3001

   More info

   If Experience Builder did not open a tab for you, browse to https://localhost:3001. If you get a "Invalid SSL Certificate" issue, click "Proceed Anyway".

2. In Experience Builder, click Create New to create a new experience page.

3. Click the Create button on the Blank scrolling template.

   1. Click the Insert widget button, and drag the Map widget onto the experience.
   2. Click the Map widget in the preview area, then click Select map in the widget settings panel.
   3. In the Select data panel, click the Add new data button.
   4. In the Add data modal, select the ArcGIS Online tab and search for web map eb1be6543e304b4d81ed55439c412c2c. Click the search result to select it and then click Done. (Note this web map has no operational layers intentionally.)
   5. Click the newly-added LA Parks and Trails Map in the Select data panel to select the web map.

4. Click the Insert widget button, and drag the new add-layers-to-a-map widget onto the experience.

   More info

   The widget may show an invalid icon right now. That's ok - you have not created one yet!

5. In the widget settings panel, choose Map from the map selection dropdown.

6. In the Experience Builder toolbar, click Save then Preview and the experience will open in a new browser tab with your custom widget and a map.

Congratulations, you're done!

In the Experience Builder preview, click the button to add the layer to the map. Compare your widget with our completed widget, and see the top of this page for an example for how the Experience should look.

Related topic

How to add a feature layer as a data source in a custom widget