4.1 Use the SDK 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 SDK.  Thankfully, Esri provides an enormous number of code samples that demonstrate usage of their SDK.  They've also configured their documentation so that the samples can be opened easily in a pair of "sandbox" environments designed for experimentation.  We'll use these sandboxes throughout the rest of the class.

Before diving in to some samples, first a word on the route we'll be taking in learning to use the SDK.  From the beginning of the SDK, it's been possible to build apps using fine-grained object classes like Map, MapView, and SceneView.  Recently, Esri has put a lot of development effort into map components, which are more coarse-grained objects that allow developers to handle the setup of various parts of their apps with less effort.  

We can look at Legos for an analogy.  Given a wide array of brick sizes and types, the sky is the limit in terms of what you can build.  However, there are some frequently built objects, such as vehicles, that would be tedious for Lego builders to build over and over again.  Thus, Lego sets often come with larger parts (like this vehicle base) to simplify the building process.  

Esri's map components are similar in concept and you may notice that the documentation recommends their use to people getting started with the SDK.  Here in Lesson 4, we're instead going to start out using the fine-grained Map, MapView, and SceneView objects found in what Esri calls their "Core API."  We will cover the use of map components, seeing how to handle certain common app elements more easily, at the end of the class in Lesson 8.  On top of the fact that we haven't yet had time to do the kind of big revision to the class that would be required to cover map components right at the start, there are a couple good arguments for leaving the class in its current configuration:

  • Even if you go on to make heavy usage of map components, there is a great deal of functionality that can only be implemented using the Core API.  Getting a bit more practice working with Core API classes and the coding patterns involved should be beneficial.
  • The vast majority of the code base of existing apps written around Esri's Maps SDK for JS still uses a map component-less approach, so it will be good for you to be well versed in that approach.

With that explanation out of the way, let's get started with out first simple 2D app.

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

    Screenshot of the ArcGIS Developers website, highlighting the "Sample Code" tab in the navigation menu for the ArcGIS API for JavaScript.
    Figure 4.1 Accessing the Sample Code area of the ArcGIS Maps SDK for JavaScript
    Image developed by J. Detwiler © Penn State with ArcGIS and licensed under CC BY-NC-SA 4.0

    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.