8.1.1 BasemapToggle

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.

The four steps are annotated in the code sample below:

const map = new Map({
 basemap: "topo-vector" // STEP 1
});

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

const toggle = new BasemapToggle({
 view: view, // STEP 2
 nextBasemap: "hybrid" // STEP 3
});

view.ui.add(toggle, "top-right"); // STEP 4

8.1.2 BasemapGallery

This widget provides the user a set of basemap options (with thumbnail previews) to choose from. The simplest implementation, as seen in this sample [1] involves creating a BasemapGallery object, associating it with the appropriate View, and adding it to the desired position in the UI.

8.1.3 Custom Basemaps

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 [2], 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,  [3]a cartography and visualization company based in San Francisco, and delivered in partnership with Stadia [4], 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:

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 [8](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

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. This sample demonstrates the Home widget [9].

8.1.5 LayerList

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. This is another widget that is straightforward to implement, so I'll again refer you to an Esri sample of the LayerList widget [10].

8.1.6 Legend

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

Customized legend

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 [13] 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

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", "non-metric" or "dual". The style property can be set to "ruler" or "line". Here's an example that shows a map with two ScaleBar widgets:

The only difference I can see between the two styles is that the ruler style has the labels appear above the line while the line style has them below the line. The Esri ScaleBar sample [15] shows that setting the unit to dual will produce a line with the metric label on top and the non-metric label on bottom.

8.2.1 Checkbox

This Esri sample [17] 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 [18] 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 [19] 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.

8.2.2 Dropdown List

As you saw in the w3schools tutorial, a dropdown list is created in HTML using a select element. This Esri sample [20] 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.).

The logic behind the display of the selected floor’s features is pretty clever. A forEach() loop is used to iterate through each of the layers in the scene. The entire "Building Wireframe" layer is meant to always be visible, so line 141 basically says to ignore that layer. For all other layers, the definitionExpression property (discussed in Lesson 6) is modified to show just the features from the selected floor.

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.

8.2.3 Button

The next sample [21] 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.

8.2.4 Text Box

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.

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 [23].
• Line 30 of the JS 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 37.  
• The storm name is then incorporated into a definitionExpression applied to the FeatureLayer that was created earlier in the code.

8.2.5 Range Slider

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" [24], 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 [25], which was introduced at v4.12 of Esri's API.  

Initial setup

Two divs are defined in the HTML on lines 25 and 27 of the HTML to serve as placeholders for the two Slider widgets.  The widget objects themselves are created early in the JS code, on lines 25-53.  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 224-226, which specifies that a click on the button should trigger execution of a function called queryEarthquakes(). That function (which begins on line 228) 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.  

8.2.6 Date

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:

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.)

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 [39] 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 references to your HTML, above the references to the JS API:

       <script src="https://js.arcgis.com/calcite-components/2.6.0/calcite.esm.js" type="module"></script>   
       <link rel="stylesheet" href="https://js.arcgis.com/calcite-components/2.6.0/calcite.css" /

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 [38] 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 window and add a reference to the LayerList module:

       require(["esri/views/MapView", "esri/WebMap", "esri/widgets/LayerList"],
   	  (MapView, WebMap, LayerList)

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 require callback function):

     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 here:
   https://www.w3schools.com/js/js_string_templates.asp [40]
   
   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:
   https://www.w3schools.com/jsref/met_document_queryselector.asp [41]
   
   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):

       require(["esri/views/MapView", "esri/WebMap", "esri/widgets/LayerList", “esri/widgets/BasemapGallery”],
           (MapView, WebMap, LayerList, BasemapGallery)

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:

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:

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 [44] component. This component is demonstrated in the CodePen below:

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 [46] component.  The heading property is set to show the Wildfire Viewer text at the top of the panel.  Next comes a Block [47] 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 [48] 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.

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 [50] and Button [51] components in a modification of the mountain peak filtering sample we saw earlier:

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 attribute settings for each calcite-combobox, note that the settings are made in the JS block, at the beginning of the require() callback function.  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 [53] to see some of the other UI elements that are available. Here are a few that are particularly useful, in my opinion:

• Accordion [54]
• Menu [55]
• Tree [56]
• Color Picker [57]
• Dropdown [58]
• Progress [59]

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.