8.2.1 Checkbox

This Esri sample [2] 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 [3] 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 [4] 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 [5] 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 [6] 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 [10].
• 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" [11], 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 [12], 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.)