8.1.1 BasemapToggle (deprecated)

There are four key steps in implementing this widget:

1. Set the basemap property of the Map object to the basemap you want the user to see when the app loads.
2. Create the new BasemapToggle object, associating it with a View.
3. Set the BasemapToggle’s nextBasemap property to the other basemap you’d like the user to be able to switch to.
4. Add the widget to the desired screen location.

See the Pen L8_BasemapToggle_widget by Jim Detwiler (@jimdetwiler) on CodePen.

8.1.2 BasemapGallery (deprecated)

This widget provides the user a set of basemap options (with thumbnail previews) to choose from. It's often embedded within an Expand widget, as demonstrated below, allowing it to be expanded/collapsed by the user rather than open at all times. 

See the Pen BasemapGallery_widget by Jim Detwiler (@jimdetwiler) on CodePen.

Where the implementation of these widgets can become more complicated is if you want to offer non-Esri basemap options. First, have a look at this app, which provides a preview of many (mostly open-source) basemaps.

The app lets you preview a basemap by selecting it from the list of mini-maps on the right. Be aware that you can change the map extent to something other than Europe, if desired. After selecting a basemap, you’ll see the JS code that would be used to implement it in Leaflet (an open-source JS API). The Leaflet syntax is not quite the same as Esri’s, but we’ll be able to work out the differences.

Choose the Stadia.StamenTerrain option to follow along with the discussion below. (This is a tiled map developed by Stamen, a cartography and visualization company based in San Francisco, and delivered in partnership with Stadia, another geospatial company.)

Using this basemap in Leaflet involves creating a TileLayer object by specifying the URL of the server that hosts the map tiles, along with some optional parameters such as attribution info and subdomains. (Subdomains are often set up on the tile server to speed up the delivery of tiles to clients.) Note that the server URL contains the letters s, x, y and z in braces. These are placeholders for the subdomain, x coordinate, y coordinate and zoom level, respectively. The TileLayer class is programmed to insert the appropriate values for these placeholders to retrieve the necessary tiles.

In an Esri context, we instead create a WebTileLayer and assign the server URL to the urlTemplate property. Esri’s placeholders are a bit different: subDomain, level, col and row. The subdomains property that was set using a string of characters in Leaflet is the subDomains property set using an array of strings in Esri. Finally, the attribution property in Leaflet is instead the copyright property in Esri. If we wanted to create an Esri WebTileLayer based on the Stamen Terrain basemap, the code would look like this:

const terrainLayer = new WebTileLayer({ 
  urlTemplate: 'https://tiles.stadiamaps.com/tiles/stamen_terrain/{level}/{col}/{row}.png',
  subDomains: ["a","b","c","d"],
  copyright: '&copy; <a href="https://www.stadiamaps.com/" target="_blank">Stadia Maps</a> &copy; <a href="https://www.stamen.com/" target="_blank">Stamen Design</a> &copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> &copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
});

The next step is to create a new Basemap object from the WebTileLayer:

const terrain = new Basemap({
  baseLayers: [terrainLayer],
  title: "Stamen Terrain",
  id: "terrain",
  thumbnailUrl: 
"http://www.arcgis.com/sharing/rest/content/items/d9118dcf7f3c4789aa66834b6114ec70/info/thumbnail/terrain.png"
});

The thumbnailUrl property provides control over the preview image that appears for the basemap option when displayed by one of the basemap widgets. You’re welcome to create this thumbnail yourself based on some desired extent. (If on Windows, you can print the screen to the Windows clipboard and use an image editing app like Paint to crop and re-size. The image should be sized to 200x133 pixels.) If you don’t want to go to that trouble, you might have luck searching for the basemap in ArcGIS Online and copying the URL of the thumbnail that you find there. That is what I did in this case.

Have a look at the source code for the example below:

See the Pen Custom BasemapGallery by Jim Detwiler (@jimdetwiler) on CodePen.

In this app, I’ve implemented the BasemapGallery widget with two non-Esri basemaps: Stamen Terrain, discussed above, and the Positron basemap developed by Carto (a company based in Madrid). I want to draw your attention to a couple of important points:

• after the creation of the two Basemap objects, a LocalBasemapsSource object is created and used to set the BasemapGallery’s source property,
• after the source property is set, the activeBasemap property is set to one of the basemaps.

8.1.4 Home (deprecated)

The Home widget is used to provide users with the ability to return to the app’s initial viewpoint. To implement the widget, you simply need to create a new Home object and set its view property to the appropriate View. You then specify where to add the widget on the UI as seen with the earlier widgets. 

See the Pen HomeWidget by Jim Detwiler (@jimdetwiler) on CodePen.

The LayerList widget is used to provide users with a list of the app’s operational layers and the ability to toggle the layer visibility on/off.  As with the BasemapGallery, this is another widget that is often embedded within the Expand widget.

See the Pen LayerList_widget by Jim Detwiler (@jimdetwiler) on CodePen.

We saw the Legend widget used earlier in the course. Basic implementation of this widget is simple, only requiring you to specify the View containing the layers you’d like listed in the legend. By default, the widget will display an entry for each layer in the view, though this can be overridden. Here are a couple of examples, built on the UniqueValueRenderer example from Lesson 5:

Uncustomized legend

See the Pen Uncustomized Legend Demo by Jim Detwiler (@jimdetwiler) on CodePen.

Customized legend

See the Pen Legend Demo by Jim Detwiler (@jimdetwiler) on CodePen.

In the first example, the Legend has only its view property set. Note that each of the two layers displayed on the map are included in the legend and that the labels for each legend entry are taken from the layer source’s name.

In the second example, the layerInfos property is used to customize the legend a bit. Only one object is defined in the layerInfos array, for the cities layer, so the counties layer is not added to the legend. A more user-friendly title is also applied to the cities layer.

Esri’s Legend widget sample demonstrates a similar customization of a layer’s title. One thing I want to call your attention to is in how the reference to the layer is obtained. The layer is actually the first layer in a web map and is retrieved using the expression webmap.layers.getItemAt(0).

8.1.7 ScaleBar (deprecated)

I’m guessing you haven’t been living under a rock all your life and are familiar with the concept of a scale bar. The ScaleBar widget has two main properties that you may want to set: style and unit. The unit property can be set to "metric", "imperial" or "dual". The style property can be set to "ruler" or "line". Here's an example that shows a map with two ScaleBar widgets:

See the Pen ScaleBar demo by Jim Detwiler (@jimdetwiler) on CodePen.

The difference between the two styles is that the ruler style conveys multiple distances at once (e.g., 25, 50, 75, and 100 km), whereas the line style only conveys a single distance. Setting the unit to dual will produce a line with the metric label on top and the imperial label on the bottom.

This Esri sample allows the user to switch easily back and forth between 3D terrain layers depicting an area before and after a landslide. A checkbox is used to toggle between the two layers. Let’s look at how this checkbox is coded.

First, a semi-transparent div (with id of "paneDiv") is positioned in the bottom right of the map. Embedded within that div are three child elements -- another div (id of "infoDiv") that provides brief instructions, an input element (type of "checkbox" and id of "elevAfter"), and a label that's been associated with that checkbox (done using the attribute setting for="elevAfter").  

There's a lot going on in this sample, most of it outside the scope of what I want to get across here.  Focusing on how to implement a checkbox, note the inclusion here of the checked attribute.  checked is an example of a Boolean attribute.  You don't need to set it equal to any value.  If the checked attribute is present, the box will be checked when the page loads; if that attribute is omitted, the box will be unchecked.  

The assignment of an id to the checkbox is an important step in the implementation as that's what enables working with the element in the JS code.  The JS code associated with the checkbox appears on lines 185-187. The DOM's getElementById() method is used to get a reference to the checkbox, plugging in the id that was assigned to the element in the HTML code. The DOM's addEventListener() method is then used to set up a "listener" for a certain kind of event to occur in relation to the checkbox – in this case, the "change" event. As outlined on the w3schools site, addEventListener() has two required arguments: the event to listen for and a function to execute when that event is triggered. And similar to how a promise returns an object to its callback function, the addEventListener() method passes an event object to its associated function. While this event object has a few different properties, the most applicable in most cases is the one used here – target. The target property returns a reference to the element that triggered the event, which in this case is an input element of type checkbox. So what’s happening on line 186 is the layer that represents the terrain after the landslide has its visible property set to event.target.checked. In other words, if the box is checked (event.target.checked returns true), then the "after" layer’s visible property is set to true. If the box is unchecked (event.target.checked returns false), then the layer’s visible property is set to false.  (The "after" layer is what we see when its visible property is true because the two layers were added to the Map up on line 56 with "before" coming first in the array and "after" second.  The "before" layer gets drawn first, then the "after" layer is drawn on top of it.  So the "before" layer will only be seen if the "after" layer is toggled off.)

If you look over the rest of the code, don't fret if you have trouble following.  It's fairly advanced.  Focus on the checkbox pieces, which have been discussed here.

As you saw in the w3schools tutorial, a dropdown list is created in HTML using a select element. This Esri sample shows a simple usage of a select element to provide the user a list of floors in a building. The user selecting one of the floor options causes only the features from that floor to be displayed.

First, have a look at the HTML. As with the earlier samples, a div is created to hold the UI element (here given an id of "optionsDiv"). Within the div is the select element and its child option elements. Each option has a value attribute (which can be accessed using JS) and the text that the user sees (the text between the start and end tags). In many cases, those two strings are the same. Here, the value attribute is assigned an expression in which the floor number is just part of a larger string. We’ll come back to that expression in a moment.

As we saw in the previous sample, the addEventListener() method is used here to set up a handler for an event associated with a form element.  In the previous sample, an anonymous callback function was embedded directly within the addEventListener() statement.  In this case, the name of a function defined elsewhere (showFloors) is specified instead.  This function will be executed whenever the floorSelect element has its change event triggered. 

The showFloors() function is defined on lines 135-149. The same expression we saw earlier (event.target) is used to get a reference to the element the listener is attached to. Unlike the checkbox sample, where the checked property was read, here the value property is read to obtain the select element’s value (e.g., "FLOOR = '1'", "FLOOR = '2'", etc.).

One wrinkle in setting the definitionExpression is that the building identifying field is not the same in all the layers. Part of the solution to this problem is the buildingQuery variable defined on lines 64-69. This object variable is defined having the layer names as the keys and the corresponding expressions needed to select building Q as the values. The definitionExpression has two parts: the first, built by retrieving the appropriate building Q selection expression from the buildingQuery variable (using layer.title as the key); the second, built using the value of the selected option in the dropdown list.

An interesting point to note is the way that the "All" option is handled. It’s assigned a value of "1=1", which may seem strange at first glance. However, it makes sense when you stop to think about it. Let’s say that the loop is processing the Walls layer. That layer will have its definitionExpression set to "BUILDINGKEY = 'Q' AND 1=1". In deciding whether a feature should be included in the layer, each side of the expression will be evaluated as either true or false. The AND operator indicates that both sides of the expression must be true. The expression 1=1 is always true, which gives the desired result of all features being displayed, regardless of their FLOOR value.

The next sample also makes use of the select element (three of them, actually), but unlike the previous sample, the script’s main logic isn’t carried out until a button is clicked. The button is created on line 282 as an HTML button element, and as seen in prior samples, is assigned an id. As in the previous sample, an event listener is defined (line 165). In this case, the listener is set up on the button’s click event. References to the three select elements are established on lines 168-170; they are then used to retrieve the selected options on line 191.

The pen below shows a simple app that provides the user a text box to enter the name of a hurricane to display on the map.

See the Pen Text box demo by Jim Detwiler (@jimdetwiler) on CodePen.

Some noteworthy aspects of this app:

• A div (id of "paneDiv") is the container for all of the custom UI elements.
• Within that div are an input element of type="text" and a button element.  Both are assigned ids so that they can be accessed in the JS code.
• The input element has its placeholder attribute set to provide a prompt to the user on the sort of entry expected in the box.  This and other input attributes are described at w3schools.
• Line 36 of the code establishes a listener for the button's click event, the getTrack() function.
• That function obtains the name entered by the user into the text box by reading its value property on line 43.  
• The storm name is then incorporated into a definitionExpression applied to the FeatureLayer that was created earlier in the code.

A slider control can be an effective means of enabling the user to specify a numeric parameter within a range of possible values. The example below -- based on an Esri sample that appears to no longer be in their SDK -- demonstrates how a range slider can be implemented in an Esri JS app.  HTML5 makes it possible to insert a slider onto a page using an input element of type="range", and in fact, an earlier version of the Esri sample displayed the sliders using that element type.  However, the example below uses the Slider widget, which was introduced at v4.12 of Esri's Maps SDK for JS.  

See the Pen Slider widget demo by Jim Detwiler (@jimdetwiler) on CodePen.

Initial setup

Two divs are defined at the bottom of the HTML (lines 242 and 244) to serve as placeholders for the two Slider widgets.  The widget objects themselves are created early in the JS code, on lines 27-54.  The min and max property settings should be self-explanatory. The steps attribute specifies how much the slider value can be incremented when it is dragged, relative to its min value. Here, a step of 100 and a min of 0 means that the slider can take on values of 0, 100, 200, etc. If the min were changed to 50, possible values would be 50, 150, 250, etc. The values property specifies the positions on the slider where "thumbs" should be placed.  Each of the sample's sliders has a single thumb, but the widget allows for defining multiple thumbs (say, to enable the user to specify a range of quake magnitudes instead of just a minimum magnitude as the sample is written). 

Getting the slider value

Also near the top of the JS code, references are obtained to the UI's dropdown list and button using the getElementById() method we've seen in the previous samples. A listener is set up for the button's click event on lines 203-205, which specifies that a click on the button should trigger execution of a function called queryEarthquakes(). That function creates a Query object that looks for features in an earthquake layer that have a magnitude value greater than or equal to what the user specified through the magnitude slider. We talked about queries in the last lesson, so that’s not my focus here. What I want you to focus on is that the slider's value is obtained simply by reading its values property (the same property that was used to define the initial thumb position).  An index of [0] is specified here to get the only thumb value, but keep in mind that you would also need to specify an index of [1] if as suggested above you allowed the user to define a range of desired values.  The single user-selected magnitude value is then used to set the Query's where property,  That constraint combined with the well buffer distance ultimately determines which earthquakes will be added to the map as Graphic objects by the displayResults() function.  

Many apps require the user to input one or more dates. It is possible to acquire dates through a plain text box. However, using a "date picker" widget can make the entry task a bit less tedious for the user, and just as importantly, help ensure that the date is supplied in the correct format. HTML5 introduced a new input type of Date that provides a date picker, and its use is demonstrated here:

See the Pen Date Picker v4.13+ by Jim Detwiler (@jimdetwiler) on CodePen.

Looking at the HTML at the bottom of the example, you should note the following:

• The two input elements are assigned a type="date" attribute. 
• An id is assigned to each element so that it can be manipulated with JS code. 
• The min and max attributes can be used to limit the dates available to the user. These attributes are set dynamically via the setDates() JS function so that the app allows for selecting dates between today and 30 days ago. However, if such dynamic behavior isn't needed, the attribute values could be hard-coded in the HTML using a yyyy-mm-dd format.
• The required attribute specifies whether or not the user should be allowed to skip over that UI element.

Now have a look at how the selected dates are retrieved in the getFires() function. First, just above the function, references to the dateFrom and dateTo elements are obtained using getElementById(). The selected dates are then retrieved by reading the value property and inserted into a definition expression that causes the layer to display only the features for which the FireDiscoveryDateTime field has a value that falls between the two selected dates. 

Of course, it's not always the case that a date picker needs to have its attributes set dynamically. Below is an example that shows data from another wildfire layer, this one containing historical data for the year 2019. As the date range is predetermined, the date pickers can have their attributes hard-coded in the HTML rather than computed on the fly in the JS. (Note that this is a polygon layer and depending on the range entered, you may need to zoom in a bit to see any of the returned polygons.)

See the Pen Date Picker v4.13+ (hard-coded dates) by Jim Detwiler (@jimdetwiler) on CodePen.

For this walkthrough, we’ll create an app that displays data from a WebMap and provides the ability to toggle layers on/off and change basemaps through a Calcite Action Bar.

A. Create a basic app and add references to Calcite

1. Use Esri's Load a Basic WebMap Esri sample as a starting point, opening it in CodePen.  Feel free to replace the WebMap portal ID to one of your own, if you wish.
2. Change the title of the document to First Calcite Walkthrough.
3. Move the CSS and JS code to the appropriate CodePen windows.

4. Add the following Calcite reference to your HTML, above the references to the Maps SDK for JS:

     <script type="module" src="https://js.arcgis.com/calcite-components/3.2.1/calcite.esm.js"></script>

B. Add a Shell component

Apps built using Calcite components typically have them embedded within a Shell component, and that's how we'll begin here. 

1. First, access the documentation of this component by going to the Calcite documentation homepage, clicking the Components tab, scrolling down the alphabetical list of components on the left side of the page, then selecting Shell > Shell. 
   
   As its name implies, the Shell component is used as a kind of parent container for the other elements that make up your mapping application. 
   
   Like other components, the documentation includes an Overview of the component and some notes on its Usage.  It then provides an interactive Sample section intended to give an opportunity to see the component in action and to experiment with its properties, slots, variables, and events. 
   
   The Shell component documentation provides 3 samples at the time of writing.  If you click on the dropdown menu in the upper left of the UI, you should see that in addition to the default sample, there are also “Shell – with content” and “Shell – with content – bottom” variants.
   
   The Sample area of the page has a top and a bottom.  On the top, you’ll see the component in action.  On the bottom, you’ll see the code that produces the result on top (broken down into its HTML, CSS, and JS pieces).  Let’s look briefly at the code.
   
   As is often the case, the sample code for the Shell component includes a number of other components.  The Shell typically houses one or more Shell Panel components.  In fact, it has been configured with slots for displaying Shell Panels (panel-start, panel-end, panel-top, and panel-bottom).  In the sample, there is a calcite-shell-panel element in the panel-start slot and another in the panel-end slot.  The one in the panel-start slot contains an Action Bar component, which itself contains 3 Action components.  We’ll implement these same components momentarily.
   
   While we’re looking at the Code part of the Sample UI, note the buttons in the upper right that allow you to copy the code to your clipboard or to open the sample in CodePen. 
   
   Continuing past the Sample part of the page you’ll find documentation of the component’s Properties, Slots, and Styles. 
   
   With that orientation done, let’s get back to our walkthrough. 

2. In the body of the document, add a Shell component and move the “viewDiv” inside of it:

       <calcite-shell content-behind>
           <div id="viewDiv"></div> 
       </calcite-shell>

   As noted in the Shell documentation, content-behind is a property that controls whether the Shell’s center content will be positioned behind any of its child Shell Panels.  The default setting of this property is false; here we’re setting it to true.

3. Next, let’s add an h2 element to the Shell’s header slot.  Add this code inside the calcite-shell element, before “viewDiv”:

       <h2 id="header-title" slot="header">
           <!-- Populated at runtime -->
       </h2>

4. Set the header’s margins (using CSS):

       #header-title {
         margin-left: 1rem;
         margin-right: 1rem;
       }

5. Now add the following JS code to dynamically set the header once the WebMap has been loaded:

     webmap.when(() => {
       const title = webmap.portalItem.title;
       document.getElementById("header-title").textContent = title;
     });

6. Go ahead and test your app.  The header should say “Accidental Deaths” if you stuck with the WebMap from the Esri sample.

C. Add a Shell Panel and Action Bar

Now let’s add a Shell Panel that will house the Action Bar with the desired functionality.

1. Back in the HTML, add the Shell Panel between the h2 element and the “viewDiv” as follows:

       <calcite-shell-panel slot="panel-start" display-mode="float">
       </calcite-shell-panel>

   Note that this associates the Shell Panel with the Shell’s panel-start slot (mentioned briefly earlier) and sets its display-mode property.  You could navigate to the Shell Panel page in the Calcite documentation to see the values allowed for this property. 

2. Next, let’s add the Action Bar to the Shell Panel.  Shell Panels are configured with an action-bar slot, so we'll add it to that slot:

       <calcite-action-bar slot="action-bar">
       </calcite-action-bar>

3. Test the app again.  You should now see a narrow vertical strip on the left side of the page with a button for expanding/collapsing the strip.  (The Action Bar is empty because we haven’t added any Actions to it yet.)

D. Add an Action to the Action Bar

1. Add an Action component for toggling layer visibility inside the Action Bar:

       <calcite-action data-action-id="layers" icon="layers" text="Layers">
       </calcite-action>

2. Test the app again and note that you now have a button at the top of the Action Bar strip.  Expand the Action Bar and note the label Layers appears next to the button, which comes from the setting of the Action’s text property. 
   
   Lastly, note that the button’s icon comes from setting the Action’s icon property.  How do you know how to set that property?
3. Return to the Calcite documentation and click on the Icons tab (upper right of the page).  On the Icons page you’ll find an alphabetical list of 1100+ available icons.  In this scenario, you might enter the word layers into the search box at the top of the page, which returns a much shorter list.  (Presumably the icons are tagged with keywords since some of the results don’t match on name.)  Scrolling down, you should see the “layers” icon used here.  Other icons could be suitable in its place.
   
   The button doesn’t actually do anything yet though.  What we’d like it to do is display a list of the layers in the WebMap along with buttons for toggling each layer on/off.  To produce that behavior, we’ll use a Panel component (different from a Shell Panel) to display a LayerList widget (discussed earlier in the lesson). 

4. Add a Panel immediately after the Action Bar with the following code:

       <calcite-panel heading="Layers" data-panel-id="layers" hidden>
       </calcite-panel>

   data-panel-id is a custom attribute that we’ll use momentarily in our JS code to show/hide the Panel.

5. As noted, we’re going to use a LayerList widget to provide the user with the ability to toggle layer visibility.  This widget won’t be associated with the Panel component directly, but with a div element embedded within the Panel.
   
   Within the calcite-panel element, add the div element:

       <div id="layers-container"></div>

   We assign the div an id so that we can easily wire it up to the LayerList widget we’re about to create.

6. Shift to your JS code and add a reference to the LayerList module:

       const [MapView, WebMap, LayerList] = await $arcgis.import([
         "@arcgis/core/views/MapView.js",
         "@arcgis/core/WebMap.js",
         "@arcgis/core/widgets/LayerList.js"
       ]);    
   

7. Next, create a new LayerList object immediately after the creation of the MapView:

       const layerList = new LayerList({ 
           view: view,
           selectionEnabled: true,
           container: "layers-container"
       });

   
   Note the setting of the container property to the div we created moments ago.
   
   At this point, the Action component doesn't actually perform any action.  To rectify that, we need to add some code that will process user clicks on the Action Bar.

E. Add a handler for clicks on the Action Bar

1. Start by defining a variable to track the active widget (add this to the end of your existing JS code:

     let activeWidget;

2. Next, define a handleActionBarClick function:

     const handleActionBarClick = ( event ) => {
       const target = event.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;
       }
     };

3. And now configure a listener that triggers execution of the handleActionBarClick() function when the Action Bar is clicked:

     document.querySelector("calcite-action-bar").addEventListener("click", handleActionBarClick);

4. Test the app, confirming that a click on the Layers Action opens a Panel showing the LayerList widget and that clicking it again hides the Panel.
   
   Let’s talk about what’s happening in the code just added.  First, note that the event listener uses the DOM’s querySelector() method to get a reference to the Action Bar.  This is a similar method to getElementById(), but more flexible.  Rather than being limited to referring to elements by their id attribute, you can also find them by tag name or class, much like you can refer to elements in your CSS code.  Here we’re finding the first element with the tag of "calcite-action-bar" and adding the event listener.
   
   Looking at handleActionBarClick(), it accepts the event object passed from addEventListener(), storing it in the event variable, then obtains a reference to the target of the click.  The first if block then checks to make sure that the target has a tagName of "CALCITE-ACTION".  If it does, that means an Action component was clicked.  If it does not, that means the user clicked on the Action Bar, but in an empty area rather than on an Action.  In that case, a return statement is used to exit out of the function.
   
   The second if block checks to see if there is an active widget associated with the Action Bar (i.e., that one of its Actions has been clicked previously and that an associated Panel component is currently visible).  If so, then a subsequent click on the Action should close the Panel.  And that is what the code block does, though some of the syntax used may be new to you.  The querySelector() method is used again, but note that the string supplied in parentheses is enclosed in backquote (also called backtick) characters.  This character is typically in the upper left of the keyboard, paired with the tilde character.  The backquote is used in JavaScript to define "string templates," one purpose of which is to insert values from variables into strings without the need for more complicated concatenation.  W3Schools has a discussion of string templates.
   
   The other aspect of the querySelector() statements that may require clarification is the use of square brackets.  This syntax is used to search for elements based on an attribute name.   Again, see W3Schools Query Selector.
   
   So, imagine that the "layers" Action has been clicked and its associated Panel is visible.  If the user clicks on that Action again, this block of code will be executed.  First, a query will be made for an element having an attribute setting of data-action-id=layers.  This will return the Action component and then set its active property to false.  (The Calcite documentation indicates that the component is highlighted when the active property is true, which I take to mean it has a blue outline.  I would expect that setting the property to false would cause that outline to disappear, but that’s not the behavior I’m seeing.  Setting the active property to false seemingly has no effect.)  The second querySelector() statement looks for an element with an attribute setting of data-panel-id=layers.  This will return the Panel component associated with the Action and then set its hidden property to true.  This causes the Panel to disappear.
   
   The next statement obtains a reference to the widget the user just clicked on.  Exactly how this works is a bit of a mystery to me, I’m afraid.  If the user clicks on a button on the Action Bar, then target will refer to an Action component.  The code then reads the dataset property and then the actionId of the object returned by the dataset property.  However, I see no dataset property listed in the Action component documentation, which is why I don’t fully understand what’s happening in this statement.  In any case, nextWidget will take on the name of the Action just clicked (e.g., "layers"). 
   
   Next comes an if block that checks whether nextWidget is the same as activeWidget.  If they are the same, that means the user clicked on an Action whose Panel was already visible.  It would have been hidden by the first part of the function and this part will simply set activeWIdget to null.  If nextWidget is not the same as activeWidget, then essentially the reverse of the logic described above occurs.  The just-clicked Action has its active property set to true and its associated Panel’s hidden property set to false.
   
   That was a lot of explanation for a relatively short block of code.  The good news is that adding other Actions to the Action Bar will be much easier.  Recall that the scenario called for the ability to change basemaps, so let’s build that in now.

F. Add a second Action to the Action Bar

1. Add another Action component to the Action Bar beneath the Layers Action (in the HTML):

       <calcite-action data-action-id="basemaps" icon="basemap" text="Basemaps">
       </calcite-action>

2. Further down in the HTML, add a Panel component to go with the Action:

       <calcite-panel heading="Basemaps" height-scale="l" data-panel-id="basemaps" hidden>        
           <div id="basemaps-container"></div>   
       </calcite-panel>

3. Add a reference to the BasemapGallery module (in the JS):

       const [MapView, WebMap, LayerList, BasemapGallery] = await $arcgis.import([
         "@arcgis/core/views/MapView.js",
         "@arcgis/core/WebMap.js",
         "@arcgis/core/widgets/LayerList.js",
         "@arcgis/core/widgets/BasemapGallery.js"
       ]);    
   

4. Instantiate a new BasemapGallery widget and associate it with the div embedded within the basemaps Panel component:

       const basemaps = new BasemapGallery({        
           view: view,        
           container: "basemaps-container"      
       });

G. Adjust view padding when Action Bar is toggled

One last thing we may want to do concerns what happens when the user expands the Action Bar (by clicking the arrows at the bottom of the bar). Note that the bar expands at the expense of the western edge of the MapView. This may not be a big deal, but an alternative is to increase the left padding of the MapView when the Action Bar is expanded.

1. Add the following code to the end of the app’s JS block:

       let actionBarExpanded = false;
       document.addEventListener("calciteActionBarToggle", event => {
           actionBarExpanded = !actionBarExpanded;
           view.padding = {
             left: actionBarExpanded ? 135 : 50
           };
       });
   

   This code creates a variable to track whether or not the Action Bar is expanded and initializes it to false. It then configures a listener for the Action Bar’s calciteActionBarToggle event (see the Action Bar documentation). The function associated with the event is defined inline. It first flips the actionBarExpanded variable to its inverse. If it’s false, make it true; if it’s true, make it false. It then sets the view’s left-side padding to the expression actionBarExpanded ? 135 : 50. This expression uses the “ternary operator” (a shorthand for a longer if-else block) to assign a value of 135 if actionBarExpanded is true and 50 if it’s false.

2. Run the app again and confirm that expanding the Action Bar causes the map to shift to the right.  You may want to remove the code block just added and test again to get a good grasp of what the code is doing.

With this walkthrough complete, let's have a look at a few other working examples that demonstrate some other useful Calcite components.

As you've no doubt seen as an end user of graphical user interfaces, tabs are often provided for switching between parts of the interface.  Calcite provides a Tabs component for developers to implement this sort of design.  The Tabs component has a child Tab Nav component, which defines the navigation piece of the interface (i.e., the tab headings/labels).  The headings are defined using Tab Title components.  In addition to the Tab Nav, the Tabs component also contains multiple child Tab components (one for each Tab Title). 

Here's an example that demonstrates the implementation of the Tabs component:

See the Pen calcite tabs by Jim Detwiler (@jimdetwiler) on CodePen.

This app is used to present data from a set of related AGO web maps, each web map being displayed through a different tab.  Note in the HTML the use of the calcite-tabs, calcite-tab-nav, calcite-tab-title, and calcite-tab elements, corresponding to the components discussed above.  Also note that each calcite-tab contains a div that is used as a container for a WebMap.  The JS code is fairly straightforward.  A separate WebMap and MapView object is created for each race category that had a tab configured for it in the HTML.

The coding of this app is not particularly graceful as it contains a lot of copy/pasted lines in both the HTML and JS.  Here's a version of the app that handles the creation of the tabs more elegantly:

See the Pen calcite tabs array by Jim Detwiler (@jimdetwiler) on CodePen.

In this version, note the following: 

• Only the Tabs component is defined in the HTML at design time; its child components are created dynamically by the JS.
• The child components are created and added to the page using the DOM createElement() and appendChild() methods introduced earlier in the lesson.
• An object -- stored in the groups constant -- is used to define the racial groups to be displayed by the app along with their portal IDs.  The group names are the object properties, while the portal IDs are the associated values.
• A loop is used to iterate over each property/value pair in the groups object.
• Within the loop, the key variable stores the group name on the current iteration.  Retrieving the portal ID for that group is done using the expression groups[key].
• With this version of the app, adding other racial groups is as simple as adding the name and portal ID to the groups variable (as opposed to copying/modifying several lines in both the HTML and JS).

Earlier in the lesson we saw that dates can be obtained from the user via the date input type built into HTML5. Another option for obtaining dates is Calcite's Date Picker component. This component is demonstrated in the CodePen below:

See the Pen calcite date picker by Jim Detwiler (@jimdetwiler) on CodePen.

Looking at the HTML, you should note that the two date widgets are created using calcite-input-date-picker elements. The scale="s" setting gives them a small size (with "m" and "l" being other options for that property).  Looking at the surrounding code, it begins with a similar configuration to the Action Bar example discussed earlier.  Everything in the body is enclosed within a Shell component, a div for the MapView goes in the Shell's default slot, and the div is followed by a Shell Panel component.  Unlike the Action Bar example, here the Shell Panel goes in the panel-end slot rather than panel-start.  

Within the Shell Panel is embedded a Panel component.  The heading property is set to show the Wildfire Viewer text at the top of the panel.  Next comes a Block component, which is used as an organizer for a set of related controls (here the Date Pickers and Button).  Nicely formatted headings are displayed at the top of the Block through the setting of its heading and description properties. Blocks are closed/collapsed by default, so the open property is set to display the Block content.  

Within the Block are the Date Pickers followed by a Button component.  id's are assigned to each of the elements so that they can be referenced in the JavaScript code.  

One last component is placed with the Block -- a Notice component.  This is used to display a nicely formatted message to the user on the number of fires found in the specified date range.  

In the JS code, the setDates() function is immediately called upon when the page loads. That function creates two Date objects: one representing today and the other 30 days prior to today. Those JS Date objects are used to set the widgets' initial values and constraints (min and max possible dates). This is in contrast to the earlier date picker example, in which those attributes were set to strings in yyyy-mm-dd format.

The rest of the app works exactly the same as the earlier date picker example.

And paralleling the earlier page that covered the HTML5 date picker, below is an example built on the 2019 wildfire layer in which the DateTextBox dijit's values and constraints have been hard-coded within the HTML.

See the Pen calcite date picker dynamic by Jim Detwiler (@jimdetwiler) on CodePen.

Two other controls often found in user interfaces are the combo box and the button.  In the CodePen below, I've implemented Calcite's Combobox and Button components in a modification of the mountain peak filtering sample we saw earlier:

See the Pen calcite peaks by Jim Detwiler (@jimdetwiler) on CodePen.

In this version of the app, I've replaced the vanilla HTML select elements with calcite-combobox elements and the HTML option elements with calcite-combobox-item elements.  The Calcite Combobox's default behavior is to allow for multiple selections, which isn't really suitable for this scenario.  To produce the best result, we want to override the default behavior by setting the selection-mode, selection-display, and clear-disabled attributes.  Rather than repeat the same HTML attribute settings for each calcite-combobox, note that the settings are made using JS code.  The DOM's querySelectorsAll() method is used to get a reference to the calcite-combobox elements (as a NodeList).  This NodeList object is stored in a constant called comboBoxes.  A for loop is then used to iterate over each combobox, with the DOM's setAttribute() method used to set the three attributes noted above to desired values.  

Returning to the HTML, note that I've replaced the vanilla HTML button element with a calcite-button element.  One benefit to this change is the ability to configure an icon to appear alongside the button text, either before or after it.  Here I've added Calcite's query icon after the text by setting the icon-end attribute. 

Finally, note that I carried over the id values from the select and button elements in the Esri sample to the calcite-comboboxes and calcite-button elements in my modification.  Thus, the sample's doQuery() function needed no changes.

We've really just scratched the surface of Calcite components that could be useful in developing geospatial apps. I encourage you to browse through the Calcite components documentation to see some of the other UI elements that are available. Here are a few that are particularly useful, in my opinion:

• Accordion
• Menu
• Tree
• Color Picker
• Dropdown
• Progress

With that, we've reached the end of the lesson content on GUI development.  For this week's assignment, you'll return to your Assignment 7 scenario and develop a more user-friendly and informative version of that app.

Some background on web components technology can be found on Mozilla Developer. (Read as far as you like, but focus on the brief Concepts and Usage section at the top of the article.  Also note that we won't be creating web components as outlined by the 5 steps at the end of that section.  We'll just be consuming components created by Esri.)

Let's begin by examining a sample from Esri's Maps SDK for JS documentation.

1. Go to the Sample Code area of the documentation, find the Intro to map components (2D) sample under the Get Started heading, and have a look at the code in the sandbox or CodePen. 
   
   Note that a map is added to the page through the use of a custom arcgis-map element.  No need to instantiate separate Map and MapView objects as required when working strictly with the Core API.  Initial map settings (basemap, zoom, and center) are applied as attributes on the HTML element.
2. Adjust the zoom and center attributes to focus the map on your area of interest.

3. Add zoom and home buttons to the UI using the Zoom and Home components:

   <arcgis-map basemap="topo-vector" zoom="4" center="15, 65">
         <arcgis-zoom position="top-left"></arcgis-zoom>
         <arcgis-home position="top-left"></arcgis-home>
   </arcgis-map>

   If you’d like to use the Map component to display a web map saved in ArcGIS Online, making that happen is as simple as setting its item-id attribute.

4. Go into AGO, find your Jen and Barry’s web map from Lesson 1, copy its portal item ID, and use it to set the map's item-id.  Your web map will carry a basemap setting with it, so while setting the item-id attribute, you can also remove the basemap attribute:

   <arcgis-map basemap="topo-vector" item-id="<your web map id here>" zoom="6" center="-78, 42">

Awesome, huh?  You're probably wondering why we didn't talk about this sooner.  It's possible that as the course evolves, we'll shift the discussion of map components toward the beginning.  These coarse-grained elements can really make it easy to put together relatively simple apps.  However, if your app has much complexity to it, you're going to have to work with the finer-grained objects from the Core API.  The two parts of the SDK are not mutually exclusive, and we'll momentarily how to build an app that utilizes both map components and objects from the Core API.

Before we do that, here are a few important points to note in this map component sample:

• You should add references to the Maps SDK for JS in the head of the HTML document, just as we've been doing.

• The map components must be referenced separately (also in the head):

  <script type="module" src="https://js.arcgis.com/4.33/map-components"></script>

• In the body of the doc, you no longer need a div that will serve as the container for a Core API Map object. The arcgis-map element will serve that purpose now. (If you want a 3D map instead, you can use arcgis-scene rather than arcgis-map.)
• JavaScript code that builds upon the components should go in a script element in the page body as opposed to the head.

Map components can simplify the basics of app development, but at some point you’re likely to need the more fine-grained objects made available through the Core API we’ve been working with during the class.  The Intro to map components (2D) sample provides a crosswalk of sorts for connecting map component code with Core API code.  The first step is to obtain a reference to the Map’s DOM element:     

     const viewElement = document.querySelector("arcgis-map");

From there, you can set up a listener for when the Map is ready for interaction:

      viewElement.addEventListener("arcgisViewReadyChange", (event) => {
        console.log("Map component is ready", event);
      });

Any code you want to build upon the map components can be embedded within this anonymous event listener. 

Picking up where we left off, let’s add Penn State buildings (which we worked with in Lesson 1) to the map as a FeatureLayer.  The first step will be to import that module. 

1. Add the following to the top of the script element that holds your JS code:

         const [FeatureLayer] = await $arcgis.import(
           ["@arcgis/core/layers/FeatureLayer.js"]
         );

2. Within the listener for the “arcgisViewReadyChange” event, instantiate a new FeatureLayer:

         const buildingsLyr = new FeatureLayer({
             url: "https://mapservices.pasda.psu.edu/server/rest/services/pasda/PSU_Campus/MapServer/1"
         });

   Creation of this FeatureLayer could also happen before getting the reference to the Map component.

3. Finally, add the FeatureLayer to the map:

         viewElement.map.add(buildingsLyr);

Note that while the arcgis-map element is referred to as a Map component, adding one to your page actually creates a MapView from the Core API. Thus, to add a layer, you need to access the Map associated with the MapView through its map property (viewElement.map). In this last step, you could certainly store a reference to the Map instead of chaining:

           const map = viewElement.map;
           map.add(buildingsLyr);

Finally, a side note on $arcgis.import()… We’ve implemented this function with arrays of modules/variables, but you should be aware that it can also be implemented without arrays. For example, in this little walkthrough in which FeatureLayer is the only Core API module being imported, we could do the import as follows instead:

           const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

You'll see single modules imported in this way in the documentation and I didn’t want the different syntax to throw you off.

The documentation of the SDK's map components can be accessed by going to the documentation home page (https://developers.arcgis.com/javascript/latest/), clicking on the References tab, and then on the Map Components box.  Alternatively, if you happen to be looking at a Core API reference page, say MapView's, the Topics pane on the left side of the window will have its tree view expanded to show the core node.  If you scroll up to the top of the tree view and collapse the core node, you'll see that there are a few other nodes in the tree, all component-related, with map-components being one of them.  You can expand the map-components node to access a list of available components.

Click on the Map component to access its documentation.  The top of its page will look similar to a Core API class page, with info on how to import the component depending on whether you're accessing the SDK via ESM or CDN.  One nice aspect of map components, as shown on the Map component page, is that you don't need to import a separate module for each component the way that you must with Core API classes.  You just need to include the single reference to the map components library in your HTML doc's head and you're set to use any map component:
<script type="module" src="https://js.arcgis.com/4.33/map-components/"></script>

Much like a Core API class page, a map component page will include a section detailing its Properties, Methods, and Events.  It will also have a section on the component's Slots (which were discussed in the Calcite part of the lesson). 

The unique part of the component pages is the Demo section, which provides a mini-sandbox for seeing how the component works.  A live preview appears on the left, while a set of controls/properties/attributes appears on the right.  The control default values can be modified and the preview will update accordingly. 

The Map component demo shows a web map of NFL stadiums by default through the setting of the item-id control.  Wipe out that ID (the component will go blank), then assign a basemap setting of satellite (or any other valid basemap you wish).  Feel free to assign values to other controls, such as zoom or center.  (The center control requires a value in a form like -100, 40.) 

After you're done experimenting with the controls, click the Code tab along the top of the Demo GUI.  You should see the HTML code for the custom element you configured and can click the Copy button to copy the code to your clipboard.  Note that the "Control" settings made through the Demo GUI translate to HTML attribute settings.  (Interestingly, I'm seeing an item-id attribute without a string assigned to it after doing the customization I just recommended to you.  While the inclusion of this unset attribute won't hurt anything, it really makes more sense to just omit it if you're not setting it.)

The Demo GUI offers a number of buttons along the top that you're free to experiment with, though I'm not sure that I'd ever find a use for them myself.  There is a Reset controls button near the top of the Controls pane, allowing you to go back to its default settings.  You could also simply reload the documentation page altogether.  

One last point on the Demo sandbox is that the controls it shows will be the component properties that can be set to simple, scalar values (strings, numbers, and Booleans).  If you click on the Properties link to jump down to that section of the component's documentation, you should note that the properties that have something in the Attribute column correspond to the controls available in the Demo sandbox.  But you should keep in mind that those properties without something in the Attribute column are ones that you can set using JS code.  We'll see an example of doing that in the discussion of the Legend component later in this section.

As noted earlier, Esri has deprecated the BasemapToggle widget in favor of the newer component by the same name.  The pen below shows the use of this component.  Note the setting of the position and next-basemap attributes.

  See the Pen   L8_BasemapToggle_component by Jim Detwiler (@jimdetwiler)   on CodePen.

As we saw with the BasemapGallery widget example, in this example a BasemapGallery component is embedded within an Expand component. Note the setting of three attributes on the Expand component. The position attribute is self-explanatory. The mode can be either "floating", as shown here, or "drawer", which causes the basemaps to appear in a box filling much of the bottom of the window. The close-on-esc attribute controls whether the user can close the gallery by pressing the Esc key on the keyboard. As a Boolean attribute, you should simply refer to it by name (i.e., don't say close-on-esc="true") to set the attribute to true or omit it to set it to false.

You can have the gallery displayed when the map loads by setting the Boolean expanded attribute to true.

See the Pen BasemapGallery_component by Jim Detwiler (@jimdetwiler) on CodePen.

The LayerList widget (covered earlier in the lesson) is not labeled as deprecated in the SDK documentation (as of Jul 2025).  Presumably that means the LayerList component lacks some important functionality.  In any case, the example below shows the component embedded within an Expand component, like the BasemapGallery example earlier.  One attribute you might consider setting is visibility-appearance, which allows for showing the user checkboxes for toggling layer visibility rather than the default eyeball icon.

See the Pen LayerList_component by Jim Detwiler (@jimdetwiler) on CodePen.

As with the LayerList widget, Esri has not yet deprecated the Legend widget (as of Jul 2025). The example below demonstrates the use of the newer Legend component, which you should use over the widget unless it doesn't deliver some needed behavior.

See the Pen Legend Demo by Jim Detwiler (@jimdetwiler) on CodePen.

Looking at the code, the component has two attributes set: position and legend-style. The latter defaults to "classic", but can be set to "card" instead. The part of the code to pay particular attention to involves customizing the legend to show only the cities layer. As with the Legend widget covered earlier, the Legend component has a layerInfos property that can be used to specify which layers to depict. Looking at the documentation, you should note that there is no layer-infos attribute; this is sensible since it's not possible to specify the information associated with this property using a simple string. So this example is the first to demonstrate how to set a component property using JS as opposed to setting an attribute using HTML. The key is to use the same querySelector() DOM method that we've seen used to get a reference to the view element, but this time to get a reference to the legend element. With a reference to the element (component), its layerInfos property can be set.

The pen below, modeled after the example for the ScaleBar widget, demonstrates the use of the ScaleBar component. Note that the style and unit are conveniently set using HTML attributes.

See the Pen ScaleBar demo - components by Jim Detwiler (@jimdetwiler) on CodePen.

This concludes the demonstration of map components built into Esri's Maps SDK for JS. There are many others and I recommend you take a few minutes to peruse them in the documentation. Some you may find to be of particular interest include (not an exhaustive list):

• Area Measurement
• Distance Measurement
• Bookmarks: typically used to provide access to spatial bookmarks stored with a web map
• Editor
• Feature Table
• Navigation Toggle: for 3D scene navigation
• Swipe