Apply core concepts

Learn to craft an engaging, interactive experience with Calcite Components and ArcGIS Maps SDK for JavaScript.

Using core web component concepts such as slots, events, and attributes, you will build an interface using Calcite Components and data provided by ArcGIS Maps SDK for JavaScript.

This tutorial will provide an overview of foundational Calcite Component and web component concepts. You will:

Scaffold an interface with calcite-shell and related components.
Add a map with a FeatureLayer containing content.
Use Calcite Components to display data provided by the queryTopFeatures() method.
Add interactivity to the map and data using the concepts of events and attributes.
Customize the look and feel using mode and color tokens.

This tutorial leverages vanilla JavaScript, but these concepts and methods of interaction are applicable across frameworks.

Prerequisites

ArcGIS account

You need a free ArcGIS Online and/or ArcGIS Location Platform account to access the services used in this tutorial.

Steps

Create a new pen

Go to CodePen to create a new pen for your mapping application.

Add HTML

In CodePen > HTML, add HTML and CSS to create a page with a viewDiv element which will display the map. The CSS ensures that the map is the full width and height of the browser window.

The <!DOCTYPE html> tag is not required in CodePen. If you are using a different editor or running the page on a local server, be sure to add this tag to the top of your HTML page.

Use dark colors for code blocks

<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
  <title>Calcite Components: Core concepts</title>

  <style>
    html,
    body,
    #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
    }
  </style>

</head>

<body>

  <div id="viewDiv"></div>

</body>

<script>
</script>

</html>

In the <head> element, add references to Calcite Components and ArcGIS Maps SDK for JavaScript.

Expand
Use dark colors for code blocks
  <script type="module" src="https://js.arcgis.com/calcite-components/2.13.2/calcite.esm.js"></script>
  <link rel="stylesheet" type="text/css" href="https://js.arcgis.com/calcite-components/2.13.2/calcite.css" />

  <script src="https://js.arcgis.com/4.31/"></script>
  <link rel="stylesheet" href="https://js.arcgis.com/4.31/esri/themes/light/main.css" />
Expand

Import modules

In the <script> element, import the ArcGIS Maps SDK for JavaScript modules that you will use in this application.

Expand
Use dark colors for code blocks
<script>

  require([
    "esri/Map",
    "esri/views/MapView",
    "esri/layers/FeatureLayer",
    "esri/symbols/WebStyleSymbol",
    "esri/Basemap",
    "esri/rest/support/TopFeaturesQuery",
    "esri/rest/support/TopFilter",
    "esri/widgets/Home"
  ], (Map, MapView, FeatureLayer, WebStyleSymbol, Basemap, TopFeaturesQuery, TopFilter, Home) => (async () => { })());

</script>

</html>

Use an API key

An API key is required to access ArcGIS services if you are using a developer account. You can skip this step if you have an account associated with an ArcGIS Online organization.

Go to the get started with security and authentication to build an app that can access secure resources.
Back in CodePen > <script>, import the esriConfig class.
Set the apiKey property.

Use dark colors for code blocks
  "esri/widgets/Home",
  "esri/config"
], function (Map, MapView, FeatureLayer, WebStyleSymbol, Basemap, TopFeaturesQuery, TopFilter, Home, esriConfig) => (async () => {
esriConfig.apiKey = "YOUR_API_KEY";

Scaffold the application

Next, you will add Calcite Components to scaffold the application.

The calcite-shell component serves as the application frame. Additionally, notice that the calcite-shell-panel, and calcite-panel components have been added.

These layout components help organize content and other components in predictable and repeatable ways, and can be configured to accommodate many desired layouts and use cases.

Expand
Use dark colors for code blocks
<body>
  <calcite-shell>
    <calcite-shell-panel slot="panel-start">
      <calcite-panel heading="National Park Visitation"> </calcite-panel>
    </calcite-shell-panel>

    <div id="viewDiv"></div>

  </calcite-shell>
</body>

Expand

Pause to understand some core web component concepts in the snippet you added to the application:
- The panel-start slot you added to the calcite-shell-panel. Defined slots such as this can provide styling or positioning for slotted content or components, making common patterns simple to construct.
- The heading attribute has been added to the calcite-panel component and populated with the name of the application. Using component attributes to add text helps consistently position and style content.

Display a map

Next, you will add the ArcGIS Maps SDK for JavaScript code, based on the Query top features from a FeatureLayer tutorial.

Expand
Use dark colors for code blocks
  ], (Map, MapView, FeatureLayer, WebStyleSymbol, Basemap, TopFeaturesQuery, TopFilter, Home) =>
    (async () => {

      const layer = new FeatureLayer({
        url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/US_National_Parks_Annual_Visitation/FeatureServer/0",
        outFields: ["*"],
        renderer: await setRenderer(),
        popupTemplate: createPopupTemplate()
      });

      const map = new Map({
        basemap: "streets-navigation-vector",
        layers: [layer]
      });

      const view = new MapView({
        container: "viewDiv",
        map: map,
        center: [-120, 45],
        zoom: 3
      });

      let homeWidget = new Home({
        view: view
      });

      view.ui.add(homeWidget, "top-right");
      view.ui.move("zoom", "top-right");
      const layerView = await view.whenLayerView(layer);

      async function setRenderer() {
        const symbol = new WebStyleSymbol({
          name: "park",
          styleName: "Esri2DPointSymbolsStyle"
        });

        const cimSymbol = await symbol.fetchCIMSymbol();
        cimSymbol.data.symbol.symbolLayers[0].size = 24;
        cimSymbol.data.symbol.symbolLayers[1].size = 0;

        return {
          type: "simple",
          symbol: cimSymbol
        };
      }

      function createPopupTemplate() {
        return {
          title: "{Park}",
          content: [
            {
              type: "fields",
              fieldInfos: [
                {
                  fieldName: "F2022",
                  label: "2022",
                  format: { digitSeparator: true }
                },
                {
                  fieldName: "F2021",
                  label: "2021",
                  format: { digitSeparator: true }
                },
                {
                  fieldName: "F2020",
                  label: "2020",
                  format: { digitSeparator: true }
                },
                {
                  fieldName: "F2019",
                  label: "2019",
                  format: { digitSeparator: true }
                }
Expand

At this point the map is visible behind the calcite-shell-panel you added. Click around the map points and see the data displayed in popups. This configuration is not specific to Calcite Components - you can view the original tutorial for more context.

Add a function to filter the data on the map. The filterItems() function contains a queryTopFeatures() method, which returns a set of results based on a set of filter options. Notice that we have assigned some default values to variables that will later be made configurable in the application.

Expand
Use dark colors for code blocks
                  format: { digitSeparator: true }
                }
              ]
            }
          ]
        };
      }


      const countDefault = 1;
      const orderByDefault = "DESC";
      const yearDefault = "F2022";

      let count = countDefault;
      let orderBy = orderByDefault;
      let year = yearDefault;

      async function filterItems() {
        const query = new TopFeaturesQuery({
          topFilter: new TopFilter({
            topCount: count,
            groupByFields: ["State"],
            orderByFields: `${year} ${orderBy}`
          }),
          orderByFields: `${year} ${orderBy}`,
          outFields: ["State, F2022, F2021, F2020, F2019, Park"],
          returnGeometry: true,
          cacheHint: false
        });

        query.orderByFields = [""];
Expand

Add the results list

Next, you will create a list using the results returned from ArcGIS Maps SDK for JavaScript. Clicking on the result items will show an associated popup on the map.

Add a calcite-block with an id attribute. Inside, place a calcite-list, again with an id attribute, that will be used for appending content. Note the collapsible and heading attributes used to customize the component.

Expand
Use dark colors for code blocks
    <calcite-shell-panel slot="panel-start">
      <calcite-panel heading="National Park Visitation">

        <calcite-block collapsible heading="Results" id="result-block">
          <calcite-list id="result-list"></calcite-list>
        </calcite-block>

      </calcite-panel>
    </calcite-shell-panel>
Expand

Next, add logic to create a calcite-list-item for each displayed item in the FeatureLayer.

Expand
Use dark colors for code blocks
            topCount: count,
            groupByFields: ["State"],
            orderByFields: `${year} ${orderBy}`
          }),
          orderByFields: `${year} ${orderBy}`,
          outFields: ["State, F2022, F2021, F2020, F2019, Park"],
          returnGeometry: true,
          cacheHint: false
        });

        document.getElementById("result-list").innerHTML = "";
        document.getElementById("result-block").open = true;

        const results = await layer.queryTopFeatures(query);
        graphics = results.features;

        graphics.forEach((result, index) => {
          const attributes = result.attributes;
          const item = document.createElement("calcite-list-item");
          const chip = document.createElement("calcite-chip");
          chip.value = attributes.State;
          chip.slot = "content-end";
          chip.scale = "s";
          chip.innerText = attributes.State;
          item.label = attributes.Park;
          item.value = index;
          item.description = `${attributes[year].toLocaleString()} visitors`;
Expand

For each graphic, you are programmatically creating a calcite-list-item, assigning property values to customize the display, and appending to the result container reference you added earlier. You are also creating a calcite-chip with the state name of each result, and placing it in a slot.

An event listener was added to each calcite-list-item created in the previous step. Create the resultClickHandler() function, which will display a ArcGIS Maps SDK for JavaScript popup.

Expand
Use dark colors for code blocks
          item.addEventListener("click", () => resultClickHandler(result, index));
          item.appendChild(chip);
          document.getElementById("result-list").appendChild(item);
        });

        query.orderByFields = [""];
        const objectIds = await layer.queryTopObjectIds(query);
        layerView.filter = { objectIds };
      }

      function resultClickHandler(result, index) {
        const popup = graphics && graphics[parseInt(index, 10)];
        if (popup) {
          view.popup.open({
Expand

Build the filters

Add another calcite-block component. Inside, place a set of controls that will adjust the parameters of the queryTopFeatures() query. Each control is wrapped in a calcite-label.

Expand
Use dark colors for code blocks
    <calcite-shell-panel slot="panel-start">
      <calcite-panel heading="National Park Visitation">

        <calcite-block heading="Filters" open>
          <calcite-label>
            Data type, per state
            <calcite-segmented-control id="control-visited-type-el" width="full">
              <calcite-segmented-control-item value="DESC" checked>Most visited</calcite-segmented-control-item>
              <calcite-segmented-control-item value="ASC">Least visited</calcite-segmented-control-item>
            </calcite-segmented-control>
          </calcite-label>
          <calcite-label>
            Year data to display
            <calcite-select id="control-year-el">
              <calcite-option label="2022" value="F2022"></calcite-option>
              <calcite-option label="2021" value="F2021"></calcite-option>
              <calcite-option label="2020" value="F2020"></calcite-option>
              <calcite-option label="2019" value="F2019"></calcite-option>
            </calcite-select>
          </calcite-label>
          <calcite-label>
            Max parks per state
            <calcite-slider id="control-count-per-state-el" label-ticks ticks="1" min="1" max="5"></calcite-slider>
          </calcite-label>
        </calcite-block>


Expand

Note that you have assigned id attributes to the calcite-segmented-control, calcite-select, and calcite-slider. You will use these references to set up event listeners to determine when to update the results.

Expand
Use dark colors for code blocks
                {
                  fieldName: "F2019",
                  label: "2019",
                  format: { digitSeparator: true }
                }
              ]
            }
          ]
        };
      }


      const controlVisitedTypeEl = document.getElementById("control-visited-type-el");
      const controlYearEl = document.getElementById("control-year-el");
      const controlCountPerStateEl = document.getElementById("control-count-per-state-el");
Expand

Note that each event listener references a custom Calcite Components event: calciteSelectChange, calciteSliderChange , and calciteSegmentedControlChange.

When that event is fired, you will set the related local variable, and run the filterItems() function. In a production environment, you might make use of more granular filtering functions to improve performance.

Create a reset action

Because you added events that allowed a user to change the view from the default filter parameters, it will be useful to add a way to reset the options.

Add a calcite-action and calcite-tooltip using slots.

Expand
Use dark colors for code blocks
        <calcite-block heading="Filters" open>

          <div slot="control">
            <calcite-action disabled icon="reset" id="control-reset-el"></calcite-action>
            <calcite-tooltip reference-element="control-reset-el" placement="bottom">
              Reset to defaults
            </calcite-tooltip>
          </div>

          <calcite-label>
Expand

You may notice some concepts used in previous tutorial steps. Take note of the icon attribute on the calcite-action. Calcite Components often provide helpers for loading Calcite UI Icons - the full set can be explored using the icon search.

The disabled attribute is also set - you will enable it when the set of parameters a user has created differs from the defaults.

Add a reference and an event listener to the reset action.

Expand
Use dark colors for code blocks
                }
              ]
            }
          ]
        };
      }


      const controlVisitedTypeEl = document.getElementById("control-visited-type-el");
      const controlYearEl = document.getElementById("control-year-el");
Expand

Add the functions determineResetActionState(), and resetFilters(), where you will determine the state of the reset action, and reset parameters when requested by a user. The resetFilters() function will reset the parameters of the query, and reset the controls to their initial display. The action will be disabled when the set of filter options matches the initial values, or a user interacts with the calcite-action.

Expand
Use dark colors for code blocks

        determineResetActionState();
      }

      function resultClickHandler(result, index) {
        const popup = graphics && graphics[parseInt(index, 10)];
        if (popup) {
          view.popup.open({
            features: [popup],
            location: result.geometry
          });
          view.goTo({ center: [result.geometry.longitude, result.geometry.latitude], zoom: 4 }, { duration: 400 });
        }
      }


      function determineResetActionState() {
        if (count !== countDefault || orderBy !== orderByDefault || year !== yearDefault) {
          controlResetEl.removeAttribute("disabled");
          controlResetEl.indicator = true;
        } else {
          controlResetEl.disabled = true;
          controlResetEl.removeAttribute("indicator");
        }
      }

      function resetFilters() {
        count = countDefault;
Expand

Call the determineResetActionState() function in the filterItems() function.

Expand
Use dark colors for code blocks
          chip.scale = "s";
          chip.innerText = attributes.State;
          item.label = attributes.Park;
Expand

Theme the application

By combining the functionality of the ArcGIS Maps SDK for JavaScript with Calcite Components, you created a rich interactive experience for your users. To go one step further, you will add styles to create a custom look and feel.

Add a CSS class to the calcite-shell:

Use dark colors for code blocks
  <calcite-shell class="calcite-tutorial">

Target individual components or sections to add custom styles:
- Add custom brand colors to create a unique experience using color and theming tokens.
- Use the custom colors you added to make the slotted calcite-chip components stand out.
- Add spacing to the slotted calcite-chip components.

Expand
Use dark colors for code blocks


    .calcite-tutorial {
      --calcite-color-brand: #039851;
      --calcite-color-brand-hover: #008d52;
    }

    .calcite-tutorial calcite-chip {
      --calcite-color-foreground-2: var(--calcite-color-brand);
      --calcite-color-text-1: white;
      margin-inline-end: 0.75rem;
    }

Expand

Run the app

In CodePen, run your code to display the map.