PrintThat last map was pretty boring, so let's spice it up a bit by plotting a point. View the source code of this map, copy the code to a text editor and replace the x/y coordinates in the ‘var pt’ statement with the coordinates of your hometown. Save the file and open it in a browser (no need to upload it to a web server) to confirm that you changed the coordinates correctly.
When working with the Google API, we added vector overlays by creating Marker, Polyline and Polygon objects and associating them with the desired Map. In Esri’s API, adding vector overlays involves creating a Graphic object and adding it to the Map’s associated GraphicsLayer. A Graphic has four properties that are typically set: geometry, symbol, attributes and infoTemplate. The bulk of the JS code in this page is concerned with building objects that can be used to set these properties for a new hometown graphic.
The first difference you may notice as compared to the Hello World example is that this page includes several module references and corresponding callback function arguments, in addition to the “Map” reference. As a developer, you probably won’t identify all of the modules you’ll need at the outset. You’re likely to jump back and forth between the body of your code and the module list as you recognize new modules that need to be referenced in the course of your coding.
Moving to the code’s body, an important detail to note is that manipulating the GraphicsLayer can only be done after the Map has finished loading. To ensure that this happens, the graphic adding code is written in a separate function called ShowHome(); that function is triggered by the event handler that is set up on Line 32. Note the use of the “on” syntax to create the event handler.
Getting a graphic to overlay properly on top of the base map requires that the graphic’s coordinates are in the same spatial reference system used by the base map. Esri’s base maps are in the WGS 84 geographic coordinate system. The first line of the ShowHome() function creates a new Point object and defines its spatial reference as 4326, the “Well-Known ID” (WKID) of the WGS 84 coordinate system. (The ID is “Well-Known” because it’s used throughout the geospatial industry.) Complete listings of geographic and projected coordinate systems and their WKIDs can be found at http://resources.arcgis.com/en/help/arcgis-rest-api/02r3/02r3000000qq000000.htm.
The next step in creating the graphic is defining its symbol. If you look under the symbols heading in the API Reference, you're likely to see a number of classes that seem like they might be suitable for depicting a point location. It turns out that the only two choices are actually SimpleMarkerSymbol and PictureMarkerSymbol. The first of these classes is used to depict points using a circle, cross, diamond, square or an x. As its name implies, the other class is used to depict points using an image.
In this script, we use a SimpleMarkerSymbol. Looking at that class in the API Reference, you should note from the Class Constructor section that objects of the class can be created by supplying no arguments (in which case you would follow up the creation of the object with calls to methods like setOutline() and setStyle()), with a list of four arguments separated by commas, or with properties defined in a JSON object. The second option is the one we use in this script.
Before discussing the code further, I want to draw your attention to the Class Hierarchy section near the top of the SimpleMarkerSymbol class. This section shows that SimpleMarkerSymbol is a sub-class of the MarkerSymbol class, which in turn is a sub-class of the Symbol class. What this means is that a SimpleMarkerSymbol inherits the properties and methods defined under the MarkerSymbol class and the Symbol class. So, a SimpleMarkerSymbol has a size property because it inherits it from the MarkerSymbol class and a color property because it inherits it from the Symbol class.
Also, while looking at the MarkerSymbol and Symbol classes, note that their descriptions explain that those classes have no constructor. This means that there are no actual objects of those classes. They simply exist in the abstract as a means of defining properties and methods that are shared in common by sub-classes beneath them in the class hierarchy. You should also note that a similar hierarchy exists for line and polygon symbols.
Returning to our code, the SimpleMarkerSymbol object is constructed using STYLE_CIRCLE for the style parameter (other constants allowed for this parameter are listed on the SimpleMarkerSymbol API Reference page), 8 (pixels) for the size parameter, a SimpleLineSymbol for the outline parameter (which is constructed in a similar way to SimpleMarkerSymbols), and a Color object. The API Reference page for the Color class explains that a Color object can be constructed using either a named color, a hexadecimal value, an array of red/green/blue values or an RGB array plus a transparency value. In this example we use an RGB array.
So far we've discussed the coding of the graphic's geometry and symbology, which leaves the graphic's attributes and info template. In a more typical mashup that displays data stored in a shapefile or geodatabase, the attributes would be retrieved from the dataset's attribute table. Here, since we are building a marker from scratch, we hard-code the attribute information into our script using JSON notation. The InfoTemplate object is then created by supplying a title that will appear in the title bar of all info windows (the first argument to the InfoTemplate constructor) and the text that will appear in the body of the info window (the second argument to the constructor). Pay particular attention to the way values from the feature's attributes are inserted into the string (with the name of the attribute enclosed in braces and preceded by a dollar sign).
With the four necessary components created, we can create the new Graphic using the four components as arguments to the Graphic class constructor. The final line within the ShowHome() function adds the new graphic to the map's graphics layer.
Now that you've been introduced to the use of graphic overlays in Esri's API and gotten some experience digging around in the API Reference, let's continue by discussing a common need for map developers, setting the map's initial extent.