Learn how to create a UI for a simple mapping application using Calcite Components and ArcGIS Maps SDK for JavaScript Map components.
You will use Calcite Components to craft a positive user experience and drive interaction in your mapping application. This tutorial focuses on the user interface and expects some knowledge of the ArcGIS Maps SDK for JavaScript. If you are new to the ArcGIS Maps SDK for JavaScript, they have a great tutorial that covers the mapping concepts used in this application.
Prerequisites
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 an
arcgis-map
, which will display the map. The CSS ensures that the map is the full width and height of the browser window.
The <!
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.
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
<title>Calcite Components: Create a mapping app</title>
</head>
<style>
html,
body,
#mapEl {
padding: 0;
margin: 0;
height: 100%;
width: 100%;
display: flex;
}
</style>
<body>
<arcgis-map id="mapEl">
<arcgis-zoom position="top-right"></arcgis-zoom>
</arcgis-map>
</body>
<script>
</script>
</html>
- In the
<head
element, add references to Calcite Components, ArcGIS Maps SDK for JavaScript, and Map components.>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
<title>Calcite Components: Create a mapping app</title>
<script src="https://js.arcgis.com/calcite-components/3.0.3/calcite.esm.js" type="module"></script>
<script src="https://js.arcgis.com/4.32/"></script>
<link rel="stylesheet" href="https://js.arcgis.com/4.32/esri/themes/light/main.css" />
<script type="module" src="https://js.arcgis.com/map-components/4.32/arcgis-map-components.esm.js"></script>
</head>
<style>
Get an access token
You need an access token with the correct privileges to access the location services used in this tutorial.
- Go to the Create an API key tutorial and create an API key with the following privilege(s):
- Privileges
- Location services > Basemaps
- In CodePen, set
esri
to your access token.Config.api Key
<!-- The esriConfig variable must be defined before adding other Esri libraries -->
<script>
var esriConfig = {
apiKey: "YOUR_ACCESS_TOKEN"
};
</script>
To learn about other ways to get an access token, go to Types of authentification.
Display a map
The map is the central focus of this application. You added CSS above which makes the map the full width and height of the window. You will also add ArcGIS Maps SDK for JavaScript components that interact with the map. The components will be organized by Calcite Components to keep the user interface clean.
- In the
<body
, you will initialize the> arcgis-map
component using theitem-id
attribute, which specifies the webmap's item ID.
<arcgis-map id="mapEl" item-id="210c5b77056846808c7a5ce93920be81">
<arcgis-zoom position="top-right"></arcgis-zoom>
</arcgis-map>
Create the layout
To create the layout you will use calcite-shell
, which organizes other components on the page using slots. Slots are a web component concept and there is a brief section in Core concepts. A list of a component's slots, if it has any, can be found on its reference page. For example, here are shell's slots.
-
Add the
calcite-shell
component.- Set the
content-behind
attribute so users can interact with the map behind the shell.
- Set the
-
Add the
calcite-shell-panel
component, placing it in shell'spanel-start
slot.- Set the
display
attribute toMode "float-content"
so the shell panel's content appears to hover over the map.
- Set the
<calcite-shell content-behind>
<calcite-shell-panel slot="panel-start" display-mode="float-content">
</calcite-shell-panel>
<arcgis-map id="mapEl" item-id="210c5b77056846808c7a5ce93920be81">
<arcgis-zoom position="top-right"></arcgis-zoom>
</arcgis-map>
</calcite-shell>
-
Add the
calcite-navigation
component and place it in the shell'sheader
slot. -
Then, slot the
calcite-navigation-logo
component into navigation'slogo
slot. Supply anid
to dynamically populate theheading
with the title of the web map.
<calcite-shell content-behind>
<calcite-navigation slot="header">
<calcite-navigation-logo id="header-title" heading-level="1" slot="logo">
<!-- Dynamically populated -->
</calcite-navigation-logo>
</calcite-navigation>
<calcite-shell-panel slot="panel-start" display-mode="float-content">
</calcite-shell-panel>
Add action and panel components
Next, add the components used to access the ArcGIS Maps SDK for JavaScript components. The calcite-panel
components will have the Map component containers. The panels will start hidden, and users can display them using the corresponding calcite-action
component.
- Add the
calcite-action-bar
component and place it in shell panel'saction-bar
slot. - Add
calcite-action
components, which will open the panels when clicked.- Set the
icon
attribute to the name of the map component that the action will open. View the Calcite Icons to find additional options. - Set the
text
attribute, which will display when uncollapsing the action bar. - Set the
data-action-id
global attribute, which will be used in a subsequent step to make the action interactive.
- Set the
<calcite-shell content-behind>
<calcite-navigation slot="header">
<calcite-navigation-logo id="header-title" heading-level="1" slot="logo">
<!-- Dynamically populated -->
</calcite-navigation-logo>
</calcite-navigation>
<calcite-shell-panel slot="panel-start" display-mode="float-content">
<calcite-action-bar slot="action-bar">
<calcite-action data-action-id="layers" icon="layers" text="Layers"></calcite-action>
<calcite-action data-action-id="basemaps" icon="basemap" text="Basemaps"></calcite-action>
<calcite-action data-action-id="legend" icon="legend" text="Legend"></calcite-action>
<calcite-action data-action-id="bookmarks" icon="bookmark" text="Bookmarks"></calcite-action>
<calcite-action data-action-id="print" icon="print" text="Print"></calcite-action>
<calcite-action data-action-id="information" icon="information" text="Information"></calcite-action>
</calcite-action-bar>
</calcite-shell-panel>
- Below the action bar, add
calcite-panel
components with the containers for the ArcGIS Maps SDK for JavaScript components includingarcgis-layer-list
,arcgis-basemap-gallery
,arcgis-legend
,arcgis-bookmarks
andarcgis-print
.- Set the
heading
attribute for the panel's title. - Set the height of the panel using the
height
attribute. - Set the
closed
attribute, which will be removed when clicking on the corresponding action. - Set the
data-panel-id
global attribute, which will be used in a subsequent step to make the panels interactive.
- Set the
<!-- Map-specific panels (each one provides a div for ArcGIS Maps SDK for JavaScript widgets) -->
<calcite-panel heading="Layers" height-scale="l" data-panel-id="layers" closed closable>
<arcgis-layer-list drag-enabled reference-element="mapEl" visibility-appearance="checkbox"></arcgis-layer-list>
</calcite-panel>
<calcite-panel heading="Basemaps" height-scale="l" data-panel-id="basemaps" closed closable>
<arcgis-basemap-gallery reference-element="mapEl"></arcgis-basemap-gallery>
</calcite-panel>
<calcite-panel heading="Legend" height-scale="l" data-panel-id="legend" closed closable>
<arcgis-legend legend-style="classic" reference-element="mapEl"></arcgis-legend>
</calcite-panel>
<calcite-panel heading="Bookmarks" height-scale="l" data-panel-id="bookmarks" closed closable>
<arcgis-bookmarks editing-enabled="false" reference-element="mapEl"></arcgis-bookmarks>
</calcite-panel>
<calcite-panel heading="Print" height-scale="l" data-panel-id="print" closed closable>
<arcgis-print allowed-formats="all" allowed-layouts="all" include-default-templates="false"
reference-element="mapEl"></arcgis-print>
</calcite-panel>
- Add another
calcite-panel
component. - Create a
div
, and then addimg
anddiv
child elements withid
global attributes. These elements will populate with the web map's thumbnail and description. - Add a
calcite-label
component with thelayout
attribute set to"inline"
. - Add a
calcite-rating
component as the label's child and set theread-only
attribute. This component will populate with the web map's average rating.
<!-- Info panel (populates with info from the web map) -->
<calcite-panel heading="Details" data-panel-id="information" closed closable>
<div id="info-content">
<img id="item-thumbnail" alt="webmap thumbnail" />
<div id="item-description">
<!-- Dynamically populated -->
</div>
<calcite-label layout="inline">
<b>Rating:</b>
<calcite-rating id="item-rating" read-only>
<!-- Dynamically populated -->
</calcite-rating>
</calcite-label>
</div>
</calcite-panel>
Populate the content
You finished adding Calcite Components to your application! Now populate the navigation logo's heading
and info panel with content from the web map.
- Below the existing JavaScript code in the
<script
element, wait for the map to finish loading asynchronously with the> arcgis
event.View Ready Change - Once the map is loaded, use the
query
method to access the DOM and populate the content.Selector() - Next, add
padding
to the left of thearcgis-map
to make room for the ArcGIS Maps SDK for JavaScript components.
const mapEl = document.getElementById("mapEl");
mapEl.addEventListener("arcgisViewReadyChange", (evt) => {
const { title, description, thumbnailUrl, avgRating } = mapEl.map.portalItem;
document.querySelector("#header-title").heading = title;
document.querySelector("#item-description").innerHTML = description;
document.querySelector("#item-thumbnail").src = thumbnailUrl;
document.querySelector("#item-rating").value = avgRating;
mapEl.view.padding = {
left: 49
};
Make components interactive
The next step is to open the calcite-panel
components, which contain the ArcGIS Maps SDK for JavaScript components, when clicking on the corresponding calcite-action
components.
- Inside of the
arcgis
event, initialize a variable to store the name of the map component that is currently open.View Ready Change - Create a function that will execute when an action is clicked. The function will close the active panel and open the panel corresponding to the clicked action. If the user clicks on the active action, the corresponding panel will close and there will not be any open panels.
This step uses attribute selectors to access the action and panel elements using the data attributes you added above. The values of the data attributes are the names of the corresponding map component.
- Create a click event listener on the
calcite-action-bar
using the function above as the callback.
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}]`).closed = true;
}
const nextWidget = target.dataset.actionId;
if (nextWidget !== activeWidget) {
document.querySelector(`[data-action-id=${nextWidget}]`).active = true;
document.querySelector(`[data-panel-id=${nextWidget}]`).closed = false;
activeWidget = nextWidget;
document.querySelector(`[data-panel-id=${nextWidget}]`).setFocus();
} else {
activeWidget = null;
}
};
// Panel interaction
const panelEls = document.querySelectorAll("calcite-panel");
for (let i = 0; i < panelEls.length; i++) {
panelEls[i].addEventListener("calcitePanelClose", () => {
document.querySelector(`[data-action-id=${activeWidget}]`).active = false;
document.querySelector(`[data-action-id=${activeWidget}]`).setFocus();
activeWidget = null;
});
}
Dynamically resize the map
Now that the components are interactive, the map should adjust when the calcite-action-bar
expands and collapses.
- Inside of the
arcgis
event, add an event listener on theView Ready Change calcite
. The listener will add or remove padding to the view when expanded or collapsed respectively.Action Bar Toggle
document.querySelector("calcite-action-bar").addEventListener("click", handleActionBarClick);
let actionBarExpanded = false;
document.addEventListener("calciteActionBarToggle", event => {
actionBarExpanded = !actionBarExpanded;
mapEl.view.padding = {
left: actionBarExpanded ? 135 : 49
};
});
Add a loader component
Now everything is interactive in your application! You can open and close the map components using Calcite Components. However, the application takes a second to load, which should be communicated to the user.
- In the
<body
element, add a> calcite-loader
to display the component. - Add the
hidden
global attribute tocalcite-shell
.
<body>
<calcite-loader></calcite-loader>
<calcite-shell content-behind hidden>
<h2 id="header-title" slot="header">
<!--dynamically populated-->
</h2>
- Inside of the
arcgis
event, below the rest of the JavaScript code, hide theView Ready Change calcite-loader
component with thehidden
property set totrue
, and display thecalcite-shell
component by setting thehidden
property tofalse
.
document.querySelector("calcite-shell").hidden = false;
document.querySelector("calcite-loader").hidden = true;
});
</script>
</html>
Add styling
- In the
<style
element, add some additional CSS to clean up the user interface.>
body {
display: flex;
}
calcite-loader {
align-self: center;
justify-self: center;
}
#info-content {
padding: 0.75rem;
}
calcite-rating {
margin-top: 0.25rem;
}
</style>
Run the app
In CodePen, run your code to display the application. The map will display once the application finishes loading, along with the web map's title and a calcite-action-bar
. Clicking on the calcite-action
components will open and close the calcite-panel
components, which contain the ArcGIS Maps SDK for JavaScript Map components.