Overview

Over the rest of this course, we’ll be working with version 4.x of the ArcGIS API for JavaScript. This version represents a major change from the previous one in terms of both coding syntax and what you can do with the API. Probably the biggest upgrade in the API is in the ability to develop 3D apps that run directly in the browser without the need for a plugin. One of the best resources for ArcGIS JS API developers is the API’s software development kit (SDK) found at ArcGIS API for JavaScript. It provides a slew of sample pages that demonstrate how to accomplish various tasks with the API. A good method for learning the API, especially for novice developers, is to find a sample that does something close to what you’d like and modify it to your liking. So we’ll develop our first simple apps by taking that approach.

Objectives

At the successful completion of this lesson, you should be able to:

• import the Esri JS API library into a web page through a content delivery network or downloaded locally;
• understand the role played in Esri's JS API by the Dojo framework;
• describe how Asynchronous Module Declaration (AMD) works;
• understand when to use Esri's main.css vs. view.css files;
• orient yourself to the JS API Software Development Kit (SDK) site js.arcgis.com;
• navigate and interpret the API Reference;
• modify Esri samples in the code sandbox;
• list the most important classes in the API (Map, MapView, SceneView) and describe the relationships between them;
• incorporate web maps like you created in Lesson 1 and web scenes into a JS app;
• navigate a 3D scene;
• set object properties through their constructor or after initialization;
• use autocasting to avoid explicitly importing certain modules

Questions?

If you have any questions now or at any point during this week, please feel free to post them to the Lesson 4 Discussion Forum. (That forum can be accessed at any time by clicking on the Discussions tab.)

Checklist

Lesson 4 is one week in length. (See the Calendar in Canvas for specific due dates.) To finish this lesson, you must complete the activities listed below. You may find it useful to print this page out first so that you can follow along with the directions.

4.1 Use the API to Create Your First 2D Map

As mentioned earlier, modifying existing sample code is a common way to begin learning a new programming language or API.  Thankfully, Esri offers a "sandbox" environment for experimenting with the samples found in their SDK.  Let's use this sandbox to start our work with the API.

1. On the SDK home page, click on the Sample Code tab.
   

   Figure 4.1 Accessing the Sample Code area of the ArcGIS Javascript API SDK
   
   There you should see a list of Get started... samples.
2. Click on the Intro to MapView (2D) link. Like the other Samples pages, you should see a map embedded at the top of the page. Beneath the map, you should see buttons labeled Explore in the sandbox, Open in CodePen, View live and Download ESM sample.
3. Click the Open in CodePen button. CodePen shows you the same map you just saw at the bottom of the page and the source code that produces that map on the top. The size of the "Preview" panel can be adjusted by dragging the horizontal bar separating that panel from the source code panels up or down. The power of CodePen is the ability to modify the source code and quickly see the result.
   
   CodePen is built to encourage the separation of HTML, CSS, and JS code (a good development practice) with separate panels for each.  However, note that it's OK to include CSS and JS in with the HTML, which is what happens when you open an Esri sample in CodePen.  
   
   Also note that it's possible to reconfigure CodePen such that the code panels are on the left or right rather than on the top.  (I prefer having them on the left and the Preview panel on the right.)  Making this change is done by clicking the Change View button (found next to the Settings button).
   
   The sample is coded so that the map is centered over Scandinavia at a zoom level of 4. What if you wanted to display the United States instead? That’s easy!
4. Modify line 30 (or thereabouts - as the documentation does occasionally get updated) so that the MapView’s center property is set to a lon/lat array of [-95, 40].  You should see that the Preview panel automatically updates as you edit the code.  I find this to be annoying when working on map pages, so I go into Settings > Behavior, and toggle the Auto-Updating Preview setting to off.  When making this setting, you'll need to click the Run button to see the result of your code changes.
   
   Now, let’s say you wanted to use a different basemap.
5. Change line 23 so that the Map’s basemap property is set to "terrain" and again click the Run button. As you can see, the CodePen sandbox makes it very convenient to “play around” with the code samples.
   
   Note: We’ll see shortly how you’d know what other values can be used to set the basemap property.

4.2 Use the API to Create Your First 3D Map

An exciting feature of version 4 of Esri's JavaScript API is its support for 3D scenes. Let’s have a look at a basic 3D sample.

1. Go back to the Sample Code Overview page and click on the Intro to SceneView (3D) link.
2. Using the same approach that you used for the 2D map, view the sample code in the CodePen sandbox and change the map’s center to the same coordinates and the scale to 4000000.

Note: Most of you have probably explored a 3D map like this one, though you may not be aware of all of the navigation options available to you. Read about the various mouse and keyboard controls and their associated effects in the documentation of the SceneView class, and be sure to try them out!

Also note that in addition to the Open in CodePen option, the sample pages also offer an Explore in the sandbox option.  This is Esri's own sandbox for experimenting with their samples, much like CodePen.

4.3 Separate Your HTML, CSS and JS Source Code Using CodePen

The samples in the SDK are written with the CSS and JavaScript code embedded within the HTML code. This is fine for simple apps, but for more complex apps it is recommended that you write the CSS and JavaScript in separate files. Among the benefits to this approach are:

• improved organization, making it easier to find your CSS or JS code rather than having to hunt in your HTML code for it;
• the ability to reuse code that is applicable across projects;
• shorter page load time through caching of the external files; and
• the ability to “minify” the code, making it a smaller download for client devices.

Let's revisit the Intro to MapView (2D) sample in CodePen, looking to follow a code separation approach.  

1. Return to CodePen.  (Here's the CodePen homepage if you no longer have the earlier samples open.)
2. If you don’t yet have a CodePen account, click the Sign Up button and supply the info needed to establish a free account.
   
   After signing up, your browser window should open up to a new Pen (environment for authoring a new web page).
3. Click the Change View button in the upper right and select your preferred Editor Layout option.
4. Click the Save button. This will give your pen a randomly generated name (in the upper left).
5. Click on the pencil icon to the right of the pen name and assign it a new name of hello_map.
6. Go back to the Intro to MapView (2D) sample sandbox. Copy and Paste the three components of the sample into their respective panels in CodePen. Note the following:
   - You should omit the DOCTYPE declaration from the HTML piece.
   - Do not include the style and script tags surrounding the CSS and JS code, respectively.
   - Make sure that the <script src=....></script> tag is in the HTML window
   - You may find it most convenient to copy the complete sample (CSS and JS included) to the HTML panel, then cut and paste the CSS and JS pieces to their respective panels. (You can remove the empty style and script elements from your HTML when done.)
   - The code panels are resizable; if you’ve set the Editor Layout such that the code panels are arranged vertically to the side of the Preview panel, note that you can double-click on any of the panel headings to maximize that panel.

4.4 Move Your Code to .html, .css, .js files

Playgrounds like Esri’s JS SDK sandbox and CodePen are great tools for experimenting with samples and developing your own apps from scratch, but when you want to “go live” with an app so that others can use it, you’ll want to host your code on a web server. You used a web hosting service in the previous lesson and we’re going to use that service again now.

When building apps, a convention that many developers follow is to create a folder on the web server for their site/app and into that folder place an HTML file called index.html (or default.html). For example, in building my “app_to_end_all_apps” site, I’d create a sub-folder by that name in my www folder, then upload my app’s HTML markup in a file named index.html to that sub-folder. I could then view my app using the URL: http://detwilergeog863.000webhostapp.com/app_to_end_all_apps/. (Note: This app doesn't actually exist, so you should expect a File Not Found error if you follow the link.) I could omit the index.html from the URL since browsers are built to look for a file by that name when the URL ends in a folder.

1. On your computer, wherever you’re storing your coursework, create a folder called hello_map. (The name for this app is a play on computer programming's "Hello, World" tradition.)
2. Create a new blank text file, copy your HTML code from CodePen into that file, and save it as index.html in your hello_map folder. Be sure to add a <!DOCTYPE html> line at the top of the file to declare your code as HTML 5.
3. Create another blank text file, copy your CSS code into that file, and save it as main.css, again in the hello_map folder.
4. Finally, create a third text file for your JS code. Call it main.js.
   
   Unlike the CodePen environment, the end user’s browser won’t know that there is a CSS file and a JS file that goes along with the HTML file unless you tell it.
5. To reference your CSS code, add the following line above the line that references Esri’s main.css stylesheet:

   <link rel="stylesheet" href="main.css"></link>

6. To reference your JS code, add the following line after the line that references Esri’s JS API:

   <script src="main.js"></script>

   Note: These references use relative paths to locate the files; the browser will look for the files in the same folder as the HTML file since no folders were included in the paths. Because the architecture of this app is not particularly complicated, I’m directing you to store all of the files together. But you should keep in mind that many developers prefer to store their files in sub-folders (e.g., css/, js/ or styles/, scripts/) for organizational reasons.
7. Open this local copy of your app in a browser (right-click on the file in Windows Explorer and select Open with). As you develop your app, you can leave it open in your browser and Refresh (F5) whenever you want to see the result of your changes.
8. To publish your app to a public facing location, open a connection to your www space on the 000webhost web server (using either FileZilla or the 000webspace File Explorer).
9. Replicate the directory structure you have locally by creating a folder called hello_map.
10. Upload the three files associated with the app to that folder.
11. Test the app by pointing your browser to surnamegeog863.000webhostapp.com/hello_map, replacing surnamegeog863 with your website name.

For extra practice, go through the process of copying the 3D sample code to CodePen and then create a site called hello_scene in your web space.

4.5 Dissecting the Esri Samples

Now that you’ve had a chance to dive right into building your own map apps, it’s time to learn more about what’s happening in those apps before you can go further with the API. Let's examine these start-up pages and discuss their HTML, CSS and JS pieces, beginning with the HTML of the 2D sample. Be sure to open up each of the three files so you can follow along with the discussion.

4.6 Maps, Scenes and Views

We’ve already been exposed to the Map, MapView and SceneView classes in experimenting with and discussing the Esri samples. Now, let’s learn some more about these fundamental classes.

In version 4.x of Esri’s API, the Map class is used to store a basemap and layers. The actual rendering of the Map on the page is done through the use of a View: either a MapView (2D) or a SceneView (3D). If you look back at the two samples we’ve been working with, you’ll note that a Map object is created and its basemap property set in both cases. The only difference is that in the 3D example, the Map’s ground property is set in addition to its basemap. Setting the ground property renders the map such that the underlying terrain can be seen. The property can be set to “world-elevation” to use Esri’s default world elevation service, but it is also possible to use other elevation layers. (Setting the ground property in a Map that is displayed in a MapView has no effect since the MapView class only renders Maps in 2D.)

The other commonly used property of the Map class is its layers property. We’ll look at adding layers to a map in depth later in the course.

Looking at the documentation of the MapView class, you’ll see that it contains a whole host of properties. The most commonly set MapView properties include:

• map: set to an object of the Map class
• container: set to a string matching the id of an element on the page (or to a reference to the element itself)
• center: set to an object of the Point class
• zoom: set to a number, typically ranging from 3 (small scale)-18 (large scale)
• rotation: set to a number ranging from 0 to 360 degrees to rotate due North

Note that while center and zoom are commonly used to specify the part of the Map that’s currently visible, it’s also possible to do so using the extent and/or scale properties. Take care that you’re setting these properties logically. As explained in the documentation, if both the zoom and scale are set, then the scale setting will override the zoom setting. Similarly, an extent setting will override any center, zoom or scale setting.

3D SceneViews have the same set of properties as listed above, with the exception of rotation.

While it’s typical for a page to contain just a single View, you should keep in mind that you’re not limited to that sort of layout. It is sometimes useful to employ multiple views on the page, as in this sample that contains both a MapView and a SceneView.

4.7 Adding Overlays to a View

The maps we’ve created so far have been pretty boring, so let's spice it up a tiny bit by plotting a point. We’ll see later in the course how to display features stored in one of Esri’s vector data formats. What I’m talking about doing right now is how you’d display a small number of geometries (points, lines or polygons) whose coordinates you’ve hard coded into the app, or perhaps acquired through user input.

1. Create a copy of your hello_map folder (and its files) called lesson 4.
2. Set the HTML doc’s title to Plotting a point.
   
   Adding geometries the way I’m describing here involves creating one or more objects of the Graphic class.
3. Look up the Graphic class in the SDK using the Search box. (The result you want is the class found in the esri/Graphic module.)
   
   As the overview explains, important properties of the Graphic class are geometry, symbol, and attributes. Attributes are important in situations where you want the user to be able to click on the graphic and see information about it in a popup window. We’re going to keep this simple, so we’ll focus on just the geometry and symbol, starting with the geometry.
   
   Looking at the geometry property's description, you should note that in order to set it, you need to use a Geometry object.
4. Click on the Geometry link to go to that class's documentation page.
   

   Figure 4.3 The Geometry class description in the API Reference
   
   Its description tells you that it’s a "base class" and that it has no constructor. What this means is that you can’t create a plain Geometry object. You’d have to create a Point, Polyline or Polygon object instead. The Geometry class exists in the abstract as a way to define the properties and methods that the Point, Polyline and Polygon classes share in common (such as the extent property). (You might find it helpful to think of cars as an analogy. If you’re shopping for a new set of wheels, you don’t just buy a generic car; you buy some model of Ford, Toyota, Volkswagen, etc.)
   
   In object-oriented programming terminology, the Geometry class can be described as the parent class or super-class of the Point, Polyline and Polygon classes (which are themselves child classes or sub-classes). These class relationships are conveyed at the very top of the class pages in the SDK.  (Look for the Inheritance and Subclasses headings.) It turns out that you’ll find all of the properties and methods the Point, Polyline and Polygon classes inherit from Geometry on their pages. Not all SDKs are written this way (i.e., the SDK could have been organized such that you’d have to view the property and method lists on both the Point and Geometry pages to know all Point capabilities).
5. Getting back to our task, we know we want to add a point to the map, so follow the link to the Point class.
   
   The Point class has several properties, but the ones we want here are latitude and longitude.
6. To the bottom of your JS code, add the following:

   const pt = new Point({
     latitude: 40.792,
     longitude: -77.871 
   });

   We’ve created a Point geometry for our Graphic, but have we forgotten something? Yes, if we want to work with the Point class, we need to include a reference to its module in our require() declaration.
7. Move to the top of your JS code and add "esri/geometry/Point" to the module list, then add Point to the callback function argument list (making sure you match its location in the list with the module’s location in the module list).
8. With the Point geometry created, let’s move on to the symbol. In the SDK, make your way back to the Graphic class’s property list.
   
   The symbol property must be set using a Symbol object. Following the Symbol link, you should note that, like the Geometry class, Symbol is an abstract parent class for several child classes. We’re trying to symbolize a Point here, so the subclass we need is MarkerSymbol. (We’d need LineSymbol for a Polyline and FillSymbol for a Polygon.)
9. Follow the MarkerSymbol link in the list of subclasses.
   

   Figure 4.4 Accessing the MarkerSymbol class in the API Reference
   Reading over the MarkerSymbol class description, you should note that it is itself another abstract parent class, having subclasses PictureMarkerSymbol and SimpleMarkerSymbol. If you wanted to depict the point using some kind of graphic stored on disk, then you’d use the PictureMarkerSymbol class. We’ll keep our app simple by using the SimpleMarkerSymbol class, which will allow us to choose from a set of predefined shapes and apply a desired color and size.
10. Follow the SimpleMarkerSymbol link in the list of subclasses. Read over the class description and note the color, size and style properties.
11. Create a new SimpleMarker as follows:

    const sym = new SimpleMarkerSymbol({
      color: "blue",
      style: "square",
      size: 12
    });

12. Update your require() declaration so that this newly added SimpleMarkerSymbol code will execute properly. Hint: the information you need is at the top of the class page in the SDK.
13. With the geometry and symbol created, we’re ready to create a new Graphic object:

    const ptGraphic = new Graphic({
      geometry:pt,
      symbol:sym
    });

14. We saw earlier in the lesson that the Map class has a method called add() for adding a layer. One way we could accomplish our goal here would be to add this Graphic to a new GraphicsLayer, then add the GraphicsLayer to our Map. However, a slightly easier alternative is to take advantage of the fact that the MapView has a graphics collection associated with it. We can simply add our Graphic to that collection as follows:

    view.graphics.add(ptGraphic);

15. Be sure to modify your require() declaration so that the browser will be able to find the Graphic class you just referenced.
16. Test your app and confirm that a blue square is added to the map.

With that, you've reached the end of this lesson's content.  Move on to the next page to access the assignment associated with this lesson.

Assignment: Plot Your Hometown

The coding assignment for this lesson is in three parts.  Here are some instructions for completing the assignment.

Part I

In an earlier course in our curriculum, you may have learned about the United States Geological Survey's Geographic Names Information System and the Getty Thesaurus of Geographic Names (for places outside the U.S.). Use those tools or any other resources at your disposal to locate the latitude/longitude coordinates of your hometown.  (One handy way to get a location's coordinates is to pull it up in Google Maps, right-click on the location and select What's Here?)

Modify the lesson4 app code from earlier in the lesson so that the map is centered on and a marker points to your hometown. The easiest approach to this problem would be to insert your hometown coordinates in both lines of the script where coordinates are found. However, I hope you'll recognize that repeating values in different parts of a program is generally a bad practice because of situations like this where you end up having to make revisions in multiple places. So, while you're changing the location displayed on the map, revise the code so that it is as efficient as possible.

Part II

As you know, one way that web maps convey information to the user is through popup windows.  We saw in Lesson 1 that layers can have popups configured using GUI-based tools in ArcGIS Online.  In the next lesson, we'll see how the API makes it possible to easily incorporate layers and maps configured in ArcGIS Online into an app.  And later we'll see how to configure layer popups programmatically.  In this lesson, we've dealt with graphics, which don't have an attribute table associated with them.  However, it's still possible to code the display of popups when the user clicks on a graphic.

For Part II, I'd like you to create a copy of the app from Part I and modify it so that clicking on a town marker will display some information about it (e.g., its name, population, when it was established, etc.).  We haven't covered how to do this, but it is something that's demonstrated in an Esri code sample.  You might be tempted to search the Sample Code area of the SDK for "popups," but all of the samples with that tag involve data layers rather than graphics.  The sample I'm thinking of can be found under Graphics in the list of Sample Code categories.  

Part III

Create a pen in CodePen that contains your code from either Part I or Part II (your choice). 

Deliverables

This project is one week in length. Please refer to the Canvas course Calendar for the due date.

1. Post the app containing your hometown map to your e-portfolio. (30 of 100 points)
2. Post the app that displays popup info for your hometown to your e-portfolio. (30 of 100 points)
3. Provide a link to your CodePen map -- or embed the pen itself -- in your e-portfolio. (20 of 100 points)
4. Below one of your maps (or on your e-portfolio index page), include some reflection on what you learned from the lesson and/or any concepts that you found to be confusing (minimum 200 words). (20 of 100 points)
5. Click on the Assignment 4 Submission to submit a link to your project page. (A link to your e-portfolio index page is OK too if it contains a link to your project.)
6. Complete the Lesson 4 quiz.

Note: The examples you've seen so far are all likely to have shown the div element used to display the map/scene filling the whole browser window.  You could add your reflection text beneath that div, but the map would still fill the whole window and it may not be immediately clear to the viewer that there was content below the map.  It's probably a better idea to shrink the height of the map div to something less than 100%.  If you're unsure how to go about this, here is an example that demonstrates one approach to including text on the page with the map.

Summary and Final Tasks

In this lesson, you built your first apps using Esri's JavaScript API. Even the simple map that you created involves a number of different technologies (HTML, CSS,  JavaScript, the Document Object Model, and the Dojo JavaScript framework) and it is important that you have a firm understanding of this material before moving on. If you skipped over the w3schools tutorials referenced in the lesson, be sure to go back and complete them.  You might also use any free study time to work through other JavaScript references such as the ones recommended in the syllabus.

In Lesson 5, you'll see how to spice up the rather dull product of Lesson 4 by adding data layers.  You'll also learn about a number of coding tools and strategies that will help you as a JavaScript developer.