DEV Community: Rene Rubalcava

Shadow DOM and Slots in ArcGIS Map Components

Rene Rubalcava — Thu, 06 Nov 2025 23:24:23 +0000

It's been a while since the ArcGIS Maps SDK for JavaScript released the map components. They're pretty awesome if I do say so myself! This latest 4.34 release of the Maps SDK introduced some exciting changes.

Components are all Shadow DOM enabled
New Slots UI layout
No need to import css files
Beta Popup component

Shadow DOM

If you're not familiar with Shadow DOM, it's essentially a hidden, secret DOM that is safe from the dirty CSS and JavaScript of the outside world... mostly, ha! One benefit here is that it allows each component to scope it's own styles and not be concerned about conflicts with other css on the page. The one exception here is the Calcite Design Tokens that the map components use heavily. These tokens are defined at the root of the page and can be used anywhere else, including inside the Shadow DOM.

This was a big task for Map components and also opens up some other capabilities of using web components!

Slots

One really fun update is the addition of slots for a new UI layout in Map and Scenes! The available slots can be found here. Take note that there are RTL slots, which I am pretty proud of!

Demo

<arcgis-map item-id="45725ba7d9fb47a0925398919b13d1fa">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-home slot="top-left"></arcgis-home>
  <arcgis-compass slot="top-left"></arcgis-compass>
  <arcgis-expand slot="bottom-left">
    <arcgis-legend></arcgis-legend>
  </arcgis-expand>
  <arcgis-layer-list slot="top-right"></arcgis-layer-list>
</arcgis-map>

I also want to point out that this fixes an old issue where components didn't always honor the order they were placed in the DOM as they were using an old positioning method. Now the order works as expected!

The old position attribute has been deprecated, but for now, it is backwards compatible, so it will work for this release, but please... please update your code. Pretty please.

There has been some requests to provide some specific layout options, and I don't think any solution will satisfy everyones needs, but you can integrate your own custom layout if you need it. Here is a demo that places the directional-pad in the center of the map and only visible when you hover over it. So if you need some custom layout options, you can definitely implement your own.

Where's my CSS?

You might notice in the samples there is no css added for the Maps SDK or Calcite. Each component loads it's own css, so no need to add the ArcGIS css file for light or dark.

How do you get dark mode? Oh my friend, that is such a nice story now.

Demo

<body class="calcite-mode-dark"></body>

Since the Map components use Calcite, it follows the same conventions for their modes!

Geez, wish I had more to say here, but it's pretty self explanatory. You don't need to add css. Fin.

Beta Popup Component

The arcgis-popup is in beta for the 4.34 release. Why? It works great, but it needs a little more time to cook, let us cook! You can start playing around with it now by adding it to the popup slot of the map or scene component.

<arcgis-map item-id="06ca49d0ddb447e7817cfc343ca30df9">
  <arcgis-popup slot="popup"></arcgis-popup>
</arcgis-map>

Why a popup slot? This lets the map/scene component know you are overriding the default popup on click. That's key right now, this only takes over the popup used when you click on the map. The search component still uses the popup widget. However, you won't see two popups at the same time, that won't happen.

Try it out, provide some feedback. This is an awesome addition to the library and I'm proud of the team that got this working!

Summary

The 4.34 release of the ArcGIS Maps SDK for JavaScript components had some great updates that really push the component story forward. Shadow DOM and Slots was a big undertaking and opened up the path to fully embrace the full suite of web component technologies!

Drop any questions down below, take the components for a spin, provide some feedback and build some awesome apps!

View video!

[Boost]

Rene Rubalcava — Fri, 20 Dec 2024 20:25:52 +0000

Enhance Your ArcGIS Web App with OpenAI

Courtney Yatteau ・ Dec 20

#ai #openai #javascript #webdev

ArcGIS Map Components Released

Rene Rubalcava — Fri, 28 Jun 2024 17:32:12 +0000

Introduction

A few years ago, I demoed a prototype of web components using the ArcGIS Maps SDK for JavaScript to my colleagues – which at the time was called the ArcGIS API for JavaScript – that's five extra keystrokes if you're keeping track. It was just an idea and believe me – I have plenty of ideas. It was something that had the potential to benefit to users and other developers at Esri. For current users, it could simplify how much code they need to write and take advantage of components to write basic applications. They can also be a gentle introduction to the maps SDK using HTML and CSS with minimal JavaScript. I knew there was other web component work being done – of course Calcite Components, and applications such as the Map Viewer, Instant Apps, and more were using web components to make it easier to reuse components in applications. I was lucky enough to have a spark at the right time and join a team with a goal to make it easier for internal developers to not only use web components – but to build their own.

At Developer Summit 2024, the Map components were announced as a beta release. This was a huge step above the initial crude implementation, but with the help of a solid team, we were able to get them in a good spot. More importantly, we were able to get more developers testing and providing feedback. With the help of that feedback, as of the 4.30 release of the ArcGIS Maps SDK for JavaScript, the map components are now officially out of beta. This means a defined API, naming conventions, and they should work as advertised. Are they perfect? Sounds like a philosophical question to me, but they are stable. There is of course what we would call under-the-hood work to be done. There are plans to have additional web component features in a future release. I'm not a fortune-teller though, so don't ask me when – but when they are added you will know.

Map Components

What are the map components? They are a collection of custom elements that let you compose HTML to build an application. In many cases you only need an item id for a webmap or webscene from ArcGIS Online or your own Enterprise portal. You may not even need to write JavaScript. The components can be used almost anywhere. The advantage is they are portable across applications and tooling.

Things to know

Here are a few things I think you should know when working with components.

1. Events

In the map components, we can make a distinction between view components and UI components. View components would be the arcgis-map and arcgis-scene. These two components are the equivalent of the MapView and SceneView in the core API. I only bring this up because these two components have a specific event called arcgisViewReadyChange.

const mapElement = document.querySelector("arcgis-map");
mapElement.addEventListener("arcgisViewReadyChange", (event) => {
  // Continue work that might include adding layers or more
});

This event will fire when the component is ready to be used. If you have ever used view.when() with the core API, that's how this works. This event only fires once – unless you change the map property. Yes, you can do that.

// Assign a WebMap to a Map Component
// Using CDN, similar with NPM package
const arcgisMap = document.querySelector("arcgis-map");

async function load() {
  // Change the WebMap
  const WebMap = await $arcgis.import("esri/WebMap");
  arcgisMap.map = new WebMap({
    portalItem: { id: "e691172598f04ea8881cd2a4adaa45ba" }
  });
}

load();

// You can defer loading components to do
// authentication for example
async function load() {
    const IdentityManager = await $arcgis.import("esri/identity/IdentityManager");
    const OAuthInfo = await $arcgis.import("esri/identity/OAuthInfo");

    // Do your authentication steps here

    // When ready, load the components library and it will pick up
    // the authentication you have done.
    await import("https://js.arcgis.com/map-components/4.30/arcgis-map-components.esm.js");
}

load();

Another event that is common across all components is arcgisPropertyChange. Before I dive into this event, you need to remember that custom elements are a standard and there are standard ways to know when DOM elements have changed. Event listeners and Mutation Observers. If you have used the core API, you are probably familiar with the Accessor and watching for property changes. This is a convenient pattern – in the core API. For custom elements, not so much. There was quite a bit of discussion on whether we should implement a DOMReactiveUtils that would work just on map components. But this isn't part of the standard, it wouldn't work anywhere else except map components and honestly, goes against the grain of the web platform.

What does this have to do with arcgisPropertyChange? This event will fire when some properties on a component change. This lets you do something in your application that might need to know when a property has changed. When this event fires it will provide the name of the property that changed, and you can then access that value from the component.

const features = document.querySelector("arcgis-features");
features.addEventListener("arcgisPropertyChange", (event) => {
  // name: event.detail.name
  // value: features[event.detail.name]
});

Some properties are also attributes (more on that in a moment). What makes a property an attribute? It must be either a boolean, string, or number. But if the updates are reflected to the element, you can use a MutationObserver.

An event like arcgisViewReadyChange that is available on UI components is arcgisReady. This means the component is ready. I've written a lot of test apps and so far, I haven't used this event, but it's there in case you need it – someone will.

2. Attributes and Properties

With HTML elements, it's key to understand the difference between attribute and properties. This topic can cause confusion for developers when trying to set properties as attributes or expecting certain value types when accessing properties.

Let's start with attributes. Attributes are values that can be set directly in the DOM on an element. Here are some examples.

<input type="text" value="Bob" />
<button type="submit">Submit</button>
<my-element show-children origin="home"></my-element>

Technically, all attributes are only string values. Even a boolean value is either null or an empty string "". Technically it is truthy or falsey. What could possibly go wrong here?

Attributes are also always kebab-case. Don't try to set showChildren as an attribute on the custom element, the proper name is show-children.

You can access attributes via element.getAttribute("value") and set attributes via element.setAttribute("value"). For boolean attributes, you can use element.toggleAttribute("show-children").

Properties however can only be accessed via JavaScript: console.log(element.currentValue). Properties cannot be set as attributes, but that doesn't mean they can't be related. A property can also be an alias for attribute and vice versa.

You might have a property called valueHistory that is an array that tracks value attribute changes. This property can be accessed internally by the component or by users that might be interested in using these entries in their application.

The key here is that properties can be objects or arrays. Attributes can be string, number, or boolean.

3. Frameworks

Events and property/attribute assignment are some core basics you should know when working with not only components, but the DOM in general. But you can also use libraries and frameworks to make this easier to deal with. For example, in React, you can assign complex objects to components.

<ArcgisMap
  itemId="d5dda743788a4b0688fe48f43ae7beb9"
  popup={
    {
      dockEnabled: true,
      dockOptions: {
        position: "bottom-right",
        breakpoint: false,
      },
    }
  }
  theme={
    {
      accentColor: "purple",
      textColor: [125, 255, 13, 0.9],
    }
  }
  onArcgisViewReadyChange={() => {
    console.log("Map is ready");
  }}
>
  <ArcgisSearch position="top-right" />
  <ArcgisExpand position="bottom-left">
    <ArcgisAreaMeasurement2d />
  </ArcgisExpand>
</ArcgisMap>

All those rules about property assignment and objects mentioned earlier can be thrown out the window when talking about most frameworks. They will handle correct property assignment for you.

In a DevSummit presentation, I did a quick rundown showing how you can use them with everything from React to Laravel, even an Elm application. Some may have thought I went too far – I like to think I went far enough. The components provide framework wrappers for React and Angular. But with upcoming release of React 19, you shouldn't need the wrapper.

// Example using React 19
import { defineCustomElements } from "@arcgis/map-components/dist/loader";
import './App.css';

defineCustomElements();

function App() {
  const popupConfig = {
    dockEnabled: true,
    dockOptions: {
      position: "bottom-right",
      breakpoint: false,
    },
  };
  return (
    <div className='app-container'>
      <arcgis-map
        popup={popupConfig}
        item-id="e691172598f04ea8881cd2a4adaa45ba"
        onarcgisViewReadyChange={() => console.log("ready")}></arcgis-map>
    </div>
  )
}

export default App

Samples

In addition to the documentation, patterns and tutorials, there are more samples you can review here. These samples provide a good starting point. You will notice that hanging out among React and Vue samples is a CDN sample. It's important to note that the CDN is a completely viable way to build some applications. You don't always need a framework. You don't always need a build tool. Sometimes you just need some HTML and a dash of CSS. I'm a fan of simplicity.

Summary

The addition of components to the ArcGIS Maps SDK for JavaScript provides some new options and powerful features to developers. The intention is that it makes adding mapping capabilities to your applications easier and provides some reusability. With a script and link tag, you can add maps to a WordPress site, Shopify store or any other static page without having to worry about writing additional JavaScript. And for new users who want to display a map quickly on the page, they can focus on other capabilities of the SDK like queries and visualization.

Intro to Binning with ArcGIS API for JavaScript

Rene Rubalcava — Tue, 27 Sep 2022 15:15:58 +0000

What the bin?

There's an option for layers in the ArcGIS API for JavaScript called featureReduction. Up until recently, you could use it to define clusters of features in your application. FeatureReduction is a way to summarize data visually on the map. For clusters, this means the amount of features in the cluster determine how large the cluster is. Recently, the API introduced the ability use binning for FeatureReduction. For more details on binning, I highly recommend you read this blog post!

Here is a codepen of the sample used in this post.

Adding binning to my features

I have this webmap that I like to use when I want to demonstrate using a large amount of features. The service over 2 million points, so it's a pretty good test map and layer. The first thing to do is define a bin level.

const layer = new FeatureLayer({
    portalItem,
    featureReduction: {
        type: "binning",
        fixedBinLevel: 4
    }
});

The fixedBinLevel will keep the bins the same size regardless of how much you zoom in and out. Depending on your dataset, and the scale you plan to use, this could take some tweaking, but once you've found a good level, you are all set.

FeatureReduction Renderer

One of the first things you would normally do is set up your aggregateFields, where you can set up the statistics for your bins. My service doesn't have a numeric field I could really use, so I won't set it up, but this is a great way to aggregate your data for visualizations. By default, bins will have an aggregateCount field I can use.

const layer = new FeatureLayer({
    portalItem,
    featureReduction: {
        type: "binning",
        fixedBinLevel: 4,
        renderer: {
            type: "simple",
            symbol: {
                type: "simple-fill",
                color: [0, 255, 71, 1],
                outline: null,
                outline: {
                    color: "rgba(153, 31, 23, 0.3)",
                    width: 0.3
                }
            },
            visualVariables: [
                {
                    type: "color",
                    field: "aggregateCount",
                    legendOptions: {
                        title: "Number of Places"
                    },
                    stops: [
                        { value: 0, color: "#d7e1ee" },
                        { value: 25, color: "#cbd6e4" },
                        { value: 75, color: "#b3bfd1" },
                        { value: 200, color: "#c86558" },
                        { value: 300, color: "#991f17" }
                    ]
                }
            ]
        }
    }
});

Ok, so in this renderer, I set up some visual variables that will define bin colors based on the amount of features in the bin. Notice that all these properties are part of the featureReduction of the layer, not the root of the layer itself.

Adding Labels

Not only can define a renderer for the bins, you can define labels! I'll admit though, this might be something you want to toggle, because it can get busy. I would say, use bin labels cautiously.

labelingInfo: [
    new LabelClass({
        minScale: 0,
        maxScale: 0,
        deconflictionStrategy: "none",
        symbol: {
            type: "text",
            color: "white",
            font: {
                family: "Noto Sans",
                size: 10,
            },
            haloColor: "gray",
            haloSize: 0.5,
        },
        labelExpressionInfo: {
            expression: "Text($feature.aggregateCount, '#,###')",
        },
    }),
]

Notice we can use an arcade expression for the aggregate fields "Text($feature.aggregateCount, '#,###')", for labels. When it comes to arcade, $feature refers to the binned feature. not any of the source features.

Color Ramps

I want to touch on a pretty cool feature in the documentation for the ArcGIS API for JavaScript. That would be the Esri Color Ramps. I don't know about you, but I don't exactly have the skill set to be creating hand crafted artisanal color ramps for my visual variables. What's great is you can browse the color ramps, filter them by type and color scheme, then they provide a nice copy button for hex values. The best part? The copy button adds a JavaScript snippet to your clipboard you can paste right into you applications!

// #48385f|#995375|#db4a5b|#fc9a59|#fee086
const colors = ["#48385f", "#995375", "#db4a5b", "#fc9a59", "#fee086"];

Now, I can update my visual variables to use them!

visualVariables: [
    {
        type: "color",
        field: "aggregateCount",
        legendOptions: {
            title: "Number of Places",
        },
        stops: [
            { value: 0, color: colors[4] },
            { value: 25, color: colors[3] },
            { value: 75, color: colors[2] },
            { value: 200, color: colors[1] },
            { value: 500, color: colors[0] },
        ],
    },
],

Look at that! Have more stops? Less stops? You can filter the color ramps to find what suits your needs!

Summary

Using bins for feature reduction and aggregating data is a great way to visualize your larger datasets. Visually, a large amount of points may not tell the story you want. Tools like binning and clusters, especially with aggregate fields can help you make the maps and apps that make your data shine!

You can watch a video on this topic below!

Intro to Calcite with Svelte

Rene Rubalcava — Mon, 08 Aug 2022 22:33:29 +0000

Web Components

If you have been building web apps for any amount of time, you have probably come across Web Components. Web Components have a lot to offer. They let you build a set of common components that can be used anywhere, regardless of the framework that you use. I won't go into detail on on this, but want to highlight that you can use a library of Web Components, like Calcite Components in your own applications. Today, it is easier to use Web Components in some frameworks than in others. One of the friendliest ones is Svelte.

For this post, we are going to follow this Calcite Components tutorial to build a mapping app, but using Svelte!

The source code for the demo in this blog post is on github.

Getting started

You can read a great intro on using Svelte with the ArcGIS API for JavaScript on the Esri blog.

We can start building a Svelte app by using Vite, and yes, I use Vite for just about everything these days.

npm init @vitejs/app svelte-calcite
cd svelte-calcite
npm install @arcgis/core

Once installed, we can install the ArcGIS API for JavaScript. The Calcite Components library will be installed with it. At this point we can empty the css and .svelte files in the scaffold application. We can add some basic CSS to get started.

/** app.css **/
@import "https://js.arcgis.com/calcite-components/1.0.0-beta.86/calcite.css";
@import "https://js.arcgis.com/4.24/esri/themes/light/main.css";

html,
body,
#app {
  padding: 0;
  margin: 0;
  height: 100%;
  width: 100%;
}

Making a mapping app

We can then start updating our App.svelte component, following the mapping tutorial. We can just start with the HTML skeleton of the app.

<calcite-shell content-behind>
    <h2 id="header-title" slot="header">
    <!-- Dynamically populated -->
    </h2>
    <calcite-shell-panel slot="primary-panel" detached>
    </calcite-shell-panel>
    <div class="viewDiv"></div>
</calcite-shell>

This provides the basic shell for the app, but we still need to hook this up to some other pieces to display a map.

<script>
  // calcite components
  import "@esri/calcite-components/dist/components/calcite-shell";
  import "@esri/calcite-components/dist/components/calcite-shell-panel";

  // arcgis js api
  import config from "@arcgis/core/config";
  import WebMap from "@arcgis/core/WebMap";
  import MapView from "@arcgis/core/views/MapView";

  import { onMount } from "svelte";

  config.apiKey = import.meta.env.VITE_API_KEY;

  let viewContainer;

  let item = {};

  onMount(() => {
    const map = new WebMap({
      portalItem: {
        id: "cc3bd744b9a44feaa493dd867a1d48dd",
      },
    });
    const view = new MapView({
      container: viewContainer,
      map,
      padding: {
        left: 49,
      },
    });

    view.ui.move("zoom", "bottom-right");

    map.when(() => {
      item = map.portalItem;
    });
  });
</script>

We are doing a few things here to start. First, we are importing the modules from Calcite Components that we are using in our app so far. If we don't, they don't register as custom elements and won't be displayed. Then we define a couple of variables that ca be referenced in the page. Svelte has a very clear way of binding variables and making them reactive. This is a breath of fresh air coming from some other frameworks. The viewContainer will be used a reference to the element we can display our map at, and the item object can referenced to display some text for us.

<calcite-shell content-behind>
    <h2 id="header-title" slot="header">
    {item.title || "...loading"}
    </h2>
    <calcite-shell-panel slot="primary-panel" detached>
    </calcite-shell-panel>
    <div class="viewDiv" bind:this={viewContainer} />
</calcite-shell>

Notice that we just reference the item.title and when we updates that variable, it will be reflected in our page. We are using the bind:this syntax to bind the viewContainer variable to the div element. The this refers to the element you are using the bind: syntax on. I really dig that API.

The next step in the tutorial is to set up the action bar and panels where the widget goes.

<calcite-shell content-behind>
  <h2 id="header-title" slot="header">
    {item.title || "...loading"}
  </h2>
  <calcite-shell-panel slot="primary-panel" detached>
    <calcite-action-bar slot="action-bar">
      <calcite-action data-action-id="layers" icon="layers" text="Layers" />
      <calcite-action
        data-action-id="basemaps"
        icon="basemap"
        text="Basemaps"
      />
      <calcite-action data-action-id="legend" icon="legend" text="Legend" />
      <calcite-action
        data-action-id="bookmarks"
        icon="bookmark"
        text="Bookmarks"
      />
      <calcite-action data-action-id="print" icon="print" text="Print" />
      <calcite-action
        data-action-id="information"
        icon="information"
        text="Information"
      />
    </calcite-action-bar>

    <calcite-panel
      heading="Layers"
      height-scale="l"
      data-panel-id="layers"
      hidden
    >
      <div id="layers-container" bind:this={layerListContainer} />
    </calcite-panel>
    <calcite-panel
      heading="Basemaps"
      height-scale="l"
      data-panel-id="basemaps"
      hidden
    >
      <div id="basemaps-container" bind:this={bmgContainer} />
    </calcite-panel>
    <calcite-panel
      heading="Legend"
      height-scale="l"
      data-panel-id="legend"
      hidden
    >
      <div id="legend-container" bind:this={legendContainer} />
    </calcite-panel>
    <calcite-panel
      heading="Bookmarks"
      height-scale="l"
      data-panel-id="bookmarks"
      hidden
    >
      <div id="bookmarks-container" bind:this={bookmarksContainer} />
    </calcite-panel>
    <calcite-panel
      heading="Print"
      height-scale="l"
      data-panel-id="print"
      hidden
    >
      <div id="print-container" bind:this={printContainer} />
    </calcite-panel>
    <!-- Info panel (populates with info from the web map) -->
    <calcite-panel heading="Details" data-panel-id="information" hidden>
      <div id="info-content">
        <img
          id="item-thumbnail"
          alt="webmap thumbnail"
          src={item.thumbnailUrl}
        />
        <div id="item-description">
          <!-- Dynamically populated -->
          {item.description}
        </div>
        <calcite-label layout="inline">
          <b>Rating:</b>
          <calcite-rating id="item-rating" read-only>
            <!-- Dynamically populated -->
            {item.avgRating}
          </calcite-rating>
        </calcite-label>
      </div>
    </calcite-panel>
  </calcite-shell-panel>
  <div class="viewDiv" bind:this={viewContainer} />
</calcite-shell>

Ok, we added a lot now. We have some more components and an action bar that let's us add buttons and toggle the visibility of some widgets. We are using the same bind:this syntax we used earlier. Since we added more components, we need to import some more modules, plus we can start initializing our widgets.

<script>
  // calcite components
  import "@esri/calcite-components/dist/components/calcite-shell";
  import "@esri/calcite-components/dist/components/calcite-shell-panel";
  import "@esri/calcite-components/dist/components/calcite-action";
  import "@esri/calcite-components/dist/components/calcite-action-bar";
  import "@esri/calcite-components/dist/components/calcite-panel";
  import "@esri/calcite-components/dist/components/calcite-label";
  import "@esri/calcite-components/dist/components/calcite-rating";

  // arcgis js api
  import config from "@arcgis/core/config";
  import WebMap from "@arcgis/core/WebMap";
  import MapView from "@arcgis/core/views/MapView";
  import Bookmarks from "@arcgis/core/widgets/Bookmarks";
  import BasemapGallery from "@arcgis/core/widgets/BasemapGallery";
  import LayerList from "@arcgis/core/widgets/LayerList";
  import Legend from "@arcgis/core/widgets/Legend";
  import Print from "@arcgis/core/widgets/Print";
  import { onMount } from "svelte";

  config.apiKey = import.meta.env.VITE_API_KEY;

  let viewContainer;

  let bookmarksContainer;
  let bmgContainer;
  let layerListContainer;
  let legendContainer;
  let printContainer;

  let item = {};

  onMount(() => {
    const map = new WebMap({
      portalItem: {
        id: "cc3bd744b9a44feaa493dd867a1d48dd",
      },
    });
    const view = new MapView({
      container: viewContainer,
      map,
      padding: {
        left: 49,
      },
    });

    view.ui.move("zoom", "bottom-right");

    const basemaps = new BasemapGallery({
      view,
      container: bmgContainer,
    });
    const bookmarks = new Bookmarks({
      view,
      container: bookmarksContainer,
    });
    const layerList = new LayerList({
      view,
      selectionEnabled: true,
      container: layerListContainer,
    });
    const legend = new Legend({
      view,
      container: legendContainer,
    });
    const print = new Print({
      view,
      container: printContainer,
    });

    map.when(() => {
      item = map.portalItem;
    });
  });
</script>

At this point, our application is nearly complete. Except we have no way to toggle the widgets yet. The mapping tutorial has this code syntax we can reuse exactly as-is.

let activeWidget;

const handleActionBarClick = ({ target }) => {
if (target.tagName !== "CALCITE-ACTION") {
    return;
}

if (activeWidget) {
    document.querySelector(`[data-action-id=${activeWidget}]`).active = false;
    document.querySelector(`[data-panel-id=${activeWidget}]`).hidden = true;
}

const nextWidget = target.dataset.actionId;
if (nextWidget !== activeWidget) {
    document.querySelector(`[data-action-id=${nextWidget}]`).active = true;
    document.querySelector(`[data-panel-id=${nextWidget}]`).hidden = false;
    activeWidget = nextWidget;
} else {
    activeWidget = null;
}
};

We just need to add the event listener to our action bar.

<calcite-action-bar slot="action-bar" on:click={handleActionBarClick}>
...
</calcite-action-bar>

The on:eventname syntax is how you can add event listeners in Svelte.

Now our application is complete and you should be able to view the map, and toggle the widgets.

Summary

I'm not a Svelte power-user, but it is quickly growing on me. Any framework that can make it easier for me to use Web Components I am a fan of. Calcite Components is also a great Web Component library for building ArcGIS Platform apps.

You can watch this video for more information!

My Secret ArcGIS Identity

Rene Rubalcava — Mon, 01 Aug 2022 21:10:00 +0000

Your Identity Matters

There will probably come a time when you are tasked to include private data in your ArcGIS web mapping applications. There are different types of Identity you can work with depending on your organization or account. I won't get into Developer Accounts and API Keys here, but I have talked about that before. This workflow is for the organization devs that need use OAuth for their apps.

The source for the code in this post can be found on github.

OAuth Flow

When working with the ArcGIS API for JavaScript, you're going to want to use the IdentityManager. The IdentityManager is going to handle all your OAuth needs. It will even kick in by default, if your application hits a service that requires authentication and you have not set it up. The drawback here is that the credentials won't get saved for next time if you don't do the set up. So let's walk through the basics of what you probably want to do in your application.

Set up authentication.
Check if user is signed in.
Provide a way to sign in.
Provide a way to sign out.

I've done this enough times that I have a module I use frequently.

1. Setting up OAuth

Before we dive in to the various steps, let's quickly talk about setting up your OAuth. First thing you will want to do is register your application in your account. This will provide your with the client ID you will need to register it with the IdentityManager. This can be done with the OAuthInfo module, via the appId property.

export const initialize = (appId) => {
    const oauthInfo = new OAuthInfo({ appId });
    IdentityManager.registerOAuthInfos([oauthInfo]);
    return oauthInfo;
};

2. Check if the user is signed in

Just our luck, the IdentityManager provides a method we can use to check the sign in status. This method will check if we signed in to the designated portal url and return the credentials if we are.

export const checkCurrentStatus = async (oauthInfo) => {
    try {
        const credential = await IdentityManager.checkSignInStatus(
            `${oauthInfo.portalUrl}/sharing`
        );
        return credential;
    } catch (error) {
        console.warn(error);
    }
};

3. Let a user sign in

Now that we have a way to check if the user is signed in, we can use it as part of our workflow to allow a user to sign in. When the user signs in, we can do our due diligence and check if they have any existing credentials. If they don't, we can kick off the workflow to fetch those credentials and this will load the OAuth sign process.

export const signIn = async (oauthInfo) => {
    try {
        const credential = await checkCurrentStatus(oauthInfo)
            || await fetchCredentials(oauthInfo);
        return credential;
    } catch (error) {
        const credential = await fetchCredentials(oauthInfo);
        return credential;
    }
};

The fetchCredentials method used here looks like this.

export const fetchCredentials = async (oauthInfo) => {
    try {
        const credential = await IdentityManager.getCredential(
            `${oauthInfo.portalUrl}/sharing`
        );
        return credential;
    } catch (error) {
        console.warn(error);
    }
};

When you registered your application in step one, you would have set up a redirect URI, that would allow your application be authenticated. I highly recommend you have a client ID for development, and another for production. Your development client ID would redirect to your local development URI. Your production to your production location. There are numerous ways you can set this up in your build tooling using environment variables, and build scripts.

When you use the IdentityManager.getCredential method, this will either open a popup with the ArcGIS Oauth login or direct the current page to the OAuth login, depending on how you set up your OAuthInfo. If you are have the popup set to true in OAuthInfo, you will need this oauth-callback page hosted with your application.

4. Sign out

With a way to sign in, now we need a way to sign out. Lucky for us, the IdentityManager simplifies this step with the destroyCredentials method.

export const signOut = async () => {
    IdentityManager.destroyCredentials();
    window.location.reload();
};

Once you destroy the credentials, you will also want to reload the page. It's important to note, if you are logged in to ArcGIS Online in your browser as well, this will not log you out of those pages. But this will provide you with a pretty basic sign out process for your application.

Summary

Working with Identity in any application can seem a little daunting at first, but the ArcGIS API for JavaScript provides all the tooling you'll need to set it up in your apps as needed. Ideally, this will help to simplify the login process for you as a developer and your users. As I mentioned earlier, there can be various Identity workflows. If you have an Enterprise installation, this could include various implementations I haven't covered, and honestly, I am not familiar with many of them. Usually, in that environment, authentication is pass-through and should just work. But don't quote me on that.

You can see more in the video below!

View Padding in the ArcGIS API for JavaScript

Rene Rubalcava — Fri, 22 Jul 2022 16:06:58 +0000

View your Padding

The ArcGIS API for JavaScript provides several ways to help developers build a user interface.
It provides numerous out-of-the-box widgets, styled using the Calcite Design System. Each View provides a user interface (UI) element that users can use to define layouts around their map. You can add widgets or your own custom HTML elements. Sometimes, this can lead to some odd use cases if you want to keep the focus of your application on the map. That's where view padding comes in!

The code for this blog is available on github.

View padding allows you to offset the center of the map within the UI. It's not much more complicated than that. This is useful if you want to display a side panel, or some widgets on one side of the map, but keep the focus on the map. You can apply some view padding to line things up. As the padding changes, so does the map's focal center point.
Okay, that's fine and all, but how about if it's a dynamic sidebar with animation? And you want to adjust the padding dynamically?

Let's have some fun!

Electric Slide

Before we dive into some code, let's talk about what you might want to accomplish.

Show tools in a side panel.
Animate side panel drawer.
Dynamically adjust view padding with drawer animation.

You can have the side panel start in a negative position, say -280 off the screen. So you will want to animate the position of the element from -280 to 0. At the same time, you will want to adjust the view padding to positive 280 to make room for the element and adjust the center of the map.

Now, math is not one of my greater strengths, at least not when it comes to stuff like easing functions, so I'm sure I found much of this animation function via Google and StackOverflow.

const margin = -280;

const identity = ((a: any) => a);
const duration = 500;
function animate(options = {
  easing: identity,
  onProgress: identity,
  onComplete: identity,
  from: {},
  to: {}
}) {
  const {
    easing,
    onProgress,
    onComplete,
    from,
    to
  } = options;

  const startTime = Date.now();

  function update() {
    let deltaTime = Date.now() - startTime;
    let progress = Math.min(deltaTime / duration, 1);
    let factor = easing(progress);
    let values = {};

    for (let k in from) {
      if (k) {
        values[k] = from[k] + (to[k] - from[k]) * factor;
      }
    }

    onProgress(values);

    if (progress === 1) {
      onComplete(deltaTime);
    }
    else {
      requestAnimationFrame(update);
    }
  }

  requestAnimationFrame(update);
}

What this function is doing is getting the start time for the animation, so you can track its progress to completion. As the animation progresses, you can use requestAnimationFrame to create a smooth animation in JavaScript.

Here are some of the helper methods and the easing function.

// easing function
function inSine(t: number) {
    return -Math.cos(t * Math.PI / 2) + 1;
}

// update the view padding object
function updatePadding(value: number) {
    return {
        left: value - margin + defaultPadding
    }
}

// expand the view padding
function expand() {
    animate({
        easing: inSine,
        onProgress({ a }: { a: number; }) {
            slider.style.marginLeft = `${a}px`;
            view.padding = updatePadding(a);
        },
        onComplete() {
            btnExpand?.removeEventListener('click', expand);
            btnExpand?.addEventListener('click', collapse);
        },
        from: {
            a: margin
        },
        to: {
            a: 0
        }
    });
}

// collapse the view padding
function collapse() {
    animate({
        easing: inSine,
        onProgress({ a }: { a: number }) {
            slider.style.marginLeft = `${a}px`;
            view.padding = updatePadding(a);
        },
        onComplete() {
            btnExpand?.removeEventListener('click', collapse);
            btnExpand?.addEventListener('click', expand);
        },
        from: {
            a: 0
        },
        to: {
            a: margin
        }
    })
}

btnExpand?.addEventListener('click', expand);

In the application, you can use the edge of the side panel as the button to open and close the panel. This can be treated like a button with a click event, so depending on whether or not you opening or closing the panel, you can add and remove the proper event listeners.

Summary

Adjusting view padding can be very handy in cases where you want to add a header to the map view, maybe custom components that have sliding panels and can change their sizes dynamically during use. Have some fun with it, you never know what you might find.

You can see a walkthrough of this application in the video below!

Web Speech API with ArcGIS RouteLayer

Rene Rubalcava — Tue, 14 Jun 2022 20:30:12 +0000

Stop for directions

The ArcGIS API for JavaScript recently added a RouteLayer that you can use to visualize the results of turn-by-turn directions, along with information about the route, like the stops and any barriers. It can be stored as an individual item in ArcGIS Online, or as part of a WebMap. There's a great intro sample in the documentation you can refer to. I was pretty excited when I first saw the RouteLayer, for one ridiculous reason... I wanted to run it through the Web Speech API.

Follow me for a second here! You have service trucks on the road and they are using your web application to get routed to various work locations. The work locations might be assigned at the beginning of the day. Maybe you've added some functionality to update the route while they are driving, due to priority or maybe someone canceled an appointment. This might push an alert on the device and reroute them with a new RouteLayer. But the user is driving, they can't be bothered to pick up the phone and read the directions. Safety first people! You have no other choice, you must use the Web Speech API!

Tell me what to do

The code for this blog post is available on github.

We can take this original sample and modify it a little bit. We can grab the speechSynthesis of the window object.

const synth = window.speechSynthesis;

The RouteLayer has a directionsPoint property made up of a Collection of DirectionPoints. Each DirectionPoint has a displayText property with the direction information associated with that point.

In a production application, you would probably create a buffer around the user's current location, and measure along the route to the next DirectionPoint. When you get within a certain distance, you might want to prefix the text with In a quarter-mile... or something similar. For demonstration purposes, we can iterate through the DirectionPoint Collection. We can add a short 1 to 2-second timeout between locations to make the speech pattern a little more natural. To simplify this, we can convert the Collection to an array and then get the values as a new array iterator. This will make navigating the points a little easier.

We can now create a new instance of an utterance using SpeechSynthesisUtterance and the display text of the DirectionPoint. We can call speak on the SpeechSynthesis and when the utterance is complete, we'll wait 1500ms and move on to the next set of directions. At each DirectionPoint, we can even add a marker and center the map to highlight the current point.

let utterance = new SpeechSynthesisUtterance(point.displayText);
utterance.addEventListener('end', () => {
    const { value, done } = points.next();
    if (done) return;

    setTimeout(() => {
        speakToMe(value);
    }, 1500);
});

synth.speak(utterance);

Once the iteration is done. we can do nothing and the directions are done!

Summary

The RouteLayer formalizes directions in the ArcGIS Platform that can be consumed in your web mapping applications. You don't have to use the Web Speech API, but it's so much fun, so why not give it a shot! You could use it with directions, alerts, or maybe some really important notification that must be shouted at the user! My point is, it sure is fun, so have some fun!

You can see a walkthrough of this application in the video below!

Custom Content in ArcGIS API Popups

Rene Rubalcava — Thu, 02 Jun 2022 14:02:19 +0000

Pop it up

I've always maintained that probably the most used widget in the ArcGIS API for JavaScript is the Popup. Aside from zoom... You're first instinct when you see a web map with features it try and click on them. Legends are great, and visualizations are incredibly powerful at telling a story with your data, but sometimes you just want info about a particular feature or location. This is where the Popup shines!

By default, the Popup will usually show you tabular information about the feature attributes. Quick, simple, and to the point. You could have charts, attachment information, even use Arcade expressions in your Popups. I highly recommend you take advantage of the MapViewer to author your Popups. This way you get a real-time experience of what your Popups will look like. But, that doesn't mean you can't get a little creative building custom content for your popups. Let's have some fun.

Do what you want

As discussed, there are various types of content you can use in Popups.The most interesting one for developers might be CustomContent. Using CustomContent, you can return an HTML element, a widget, a string, anything that can be displayed. It also supports Promises, so you can execute numerous asynchronous tasks before returning the content. This sample does a great job showing how you can run some statistics in the Popup and return a Search widget. Are you following me? A widget in your Popup! You could even load another Map or Scene in the Popup if you want.

Maybe you would like to display weather information about the location for your Popup. There is a completely free weather API you can use from the National Weather Service for something like this. You can get the coordinates from the graphic for your Popup and use it query the weather API to get a forecast of weather information.

The code for this blog post is available on codepen

Let's assume I have a FeatureLayer of cities, which is a pretty good use case for displaying some weather information. I might want to show both the tabular information for a single field, and my custom content of weather forecasts. I could define my PopupTemplate like this.

const layer = new FeatureLayer({
  popupTemplate: {
    title: "{NAME}",
    outFields: ["*"],
    content: [
      new FieldsContent({
        fieldInfos: [
          {
            fieldName: "POPULATION",
            label: "Population",
            format: {
              places: 0,
              digitSeparator: true,
            },
          },
        ],
      }),
      new CustomContent({
        creator: async ({ graphic }) => {
          const { latitude, longitude } = graphic.geometry;
          const response = await fetch(
            `https://api.weather.gov/points/${latitude},${longitude}`
          );
          const results = await response.json();
          const { forecast } = results.properties;
          const forecastResponse = await fetch(forecast);
          const data = await forecastResponse.json();
          const { periods } = data.properties;
          const element = document.createElement("div");
          let fragment = `<h3>Weather Forecast</h3><br/>`;
          for (let a of periods) {
            fragment += `
                <image width="36" height="36" src=${a.icon}><br/>
                <strong>Name</strong>: <span>${a.name}</span><br/>
                <strong>Forecast</strong>: <span>${a.shortForecast}</span><br/>
                <strong>Temp</strong>: <span>${a.temperature}${a.temperatureUnit}</span><br/>
                <strong>Wind</strong>: <span>${a.windSpeed}, ${a.windDirection}</span><br/>
                <hr/>
            `;
          }
          element.innerHTML = fragment;
          return element;
        },
      }),
    ],
  },
  ...
});

Ok, let's take a step back here. We have an array for the popupTemplate.content that contains a FieldsContent and a CustomContent.

new FieldsContent({
    fieldInfos: [
        {
        fieldName: "POPULATION",
        label: "Population",
        format: {
            places: 0,
            digitSeparator: true,
        },
        },
    ],
})

This will display a single Population field in tabular form. This is pretty simple. Let's take a look at the CustomContent.

new CustomContent({
    creator: async ({ graphic }) => {
        const { latitude, longitude } = graphic.geometry;
        const response = await fetch(
          `https://api.weather.gov/points/${latitude},${longitude}`
        );
        const results = await response.json();
        const { forecast } = results.properties;
        const forecastResponse = await fetch(forecast);
        const data = await forecastResponse.json();
        const { periods } = data.properties;
        const element = document.createElement("div");
        let fragment = `<h3>Weather Forecast</h3><br/>`;
        for (let a of periods) {
        fragment += `
            <image width="36" height="36" src=${a.icon}><br/>
            <strong>Name</strong>: <span>${a.name}</span><br/>
            <strong>Forecast</strong>: <span>${a.shortForecast}</span><br/>
            <strong>Temp</strong>: <span>${a.temperature}${a.temperatureUnit}</span><br/>
            <strong>Wind</strong>: <span>${a.windSpeed}, ${a.windDirection}</span><br/>
            <hr/>
        `;
        }
        element.innerHTML = fragment;
        return element;
    },
})

The key here is using the creator method as an async function so that some data can be fetched from the weather API. We can pluck the latitude and longitude off the graphic geometry. Once we get the initial results from the weather API for this location, that result will provide various URLs for more detailed weather information such as the forecast URL. We can send another request to the forecast URL and get a more detailed five day forecast for day and night weather information. It will even provide an icon that coincides with the weather conditions. We can use this information to construct a list of HTML elements to display in the Popup. You should get a Popup that looks similar to this!

Summary

At the end of the day, you can pretty much use whatever you want inside CustomContent for a Popup. Maybe you have some custom chart requirements, or want to run an analysis on nearby features. That's the beauty of using CustomContent, you can do whatever you need to do. I'm very curious to see what some developers might build with this, maybe even entire micro apps inside the Popup to process data!

You can see more details in the video below!

Intro to reactiveUtils in ArcGIS JSAPI

Rene Rubalcava — Wed, 25 May 2022 21:23:12 +0000

Reactive at heart

If you weren't already aware, the ArcGIS API for JavaScript is reactive at heart. Since it's release, you have had the capability to watch for property changes. This provides a lot more flexibility for developers to watch for changes they care about. Rather than rely on a variety of events, you can just watch for particular properties to change.

Since the release of version 4 of the API, there has been a watchUtils you could use to help you watch for changes. The drawback is that depending on what you were interested in, you could use a utility to check when a property has been defined, changed, or is a true/false boolean value. These watchUtils are being deprecated in favor of reactiveUtils, so there is no time to update like today!

Flexibility

A core benefit to using reactiveUtils is the flexibility you have to manage property changes. Combine this with optional chaining, and you don't even need to check if properties exist up front.

Let's take a quick look at reactiveUtils and what they are used for.

on() - Listen for events on a target
once() - Like watch, but only fires one time as a Promise
watch() - Most versatile of the methods, used for watching property changes
when() - Similar to watch, but executes the callback when the expression returns truthy
whenOnce() - Executes the when expression only once as a Promise

This is an older example of how you might do some deep property watching compared to how you can use reactiveUtils.

// old watchUtils
watch(view, 'map.basemap.title', (title) => console.log(title));

// reactiveUtils
watch(
    () => view.map?.basemap?.title,
    (title) => console.log(title)
);

This sample isn't too exciting, but it gives you an idea of what you can accomplish.

An incredibly useful property to track is view.updating. This property will be true when there is data being fetched, and rendered by the map, it becomes false when that rendering is done. It's useful to know when the View, in 2d or 3d, has completed drawing.

when(
    () => !view.updating,
    (updating) => /** take screenshot, notify user, etc **/
);

You can also watch for multiple properties to change. Maybe you are interested in checking when the zoom or scale of the map changes, but not when you pan the map. This requires that track the previous zoom value to compare.

let prevZoom;

// wait for view to be ready
whenOnce(() => view.ready).then(() => {
  // save the initial value
  prevZoom = view.zoom;
  watch(
    () => [view.zoom, view.stationary],
    ([zoom, stationary]) => {
      // do not execute if values are the same
      if (zoom === prevZoom) return;
      // make sure view is stationary
      if (stationary) {
        // update tracked value
        prevZoom = zoom;
        // do something when the value is updated as expected
        console.log(zoom);
      }
    }
  );
});

In this sample, as a bonus, we can look at an alternative to view.when() to check then the view.ready property is true using whenOnce.

You can get as detailed or specific in how you watch for property changes as needed. There's a great sample in the documentation you can look at with some good use cases.

Events

An alternative to target.on() is using the on() to listen for events.

on(
    () => view.popup,
    "trigger-action",
    (event) => handleTriggerAction(event)
);

You can even listen for multiple events.

on(
    () => view,
    ["click", "double-click"],
    (event) => handleViewEvents(event)
);

This could be useful if you want to handle multiple events the same way on a component or element.

Summary

This was just a quick intro to reactiveUtils in the ArcGIS API for JavaScript. There are many different use cases you can leverage in your applications with this utility. There are less methods in reactiveUtils than you would find in watchUtils, but now you have more flexibility in how you compose what is being watched, when you handle those updates and other side effects in your application. If you can learn how to leverage reactiveUtils in the ArcGIS API for JavaScript, you can take your development experience to the next level!

You can see more details in the video below!

Building ArcGIS API for JavaScript Apps with NextJS

Rene Rubalcava — Mon, 02 May 2022 17:49:17 +0000

React is a popular library for building web applications. However, it's only a library, not a complete framework. This is where something like NextJS becomes useful. NextJS is a complete React framework for building applications. It comes with a variety of features including routing, static site generation, and even built in API endpoints, so you can write server-side code in your application if you need it. It pairs great with the ArcGIS API for JavaScript.

You can get started with NextJS with the following command.

npx create-next-app@latest

For this application, we’re going to be looking at a service of global power plants. For the user experience, we want to display a list of power plants by type, and when the user clicks on a type of plant from a list, it will display a map of the power plants for that selected type.

You can find the source code for the application in this blog post on github.

API Route

To accomplish the first task of getting a list of the types of power plants, we can write an API route in a NodeJS environment. We can use the ArcGIS API for JavaScript in the route API to query the service and extract the values from the results.

import type { NextApiRequest, NextApiResponse } from "next";
import { executeQueryJSON } from "@arcgis/core/rest/query";

const PLANT_URL =
  "https://services1.arcgis.com/4yjifSiIG17X0gW4/arcgis/rest/services/PowerPlants_WorldResourcesInstitute/FeatureServer/0";

type Data = {
  types: string[];
};

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  const query = {
    outFields: ["fuel1"],
    where: "1=1",
    returnDistinctValues: true,
    returnGeometry: false
  };
  const results = await executeQueryJSON(PLANT_URL, query);
  const values = results.features
    .map((feature) => feature.attributes["fuel1"])
    .filter(Boolean)
    .sort();
  res.status(200).json({ types: values });
}

In this API route, we are going to query the feature service, limit the results only to the field for the primary type of power generated at the plant and extract that to a simple list. The best part of this is that this query is executed on the server, so there is no latency on the client to run this query.

Redux and Stores

To manage the application state, we can use Redux. If you’ve used Redux in the past, you might be thinking you need to set up a lot of boiler plate code for constants, actions, and reducers. The Redux toolkit helps to simplify this using slices with the createSlice() method. This will let you define the name of the slice, the initial state, and the reducers, or methods used to update the state. We can create one that will be used for our application.

import { createSlice } from '@reduxjs/toolkit'

export interface AppState {
    types: string[];
    selected?: string;
}

const initialState: AppState = {
    types: []
}

export const plantsSlice = createSlice({
    name: 'plants',
    initialState,
    reducers: {
        updateTypes: (state, action) => {
            state.types = action.payload
        },
        updateSelected: (state, action) => {
            state.selected = action.payload
        }
    },
})

export const { updateTypes, updateSelected} = plantsSlice.actions

export default plantsSlice.reducer

With our slice and reducers defined, we can create a React store and hook to be used in our application for the reducer.

import { configureStore } from '@reduxjs/toolkit'
import plantsReducer from '../features/plants/plantsSlice'

const store = configureStore({
  reducer: {
      plants: plantsReducer
  },
})

export default store
export type RootState = ReturnType<typeof store.getState>
export type AppDispatch = typeof store.dispatch

In this case, the only reason we really need the custom hooks is to have proper TypeScript typings.

Layout

At this point, we can start thinking about how the application and pages will be displayed. We can start with a layout file.

import Head from 'next/head'
import Link from 'next/link'
import { useRouter } from 'next/router'
import { useAppSelector } from '../app/hooks'
import { useEffect, useState } from 'react'
import styles from './layout.module.css'

export default function Layout({ children }: any) {
    const router = useRouter()
    const selected = useAppSelector((state) => state.plants.selected)
    const [showPrevious, setShowPrevious] = useState(false)
    useEffect(() => {
        setShowPrevious(router.asPath.includes('/webmap'))
    }, [router])
    return (
        <>
            <Head>
                <title>Power Plants Explorer</title>
            </Head>
            <div className={styles.layout}>
                <header className={styles.header}>
                    {
                        showPrevious ?
                        <Link href="/">
                            <a>
                                <svg className={styles.link} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path d="M14 5.25L3.25 16 14 26.75V20h14v-8H14zM27 13v6H13v5.336L4.664 16 13 7.664V13z"/><path fill="none" d="M0 0h32v32H0z"/></svg>
                            </a>
                        </Link>
                        : null
                    }
                    <div className={styles.container}>
                        <h3>Global Power Plants</h3>
                        {showPrevious  && selected ? <small className={styles.small}>({selected})</small> : null}
                    </div>
                </header>
                <main className={styles.main}>{children}</main>
            </div>
        </>
    )
}

The layout is going to define how the all pages are going to look. We are going to have a header on the page with a navigation button and a title. This will be visible on all the pages of our application. Then we can define a section of the layout that will be used for the varying content.

Router

This is also where we start looking at the provided router with NextJS. When we are on the page that displays the map, we want to add a back button to return to the list of power plants. The layout page creates a header, and a main element for the content.

We can use the layout in the global App for NextJS.

import '../styles/globals.css'
import type { ReactElement, ReactNode } from 'react'
import type { NextPage } from 'next'
import type { AppProps } from 'next/app'
import { Provider } from 'react-redux'
import store from '../app/store'

type NextPageWithLayout = NextPage & {
  getLayout?: (page: ReactElement) => ReactNode
}

type AppPropsWithLayout = AppProps & {
  Component: NextPageWithLayout
}

export default function MyApp({ Component, pageProps }: AppPropsWithLayout) {
  const getLayout = Component.getLayout ?? ((page) => page)
  return (
    <Provider store={store}>
      {getLayout(<Component {...pageProps} />)}
    </Provider>
  )
}

It’s in this global app file that we can add the layout and provider for our Redux store. The global app will determine if there is a layout or not and apply it.

API

To fetch data from our routing API, we can use swr, which will provide a React hook that handles fetching data for us. It’s not required, but it’s a useful tool to help wrap a number data fetching capabilities, like caching and more.

import styles from '../../styles/Home.module.css'
import useSWR from 'swr'
import { useState, useEffect } from 'react'
import { useAppSelector, useAppDispatch } from '../../app/hooks'
import { updateTypes } from './plantsSlice'
import Loader from '../../components/loader'
import { useRouter } from 'next/router'

const fetcher = async (
    input: RequestInfo,
    init: RequestInit,
    ...args: any[]
  ) => {
        const res = await fetch(input, init)
        return res.json()
    }

const Plants = () => {
    const { data, error } = useSWR('/api/powerplants', fetcher)
    const types = useAppSelector((state) => state.plants.types)
    const dispatch = useAppDispatch()
    const [isLoading, setLoading] = useState(true)
    const router = useRouter()

    useEffect(() => {
        setLoading(true)
        if (data) {
            dispatch(updateTypes(data.types))
            setLoading(false)
        }
    }, [data, error, dispatch])

    if (isLoading)
        return (
            <div className={styles.loader}>
                <Loader />
            </div>
        )
    if (!types.length) return <p>No data</p>

    return (
        <ul className={styles.list}>
            {types.map((value, idx) => (
            <li
                className={styles.listItem}
                key={`${value}-${idx}`}
                onClick={() => router.push(`/webmap?type=${value}`)}
            >
                {value}
            </li>
            ))}
        </ul>
    )
}

export default Plants

Pages

The plants component will fetch the list of power plants and display them. It will display a simple animated SVG loader while it loads the request. When a type of power plant is selected from the list, it will route to a page that displays the map and will filter the results to the selected type of power plant. Since the entry page for this application will display the list of power plants, we can use this Plants component in our index.tsx file.

import styles from '../styles/Home.module.css'
import Layout from '../components/layout'
import { ReactElement } from 'react'
import Plants from '../features/plants/plants'

const Home = () => {
  return (
    <div className={styles.container}>
      <Plants />
    </div>
  )
}

Home.getLayout = function getLayout(page: ReactElement) {
  return <Layout>{page}</Layout>
}

export default Home

Our index.tsx file exposes a Home component that will be the home route for our application.

The next step is defining our webmap route for the application. This page will display our webmap and filter the results to only display the type of Power Plants that were selected from the list in the home page. To make this more configurable, we can also add a ?type= parameter to the URL string so we can share this link with other users later on.

import styles from '../styles/WebMap.module.css'
import Layout from '../components/layout'
import { ReactElement, useEffect, useRef } from 'react'
import { useRouter } from 'next/router'
import { useAppSelector, useAppDispatch } from '../app/hooks'
import { updateSelected } from '../features/plants/plantsSlice'

async function loadMap(container: HTMLDivElement, filter: string) {
    const { initialize } = await import('../data/mapping')
    return initialize(container, filter)
}

const WebMap = () => {
    const mapRef = useRef<HTMLDivElement>(null)
    const router = useRouter()
    const { type } = router.query
    const selected = useAppSelector((state) => state.plants.selected)
    const dispatch = useAppDispatch()

    useEffect(() => {
        dispatch(updateSelected(type))
    }, [type, dispatch])

    useEffect(() => {
        let asyncCleanup: Promise<(() => void)>
        if (mapRef.current && selected) {
            asyncCleanup = loadMap(mapRef.current, selected)
        }
        return () => {
            asyncCleanup && asyncCleanup.then((cleanup) => cleanup())
        }
    }, [mapRef, selected])

    return (
        <div className={styles.container}>
            <div className={styles.viewDiv} ref={mapRef}></div>
        </div>
    )
}

WebMap.getLayout = function getLayout(page: ReactElement) {
  return <Layout>{page}</Layout>
}

export default WebMap

There are few things happening here. We’re using the provided router hooks from NextJS to get the query parameters. We also manage a little bit of state to display a button to navigate back to the home page. Notice there is no reference to the ArcGIS API for JavaScript in this component. We have a loadMap() method that dynamically imports a mapping module. This mapping module is how we communicate with modules from the ArcGIS API for JavaScript.

import config from '@arcgis/core/config'
import ArcGISMap from '@arcgis/core/Map'
import FeatureLayer from '@arcgis/core/layers/FeatureLayer'
import MapView from '@arcgis/core/views/MapView'
import Extent from '@arcgis/core/geometry/Extent'
import { watch } from '@arcgis/core/core/reactiveUtils'
import Expand from '@arcgis/core/widgets/Expand'
import Legend from '@arcgis/core/widgets/Legend';
import LayerList from '@arcgis/core/widgets/LayerList';

config.apiKey = process.env.NEXT_PUBLIC_API_KEY as string

interface MapApp {
    view?: MapView;
    map?: ArcGISMap;
    layer?: FeatureLayer;
    savedExtent?: any;
}

const app: MapApp = {}

let handler: IHandle

export async function initialize(container: HTMLDivElement, filter: string) {
    if (app.view) {
        app.view.destroy()
    }

    const layer = new FeatureLayer({
        portalItem: {
            id: '848d61af726f40d890219042253bedd7'
        },
        definitionExpression: `fuel1 = '${filter}'`,
    })

    const map = new ArcGISMap({
        basemap: 'arcgis-dark-gray',
        layers: [layer]
    })

    const view = new MapView({
        map,
        container
    })

    const legend = new Legend({ view });
    const list = new LayerList({ view });

    view.ui.add(legend, 'bottom-right');
    view.ui.add(list, 'top-right');

    if(app.savedExtent) {
        view.extent = Extent.fromJSON(app.savedExtent)
    } else {
        layer.when(() => {
            view.extent = layer.fullExtent
        })
    }

    handler = watch(
        () => view.stationary && view.extent,
        () => {
            app.savedExtent = view.extent.toJSON()
        }
    )

    view.when(async () => {
        await layer.when()
        const element = document.createElement('div')
        element.classList.add('esri-component', 'esri-widget', 'esri-widget--panel', 'item-description')
        element.innerHTML = layer.portalItem.description
        const expand = new Expand({
            content: element,
            expandIconClass: 'esri-icon-description'
        })
        view.ui.add(expand, 'bottom-right')
    })

    app.map = map
    app.layer = layer
    app.view = view

    return cleanup
}

function cleanup() {
    handler?.remove()
    app.view?.destroy()
}

This mapping module creates a thin API layer in our application to communicate with the ArcGIS API for JavaScript and our application components. The initialize method creates the map and layer. It also saves the extent as a JSON object as the user navigates the map. So when the user navigates to the home page and comes back to the map, their last viewed location will be saved and reused again. This is a useful way to provide a more seamless user experience.

This is what the finished application looks like.

Deployment

NextJS leverages what is called serverless functions. Serverless functions are short lived methods that last only seconds, spun up for use and quickly destroyed. NextJS uses them for the API route when serving pages. You will need to keep this in mind when you deploy your application. It should be noted, NextJS is developed by Vercel, and they do offer a hosting solution that works with serverless functions. Other platforms like Heroku and Amazon do as well. It’s up to you to decide where you want to deploy your application to use these serverless functions. For demo purposes, I deployed the application to Heroku here.

Summary

NextJS is a powerful React framework you can use to build scalable production ready applications using the ArcGIS API for JavaScript. You can use tooling like Redux to help you manage your application state, and even use the ArcGIS API for JavaScript to query mapping services in serverless functions. This application also provides the benefits of fast load times by deferring loading the map until necessary.

The combination of NextJS and the ArcGIS API for JavaScript provide a great developer experience, and one that I highly recommend you try for yourself. Have fun, and build some awesome applications!

You can view a walkthough in the video below!

React Portals for ArcGIS JSAPI Popups

Rene Rubalcava — Thu, 28 Apr 2022 16:53:51 +0000

You people do weird stuff

I get asked some pretty odd questions. It's ok, I have some pretty odd answers. One of the questions that comes up is how people can do weird stuff with their Popups in the ArcGIS API for JavaScript.

Can I have multiple popups? No.
Can I drag the Popup around? No.
Can I resize the Popup? No.

All these have some more nuanced answers, that require a bit of elbow grease, but by default... no.

One question that comes up sometimes is can I use React components in my Popup? Sure you can!

As a matter of fact, React has an API for just this kind of use case. React Portals. The purpose of React Portals is to manage DOM elements that exist outside the parent DOM. The most common use case is a modal dialog. Or maybe a toast alert, or tooltips and popovers on your page. You can leverage this in your Popups too!

Open the Portals in your mind

Note: You can find the source code this project on github.

First thing I want to do is create a React component that can take some data and be displayed in my Popup.

/// src/PopupInfo.js 
import React from 'react-dom';

const PopupInfo = ({ data }) => (
    <div className='popup-container'>
    <div className='my-popup'>
      <h1>{data.title}</h1>
      <p>
          {data.description}
      </p>
    </div>
  </div>
);

export default PopupInfo;

This is a fairly straightforward component. But you can make your component as complicated as you desire, charts, graphs, animations, maybe another Map?!?! Knock yourself out, it's your component.

Then I need to create a wrapper portal component for my Popup content.

// src/PopupPortal.js 
import { useEffect } from "react";
import { createPortal } from "react-dom";

const PopupPortal = ({ mountNode, children }) => {
  const el = document.createElement("div");

  useEffect(() => {
    mountNode.appendChild(el);
    return () => mountNode.removeChild(el);
  }, [el, mountNode]);

  return createPortal(children, el);
};

export default PopupPortal;

This component is going to take mountNode DOM element, and child components, and then render them in the React Portal. It's not very complicated, but does the job. I think I could simplify this even more.

// src/PopupPortal.js Option 2
import { createPortal } from "react-dom";

const PopupPortal = ({ mountNode, children }) => {
  return createPortal(children, mountNode);
};

export default PopupPortal;

My only concern here is that the mountNode might get destroyed when I don't want it to. I might be overly cautious, but that's how I roll.

Put the lime in the coconut

Here is a quick preview of how I can use the PopupPortal.

// src/App.js
import React, { useRef, useEffect, useState } from "react";

import PopupInfo from "./PopupInfo";
import PopupPortal from "./PopupPortal";

const popupRoot = document.createElement('div');

function App() {
  const mapDiv = useRef(null);
  const [ popupData, setPopupData ] = useState({});

  useEffect(() => {
    if (mapDiv.current) {
      ...
      sceneView.when(() => {
        ...
        function setContentInfo(center) {
          setPopupData({
            title: "My Popup with React Portal",
            description: `This is my React Portal: center = ${JSON.stringify(center.toJSON())}`,
          });
          return popupRoot;
        }
      });
    }
  }, [mapDiv]);

  return (
    <div className="mapDiv" ref={mapDiv}>
        <PopupPortal mount={popupRoot}>
            <PopupInfo data={popupData}></PopupInfo>
        </PopupPortal>
    </div>
  );
}

export default App;

Ok, let's break this down a bit. The PopupTemplate content can be a variety of things, including a method that returns an HTML element that is used for the Popup content. We can use a method like setContentInfo to update our component state and return an HTML element we've created.

function setContentInfo(center) {
    setPopupData({
        title: "My Popup with React Portal",
        description: `This is my React Portal: center = ${JSON.stringify(center.toJSON())}`,
    });
    return popupRoot;
}

We can pass this element exist in the context of our component, so we can pass it to our Portal component.

<div className="mapDiv" ref={mapDiv}>
    <PopupPortal mount={popupRoot}>
        <PopupInfo data={popupData}></PopupInfo>
    </PopupPortal>
</div>

Now, when we open the Popup in our map, it will be populated with our Popup React component!

Summary

The ArcGIS API for JavaScript provides a lot of functionality for Popups. Tables, charts, media, attachments, Arcade, various expressions, custom actions, and the list goes on. Considering it is probably the most widely used widget across various applications, the fact that you can have total control of the content based on some of not only where you click on the map, but what you click on the map, is pretty damn cool. Have some fun with it, you might find that React Portals solve a particular use case for you that you've been working around. For example, the non-Portal way to do this would involve using React.unmountComponentAtNode(container), which works great, but poses its own issues of managing multiple React DOMs. You can see more information in the video below!