Tutorial for ArcGIS web mapping API for JavaScript (ESRI)

[Editor's note: This tutorial from ESRI walks the user thru a short project using the new ArcGIS web mapping API for Javascript.]

Republished from ESRI ArcUser magazine.
Winter 2009. View code snippits.
List of sites using ArcGIS API for Javascript.

Add a Map to a Web Page in Three Simple Steps
Getting started with the ArcGIS API for JavaScript

By Bronwyn Agrios, ESRI Education Services

Giving a wider audience access to your geographic data and maps through a Web page is almost effortless when you embed a simple map into a new or existing Web site using the ArcGIS API for JavaScript. Although ArcGIS Server provides many methods for adding a spatial component to a Web site, the ArcGIS API for JavaScript lets you use ArcGIS Server services to build lightweight, high-performance, pure browser GIS applications. ArcGIS API for JavaScript is hosted by ESRI and free to use. There are no licensing or service fees associated with its use.

Use the ArcGIS API for JavaScript to embed a map or perform a task such as querying spatial data in your Web application. The best way to get started using the ArcGIS API for JavaScript is to use the application samples and services provided by ESRI. If needed, you can modify these samples to include your own services and custom functionality in a mashup that incorporates multiple layers and functionalities in a single application.

This tutorial shows you how to access ArcGIS Online services through a simple Web application created using the JavaScript API. ArcGIS Online is a family of Web-based services and resources that lets you populate applications with base data hosted by ESRI and access tasks. In this exercise, you will be using only spatial content from ArcGIS Online in a JavaScript API application so you won’t even need to set up and maintain an installation of ArcGIS Server.

The Flagler County Property Appraiser Web site used the ArcGIS API for JavaScript to create an application that helps citizens find real property information including land, building, assessed, and taxable values.

Step 1

Embedding a Hosted Map in a New Web Page To create a Web page that contains an embedded map from a hosted service, you do not need to have ArcGIS Server installed or possess mapmaking or programming skills.

The following section will help familiarize you with the ArcGIS API for JavaScript samples on the ArcGIS Server Resource Center that you can use to create this page.

ArcGIS Resource Centers provide you with one-stop access to help resources, blogs, communities, and other information on all ArcGIS products. Navigate to resources.esri.com and select ArcGIS Server or any other
products. To learn more about the available samples, you will make a local copy of some sample JavaScript code and make it available through a new hosted Web page using the following steps:

  1. Open a Web browser and navigate to resources.esri.com/javascript.
  2. On the Home tab, click Concepts and Getting Started, located under Using the JavaScript API. Under Concepts, click Getting Started, and choose the topic Adding a map.
  3. Click the Show Me link at the top of the help topic. A new browser will open with a new JavaScript API map containing an ArcGIS Server service coming from ArcGIS Online.
  4. Now view the source of the Web page. Right-click anywhere on the Web page (except the map) and choose View Source if you are using Internet Explorer or choose View Page Source if you are using Firefox. A new window will open displaying the HTML code for this page.
  5. Copy the HTML code into a text editor such as Notepad. Save it as an HTML file (.html) locally on your computer.
  6. Before closing the text editor, go to line 16, find the following lines of JavaScript, and note the sections in bold.esri.layers.ArcGISTiledMapServiceLayer (server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer)(Note: You may need to turn off Word Wrap in Notepad to make the Go To function available.) You can see that the ESRI_StreetMap_World_2D service coming from an ArcGIS Online server is being referenced in the map using its URL. When you have finished, close the text editor.
  7. Double click the new HTML file to open it and verify that you can see and use the map from this file. (You may need to tell the browser to allow blocked content to display.) If you are able to see the map, you have successfully created an HTML file that references an ArcGIS Online service. Go to resources.esri.com/javascript, click Samples, and select the first Watch a Video link to watch a video that leads you through these steps.

Use the JavaScript API samples to get started building your own simple Web mapping applications.

Each sample page contains a live demo, a description of what happens in the sample, and the source code.

Step 2

Making the Map Available on the Web To make this file available over the Web, you need to move it to a Web server. If you have access to a Web server (Microsoft’s IIS, for example), move the file to the directory of the Web server (e.g., C:\inetput\wwwroot\MyWebMap.html). If you don’t have a Web server, upload your HTML file to a free hosting site such as Yahoo! GeoCities at geocities.yahoo.com. Use the following steps to create a GeoCities site and upload your HTML document.

  1. Navigate to geocities.yahoo.com/ and click Sign Up.
  2. If you already have a Yahoo ID, sign into your account to get a site for free. If you don’t have a Yahoo ID, click Sign Up and fill in the information to create an account.
  3. Define what type of Web site you intend to build as well as the other required information. Click Submit.
  4. Click Build your Web site now. Under Getting Started, click Create a Web site.
  5. Create your Web site using Yahoo! PageBuilder. Click Try PageBuilder, then click Launch PageBuilder. (Note: If PageBuilder does not open, you may need to turn on or install Java.)
  6. When PageBuilder has opened, click File > Upload Files and Images. Browse to the HTML file that you saved on your local machine and click Upload. You will not see a preview of the map in the PageBuilder design view.
  7. Open a new Web browser and type the URL to your GeoCities Web site. You can find this URL at the top of the PageBuilder window. Append the name of the HTML file onto the end of your Web site URL. For example: www.geocities.com/MyAccount/MyWebMap. You should now be able to see the ArcGIS Online map in a live Web site that others can use. Built-in navigation functionality such as zoom and pan will be automatically enabled.

You now have a new map embedded in your Web site that accesses a base data service and an overlay service hosted by ESRI.

Step 3

Adding Another Web Service

Next, we will use an additional service from one of several publicly available from ESRI’s servers. These steps will guide you through the process of adding an additional tiled ArcGIS Server service into your existing JavaScript API application.

  1. Open the HTML file that you created earlier and find the code block beginning at line 13 that is shown in bold (Listing 1). Copy the code in bold to your clipboard. Paste the code just copied so that it resides within the last curly bracket and you have two copies of the same lines of code.
  2. Navigate to resources.esri.com/javascript and select the link for Sample Server 1.
  3. Click the Portland link and choose Portland/Portland_ESRI_Neighborhoods_AGO (MapServer). Select and copy the URL from the address bar of the browser (sampleserver1.arcgisonline.com/ArcGIS/rest/services/Portland/Portland_ESRI_Neighborhoods_AGO/MapServer).
  4. In the HTML file, replace the URL on the block of code that you just pasted with the URL to the Portland_ESRI_Neighborhoods_AGO Service. Also create a new variable Portland (var Portland = new) and add it to the map. The new block of code should look like Listing 3.
  5. Test this updated HTML page locally by opening it in a browser. Upload the revised file by opening a new Web browser and entering geocities.yahoo.com. Click the Manage tab, click the Easy Upload link, and upload the new version of your HTML file. Go to your GeoCities Web site and reload the page.

Use GeoCities PageBuilder to load your HTML file onto the GeoCities Web server so your mapping application will be available over the Web. Upload the revised HTML page to your GeoCities Web site using and appending the name of the file that was uploaded.

The world map and Portland region are both accessible now. You can quickly zoom into the Portland region by holding down the Shift key and create a zoom-in box around the area of interest. You now have a new map embedded in your Web site that accesses a base data service and an overlay service hosted by ESRI.

To use your own service, all you need to do is replace the URL of the sample 1 service with the URL of your own service. You can find a video on the ArcGIS Server Resource Center that will expand on these steps to lead you through an example of adding an overlay service to your base data. Navigate to www.esri.com/javascript, click Samples, and select the link for the second video. Both services are tiled (also known as cached) services, so the method used is ArcGISTiledMapServiceLayer. For a dynamic service, the method would be ArcGISDynamicLayer.

When overlaying multiple cached services, the tiling scheme and projection from the second layer must
match that of the first. For more information on overlaying a service with ArcGIS Online base data, refer to the ArcGIS Server online help documentation. Open a Web browser and navigate to webhelp.esri.com. Click ArcGIS Server 9.3 Help and choose ArcGIS Server Help Online from either the .NET or Java edition. Expand Publishing Services > Caching Services > Map Caches (2D) and choose the help topic Designing a Map to overlay ArcGIS Online services.

Code snippits:
Disclaimer: I haven’t tried this code!
Copied and pasted from the PDF.

Listing 1: Find line 13 and add the code shown in bold onto your clipboard.

function init() {
myMap = new esri.Map(“mapDiv”);
myTiledMapServiceLayer = new esri.layers.ArcGISTiledMapServiceLayer(“http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer”);
myMap.addLayer(myTiledMapServiceLayer);
}

Listing 2: Paste another copy of the code as shown in bold.

function init() {
myMap = new esri.Map(“mapDiv”);
myTiledMapServiceLayer = new esri.layers.ArcGISTiledMapServiceLayer(“http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer”);
myMap.addLayer(myTiledMapServiceLayer);
myTiledMapServiceLayer = new esri.layers.ArcGISTiledMapServiceLayer(“http://server.arcgisonline.co/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer”);
myMap.addLayer(myTiledMapServiceLayer);
}

Listing 3: Code after adding the URL for Portland_ESRI_Neighborhoods_AGO Service URL

function init() {
myMap = new esri.Map(“mapDiv”);
myTiledMapServiceLayer = new esri.layers.ArcGISTiledMapServiceLayer(“http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer”);
myMap.addLayer(myTiledMapServiceLayer);
var Portland = new esri.layers.ArcGISTiledMapServiceLayer(“http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Portland/Portland_ESRI_Neighborhoods_AGO/MapServer”);
myMap.addLayer(Portland);
}

Tags: , , ,

3 Responses to “Tutorial for ArcGIS web mapping API for JavaScript (ESRI)”

  1. zak says:

    can you give me full tutorial in pdf file
    thank

  2. Delfi says:

    @ Nathaniel
    I also need the tutorial. Try to open ur link but it’s broken.. error.
    Would u like to help me with other link? Please send it to my email.
    Thanks before ^_^