Lesson 3: Introduction to the ArcGIS API for JavaScript

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 js.arcgis.com. 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 3 Discussion Forum. (That forum can be accessed at any time by clicking on the Discussions tab within Canvas.)

Checklist

Lesson 3 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.

Steps to Completing Lesson 3
Step Activity Access/Directions
1 Work through Lesson 3. You are in the Lesson 3 online content now. The Overview page is previous to this page, and you are on the Checklist page right now.
2 Complete the two-part "Plot Your Hometown" project. On your e-portfolio index page:
 
  • Post links to your two hometown maps.
  • Include some reflection on what you learned from the lesson and/or any concepts that you found to be confusing (minimum 200 words).
Follow the directions throughout the lesson and on the "Plot Your Hometown" page.
3 Take Quiz 3 after you read the online content. Go to the Canvas Homepage and click on the "Lesson 3 Quiz" link to begin the quiz.

3.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.
    Accessing the Sample Code area of the 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, JS Bin, and View live.
  3. Click the Explore in the sandbox button. The sandbox shows you the same map you just saw on the right side of the page and the source code that produces that map on the left. The size of these two panels can be adjusted by dragging the vertical bar separating them to the left or right. The power of the sandbox is the ability to modify the source code and quickly see the result (by clicking the Refresh button in the upper right of the page).

    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 36 so that the MapView’s center property is set to a lon/lat array of [-95, 40] and click the Refresh button. Now, let’s say you wanted to use a different basemap.
  5. Change line 29 so that the Map’s basemap property is set to "terrain" and again click the Refresh button. As you can see, the 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.

3.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 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!

3.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;
  • the ability to “minify” the code, making it a smaller download for client devices.

Some sites offer sandboxes in which each of the three-page components is in its own box (e.g., jsFiddle, CodePen). In order to encourage you to follow this code separation approach, let’s have a look at one of these sites.

  1. Go to the CodePen homepage.
  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 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 boxes 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.
    - You may find it most convenient to copy the complete sample (CSS and JS included) to the HTML box, then cut and paste the CSS and JS pieces to their respective boxes. (You can remove the empty style and script elements from your HTML when done.)
    - The code boxes are resizable; if you’ve set the Editor Layout such that the code boxes are arranged vertically to the side of the output box, note that you can double-click on any of the box headings to maximize that box.
    - The output box will update itself immediately after you make a change by default. You can override this behavior by going to Settings > Behavior and unchecking the ENABLED checkbox under the Auto-Updating Preview heading. This will add a Run button to your interface.

3.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 Penn State’s 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://www.personal.psu.edu/jed124/app_to_end_all_apps/. 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 www.personal.psu.edu web server (using either FileZilla or the PASS 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 www.personal.psu.edu/xyz123/hello_map, replacing xyz123 with your PSU access account ID.

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 PSU web space.

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

3.5.1 The HTML

After completing the previous lesson, you should recognize the <html>, <head> and <body> tags. You should also recognize that the <!DOCTYPE> directive declares that the document is written as HTML 5.

The <head> of the document contains two <meta> elements. The second of these is concerned with rendering the document in a user-friendly way across a variety of devices (part of the larger CSS topic of responsive web design). This is not critical for you to worry about now, but you may want to return to this topic if you are developing for mobile phones or tablets. The first meta element specifies that your document is encoded in the UTF-8 character set, one that supports all of the world's major languages. It's a good idea to include this line verbatim in all of your map pages. If you're an insomniac, you may want to read more about character encoding.

The <head> also contains the page’s title, links to two external stylesheets (your own main.css file and Esri’s main.css file), and two script elements (one referencing the Esri JS API and the other your local main.js file). We’ll discuss the CSS and JS source code in detail shortly.

Note: Have a look at the Default Stylesheets section of the SDK Guide page on Styling. For most of the term, we’ll be implementing “a basic map with the default widgets,” so you can reduce the amount of data that must be downloaded to the client device by linking to Esri’s view.css stylesheet rather than main.css.

Next in the HTML file comes the body of the document, in which the only thing you'll find is a div element. div elements are used to create divisions, or sections, in a document. In a web mapping context, a div is typically used as the container for the page's map. Note that this div is assigned an id (viewDiv).

3.5.2 The CSS

Looking at your main.css file, there are three elements being styled: the html element, its child body element, and the element having the id of viewDiv (indicated by the pound sign). Each element has four property settings applied to it. The height and width settings specify that the element should take up all of the space of its parent container. The padding and margin settings specify that there should be no white space inserted on the inside or outside of the element, respectively. Basically, these styles produce a map filling the entire browser window.

3.5.3 The JS

Learn More

At this point, you should familiarize yourself with the syntax of JavaScript (JS). The w3schools site offers a good hands-on JavaScript tutorial that should do the job. Take a couple of hours to work through the topics listed under the JS Tutorial heading and pay particular attention to the following points:

  • Ending statements with a semicolon is optional. (The Esri samples use them.)
  • Note the difference between placing scripts inside the page's head section and its body section.
  • JavaScript is a dynamically typed language; you do not need to specify a data type when declaring a variable.
  • JavaScript variables are case sensitive.
  • Variables can be initialized on the same line that they are declared.
  • Code associated with a conditional statement (if or else statements) or a loop (for or while) must be enclosed in braces.
  • Alert boxes can be used to debug scripts that aren't working properly.
  • JS functions are reusable blocks of code with an optional return value.
  • The backslash (\) can be used to insert special characters in a string (e.g., if you want a string enclosed in double quotes to also contain a double quote).
  • Comments are signaled in JS using two slashes (//).

Now that you've learned a bit about JavaScript, we can examine what’s happening in the main.js file.

AMD

The first thing you should notice is that all of the code is wrapped inside a require() function. This is a result of the fact that Esri’s API is built around a JS toolkit called Dojo. Dojo uses a design pattern called Asynchronous Module Definition (AMD) to load JS resources into memory. By defining their API’s object classes in modules, Esri’s made those classes easier to maintain and re-use. Loading the modules asynchronously (in parallel rather than one at a time) means that apps built on the API will load faster than they would in a non-AMD framework. One of your recurring tasks as an Esri JS developer will be to identify the modules containing the object classes needed by your app.

In the case of the 2D sample, two Esri classes are needed: Map and MapView. These classes are accessed by loading the esri/Map and esri/views/MapView modules, respectively.

The DOM

A third module, called domReady! is also loaded. This module is built into Dojo and is used to specify that none of the code that follows should be executed until the DOM has finished loading. What is the DOM, you might be asking? DOM stands for Document Object Model, which is a tree-like representation of a web page that the browser creates whenever it loads that page. The DOM provides the means for JS developers to manipulate a page’s contents and behavior programmatically. In the case of developing an Esri JS app, the DOM is needed to insert a map or scene onto the page.

Learn More

Once again, the w3schools site offers a good JavaScript HTML DOM tutorial. This short tutorial should only take you 30-60 minutes to complete.

The list of modules at the beginning of the require() function is then followed up by an anonymous callback function. The function is anonymous, in that it has no name. It’s a “callback” function because it’s being used in conjunction with the domReady! module, which tells the browser that it shouldn’t execute the code within the function right away; it should “call back” to it when the DOM is finished loading.

The callback function contains a list of arguments that corresponds to the list of required modules. In the 2D example, only the esri/Map and esri/views/MapView modules are required, so the only arguments to the callback function are Map and MapView. We’ll see other arguments associated with other modules in more complex examples later. Some notes on the callback function arguments:

  • You should not include one to go along with the domReady! plugin.
  • They can be named anything you like, though the accepted practice is to name them the same as their corresponding modules.
  • It is critical that the arguments be listed in the same order as the modules.

Using the API Reference

Earlier in the lesson, we visited the Esri JS API SDK to locate sample code that could be used to create our first apps. Now, let’s have a look at an equally important part of the SDK: the API Reference. The API Reference contains a list of all the API modules down the left side of the page. Each module heading can be expanded to see the classes defined in that module. For example, we’d find the Map class in the esri module and the MapView class in the esri/views module.

Locating the map class in the API Reference

On the right side of the API Reference index page is a list of commonly used classes, generally organized from top to bottom in order of importance. We’ll cover most of these classes over the course of the term.

The first line of JS code in our 2D sample creates an object of the Map class (new Map). We can learn about that class by clicking the Map link on the API Reference index page or by entering Map into the Search API Reference box.

Like the other class description pages in the API Reference, the page for the Map class conveys a lot of useful information:

  • how you’d go about referencing the class in your code’s require() declaration
  • an overview of the class (what it’s used for, a code snippet showing its usage, and links to samples and related classes)
  • the class’s constructors (more on this shortly)
  • the class’s properties (characteristics that uniquely define Map objects)
  • the class’s methods (actions that the Map class is programmed to perform)

The Properties section of the page includes an Overview, listing all of the properties in alphabetical order along with their type (e.g., String, Number, or some object class). The property type is important to know as it tells you what you can expect to get back if you read the property (or conversely, what you need to supply if you’re setting the property). After the Overview, you’ll find a section of Details, providing more specifics on the class’s properties. For example, the details on the basemap property provide a list of acceptable values, along with a thumbnail of each.

The Methods section likewise includes both an Overview and Details section. Method parameters (pieces of information the method uses in performing its action) are listed in parentheses after the name in the Details section. If a parameter is optional, it will be listed with a question mark next to it. If a method returns a value when it is called, the method parameters will be followed by an arrow symbol pointing to the return type. Looking at the Map class methods, the add() method has a required parameter (I believe this should say layer, singular), an optional parameter (index, specifying the position in the Map’s layer collection where you want the layer to appear), and no return value. The findLayerById() method has a required layerId parameter and it returns a reference to a Layer object. Note that when a parameter or return value is an object, it will appear in the documentation as a link. This helps you to navigate through the SDK as you write your code.

The part of the class documentation that we glossed over was the Constructor section. This section is intended to provide guidance on how to create a new object of the class. This is done by using the word new followed by the name of the class and a set of parentheses. In some APIs (including version 3.x of Esri’s JS API), it is possible to set certain properties of the object you’re creating as part of the constructor statement, making it important to consult the Constructor section of the class’s documentation. However, in version 4.x, any of the class’s properties can be set as part of the constructor, which is why you’ll note that the Map class constructor says simply properties? within the parentheses.

Whatever properties you decide to set in the constructor should be expressed as a JS object literal, a term that may seem intimidating, but is actually not too difficult to grasp. Object literals are basically a list of property-value pairs, in which the list is enclosed in curly braces and the property-value pairs are separated by commas. In the case of the 2D sample, the Map was constructed with just a single property-value setting (the basemap), whereas in the 3D sample, it was constructed with two property-value settings (the basemap and the ground).

Note that you need not set all properties as part of the constructor. For example, I could rewrite the 2D sample as follows:

var map = new Map();
map.basemap = "streets";

Or the 3D sample as follows:

var map = new Map({
  basemap: "streets"
});
map.ground = "world-elevation";

One last word on constructors... When creating an object, you’re typically doing so because you need it later in your script. Thus, you will usually store a reference to the object you’re creating in a variable. In the samples, the new Map object was stored in a variable called map. That variable was later used to set the map property of a MapView object. Having multiple entities in a script with the same name can be confusing, especially for beginners, so I like to assign variable names that don’t duplicate the name of a class or property. In this case, I might use myMap or theMap. Keep in mind though that this means updating other statements in which that variable is referenced:

require([
  "esri/Map",
  "esri/views/MapView",
  "dojo/domReady!"
], function(Map, MapView) {
  var myMap = new Map({
    basemap: "streets"
  });
  var myView = new MapView({
    container: "viewDiv",
    map: myMap,
    zoom: 4,
    center: [15, 65]
  });
});

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

3.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 lesson3.
  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.
    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., to know everything a Point can do, you’d have to view the property and method lists on both the Point and Geometry pages).
  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:
    var 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 (just before domReady! is a logical place), 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, the Symbol class 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.
    Access 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:
    var 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:
    var 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 two 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 lesson3 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.  

Deliverables

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

  1. Post the app containing your hometown map to your e-portfolio. (40 of 100 points)
  2. Post the app that displays popup info for your hometown to your e-portfolio. (40 of 100 points)
  3. Below the map, 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)
  4. Click on the Assignment 3 Submission link in Canvas 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.)
  5. Complete the Lesson 3 quiz.

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 4, you'll see how to spice up the rather dull product of Lesson 3 by adding data layers.  You'll also learn about a number of coding tools and strategies that will help you as a JavaScript developer.