Learn how to create a UI for a simple mapping application using Calcite Components and ArcGIS Maps SDK for JavaScript.
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 a
view
element which will display the map. The CSS ensures that the map is the full width and height of the browser window.Div
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,
#viewDiv {
padding: 0;
margin: 0;
height: 100%;
width: 100%;
}
</style>
<body>
<div id="viewDiv"></div>
</body>
<script>
</script>
</html>
- In the
<head
element, add references to Calcite Components and ArcGIS Maps SDK for JavaScript.>
<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/2.13.2/calcite.esm.js" type="module"></script>
<link rel="stylesheet" href="https://js.arcgis.com/calcite-components/2.13.2/calcite.css" />
<script src="https://js.arcgis.com/4.30/"></script>
<link rel="stylesheet" href="https://js.arcgis.com/4.30/esri/themes/light/main.css" />
</head>
<style>
Import modules
- In the
<script
element, import the ArcGIS Maps SDK for JavaScript modules that you will use in this application.>
require([
"esri/WebMap",
"esri/views/MapView",
"esri/widgets/Bookmarks",
"esri/widgets/BasemapGallery",
"esri/widgets/LayerList",
"esri/widgets/Legend",
"esri/widgets/Print"
], function (WebMap, MapView, Bookmarks, BasemapGallery, LayerList, Legend, Print) {
});
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 your developer dashboard to get an API key.
- Back in CodePen >
<script
, import the> esri
class.Config - Set the
api
property.Key
"esri/widgets/Print",
"esri/config"
], function (WebMap, MapView, Bookmarks, BasemapGallery, LayerList, Legend, Print, esriConfig ) {
esriConfig.apiKey = "YOUR_API_KEY";
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 widgets that interact with the map. The widgets will be organized by Calcite Components to keep the user interface clean.
- Initialize a
Web
using theMap id
provided via thewebmap
URL search parameter. If a web mapid
is not provided, it will use the fallbackid
specified in the code.
const webmapId = new URLSearchParams(window.location.search).get("webmap") ?? "210c5b77056846808c7a5ce93920be81";
const map = new WebMap({
portalItem: {
id: webmapId
}
});
- Initialize the
Map
, and addView padding
to the left of the view to make room for the Calcite Components you will add later. - Next, initialize the ArcGIS Maps SDK for JavaScript widgets, placing them in containers which you will create in a subsequent step.
const view = new MapView({
map,
container: "viewDiv",
padding: {
left: 49
}
});
view.ui.move("zoom", "bottom-right");
const basemaps = new BasemapGallery({
view,
container: "basemaps-container"
});
const bookmarks = new Bookmarks({
view,
container: "bookmarks-container"
});
const layerList = new LayerList({
view,
dragEnabled: true,
visibilityAppearance: "checkbox",
container: "layers-container"
});
const legend = new Legend({
view,
container: "legend-container"
});
const print = new Print({
view,
container: "print-container"
});
At this point the application will display a map. However, the widgets you initialized will not appear because they are placed in HTML containers that have not been created yet.
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"
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">
</calcite-shell-panel>
<div id="viewDiv"></div>
</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">
</calcite-shell-panel>
Add action and panel components
Next, add the components used to access the widgets. The calcite-panel
components will have the widgets' 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 widget 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">
<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 widgets you initialized in JavaScript.- Set the
heading
attribute for the panel's title. - Set the height of the panel using the
height-scale
attribute. - Set the
hidden
global 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" hidden>
<div id="layers-container"></div>
</calcite-panel>
<calcite-panel heading="Basemaps" height-scale="l" data-panel-id="basemaps" hidden>
<div id="basemaps-container"></div>
</calcite-panel>
<calcite-panel heading="Legend" height-scale="l" data-panel-id="legend" hidden>
<div id="legend-container"></div>
</calcite-panel>
<calcite-panel heading="Bookmarks" height-scale="l" data-panel-id="bookmarks" hidden>
<div id="bookmarks-container"></div>
</calcite-panel>
<calcite-panel heading="Print" height-scale="l" data-panel-id="print" hidden>
<div id="print-container"></div>
</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" hidden>
<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.> - Once the map is loaded, use the
query
method to access the DOM and populate the content.Selector()
map.when(() => {
const { title, description, thumbnailUrl, avgRating } = 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;
});
Make components interactive
The next step is to open the calcite-panel
components, which contain the ArcGIS Maps SDK for JavaScript widgets, when clicking on the corresponding calcite-action
components.
- Inside of the
map.when()
function, initialize a variable to store the name of the widget that is currently open. - 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 widgets.
- 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}]`).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;
}
};
document.querySelector("calcite-action-bar").addEventListener("click", handleActionBarClick);
Dynamically resize the view
Now that the components are interactive, the map's view should adjust when the calcite-action-bar
expands and collapses.
- Inside of the
map.when()
function, add an event listener on thecalcite
. The listener will add or remove padding to the view when expanded or collapsed respectively.Action Bar Toggle
let actionBarExpanded = false;
document.addEventListener("calciteActionBarToggle", event => {
actionBarExpanded = !actionBarExpanded;
view.padding = {
left: actionBarExpanded ? 135 : 49
};
});
Add a loader component
Now everything is interactive in your application! You can open and close the widgets 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
map.when()
function, below the rest of the JavaScript code, hide thecalcite-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 widgets.