Adding Graphics to the Map

Eric Pimpler

February 2014

(For more resources related to this topic, see here.)

Graphics are points, lines, or polygons that are drawn on top of your map in a layer that is independent of any other data layer associated with a map service. Most people associate a graphic object with the symbol that is displayed on a map to represent the graphic. However, each graphic in ArcGIS Server can be composed of up to four objects, including the geometry of the graphic, the symbology associated with the graphic, attributes that describe the graphic, and an info template that defines the format of the info window that appears when a graphic is clicked on. Although a graphic can be composed of up to four objects, it is not always necessary for this to happen. The objects you choose to associate with your graphic will be dependent on the needs of the application that you are building. For example, in an application that displays GPS coordinates on a map, you may not need to associate attributes or display info window for the graphic. However, in most cases, you will be defining the geometry and symbology for a graphic.

Graphics are temporary objects stored in a separate layer on the map. They are displayed while an application is in use and are removed when the session is complete. The separate layer, called the graphics layer, stores all the graphics associated with your map. Just as with the other types of layers, GraphicsLayer also inherits from the Layer class. Therefore, all the properties, methods, and events found in the Layer class will also be present in GraphicsLayer.

Graphics are displayed on top of any other layers that are present in your application. An example of point and polygon graphics is provided in the following screenshot. These graphics can be created by users or drawn by the application in response to the tasks that have been submitted. For example, a business analysis application might provide a tool that allows the user to draw a freehand polygon to represent a potential trade area.

The polygon graphic would be displayed on top of the map, and could then be used as an input to a geoprocessing task that pulls demographic information pertaining to the potential trade area.

Many ArcGIS Server tasks return their results as graphics. The QueryTask object can perform both attribute and spatial queries. The results of a query are then returned to the application in the form of a FeatureSet object, which is simply an array of features. You can then access each of these features as graphics and plot them on the map using a looping structure. Perhaps you'd like to find and display all land parcels that intersect the 100 year flood plain. A QueryTask object could perform the spatial query and then return the results to your application, where they would then be displayed as polygon graphics on the map.

In this article, we will cover the following topics:

  • The four parts of a graphic
  • Creating geometry for graphics
  • Symbolizing graphics
  • Assigning attributes to graphics
  • Displaying graphic attributes in an info window
  • Creating graphics
  • Adding graphics to the graphics layer

The four parts of a graphic

A graphic is composed of four items: Geometry, Symbol, Attributes, and InfoTemplate, as shown in the following diagram:

A graphic has a geometric representation that describes where it is located. The geometry, along with a symbol, defines how the graphic is displayed. A graphic can also have attributes that provide descriptive information about the graphic. Attributes are defined as a set of name-value pairs. For example, a graphic depicting a wildfire location could have attributes that describe the name of the fire along with the number of acres burned. The info template defines what attributes should be displayed in the info window that appears when the graphic appears, along with how they should be displayed. After their creation, the graphic objects must be stored inside a GraphicsLayer object, before they can be displayed on the map. This GraphicsLayer object functions as a container for all the graphics that will be displayed.

All the elements of a graphic are optional. However, the geometry and symbology of a graphic are almost always assigned. Without these two items, there would be nothing to display on the map, and there isn't much point in having a graphic unless you're going to display it.

The following figure shows the typical process of creating a graphic and adding it to the graphics layer. In this case, we are applying the geometry of the graphic as well as a symbol to depict the graphic. However, we haven't specifically assigned attributes or an info template to this graphic.

Creating geometry for graphics

Graphics will almost always have a geometry component, which is necessary for their placement on the map. These geometry objects can be points, multipoints, polylines, polygons, or extents and can be created programmatically through a constructor for these objects or can be returned as an output from a task such as a query.

Before creating any of these geometry types, the sri/geometry resource needs to be imported. This geometry resource contains classes for Geometry, Point, Multipoint, Polyline, Polygon, and Extent.

Geometry is the base class that is inherited by Point, MultiPoint, Polyline, Polygon, and Extent.

As can be seen from the following code line, the Point class defines a location by
an X and Y coordinate, and can be defined in either map units or screen units:

new Point(-118.15, 33.80);

Symbolizing graphics

Each graphic that you create can be symbolized through one of the various symbol classes found in the API. Point graphics are symbolized by the SimpleMarkerSymbol class and the available shapes include circle, cross, diamond, square, and X. It is also possible to symbolize your points through the PictureMarkerSymbol class, which uses an image to display the graphic. Linear features are symbolized through the SimpleLineSymbol class and can include solid lines, dashes, dots, or a combination. Polygons are symbolized through the SimpleFillSymbol class and can be solid, transparent, or crosshatch. In the event that you'd prefer to use an image in a repeated pattern for your polygons, the PictureFillSymbol class is available. Text can also be added to the graphics layer and is symbolized through the TextSymbol class.

Points or multipoints can be symbolized through the SimpleMarkerSymbol class, which has various properties that can be set, including style, size, outline, and color. Style is set through the SimpleMarkerSymbol.setStyle() method that takes one of the following constants, which corresponds to the type of symbol that is drawn (circle, cross, diamond, and so on):


Point graphics can also have an outline color, which is created through the SimpleLineSymbol class. The size and color of the graphics can also be set.
Examine the following code example to get an idea on how this is done:

var markerSymbol = new SimpleMarkerSymbol(); markerSymbol.setStyle(SimpleMarkerSymbol.STYLE_CIRCLE); markerSymbol.setSize(12); markerSymbol.setColor(new Color([255,0,0,0.5]));

Linear features are symbolized with the SimpleLineSymbol class and can be a solid line or a combination of dots and dashes. Other properties include color, as defined with dojo/Color, and a width property setWidth to set the thickness of your line. The following code example explain the process in detail:

var polyline = new Polyline(msr); //a path is an array of points var path = [new Point(-123.123, 45.45, msr),…..]; polyline.addPath(path); var lineSymbol = new SimpleLineSymbol().setWidth(5); //create polyline graphic using polyline and line symbol var polylineGraphic = new Graphic(polyline, lineSymbol);;

The following screenshot is obtained when the preceding code is run:

Polygons are symbolized through the SimpleFillSymbol class, which allows the drawing of polygons in solid, transparent, or crosshatch patterns. Polygons can also have an outline specified by a SimpleLineSymbol object. The following code example explains the process in detail:

var polygon = new Polygon(msr); //a polygon is composed of rings var ring = [[-122.98, 45.55], [-122.21, 45.21], [-122.13, 45.53],……]; polygon.addRing(ring); var fillSymbol = new SimpleFillSymbol().setColor(new Color([255,0,0,0.25])); //create polygon graphic using polygon and fill symbol var polygonGraphic = new Graphic(polygon, fillSymbol); //add graphics to map's graphics layer;

The following screenshot is obtained when the preceding code is run:


Assigning attributes to graphics

The attributes of a graphic are the name-value pairs that describe that object. In many cases, graphics are generated as the result of a task operation such as QueryTask. In such cases, each graphic is composed of both geometry and attributes, and you would then need to symbolize each graphic accordingly. The field attributes associated with the layer become the attributes for the graphic. In some cases, the attributes can be limited through properties such as outFields. If your graphics are being created programmatically, you will need to assign the attributes in your code using the Graphic.setAttributes() method as seen in the following code example:

Graphic.setAttributes( {"XCoord":evt.mapPoint.x, "YCoord".evt.mapPoint.y,
"Plant":"Mesa Mint"});

Displaying graphic attributes in an info template

In addition to attributes, a graphic can also have an info template that defines how the attribute data is displayed in a pop-up window. A point attribute variable has been defined in the following code example and contains key-value pairs. In this particular case, we have keys that include the address, city, and state. Each of these names or keys has a value. This variable is the third parameter in the constructor for a new point graphic. An info template defines the format of the pop-up window that appears, and contains a title and an optional content template string:

var pointESRI = new Point(Number(theX), Number(theY),msr); var markerSymbol = new SimpleMarkerSymbol(); markerSymbol.setStyle(SimpleMarkerSymbol.STYLE_SQUARE); markerSymbol.setSize(12); markerSymbol.setColor(new Color([255,0,0])); var pointAttributes = {address:"101 Main Street", city:"Portland", state:

var pointInfoTemplate = new InfoTemplate("Geocoding Results"); //create point graphic using point and marker symbol var pointGraphic = new Graphic(pointESRI, markerSymbol, pointAttributes)
.setInfoTemplate(pointInfoTemplate); //add graphics to maps' graphics layer;

The preceding code produces the following screenshot:

Creating the graphics

Once you have defined the geometry, symbology, and attributes for your graphic, a new graphic object can be created with these parameters used as an input to the constructor for the Graphic object. In the following code example, we will create variables for the geometry (pointESRI), symbology (markerSymbol), point attributes (pointAttributes), and info template (pointInfoTemplate), and then apply these variables as an input to the constructor for our new graphic called pointGraphic. Finally, this graphic is added to the graphics layer.

var pointESRI = new Point(Number(theX), Number(theY, msr); var markerSymbol = new SimpleMarkerSymbol(); markerSymbol.setStyle(SimpleMarkerSymbol.STYLE_SQUARE); markerSymbol.setSize(12); markerSymbol.setColor(new Color([255,0,0])); var pointAttributes = {address:"101 Main Street", city:"Portland",
state:"Oregon"}; var pointInfoTemplate = new InfoTemplate("Geocoding Results"); //create the point graphic using point and marker symbol var pointGraphic = new Graphic(pointESRI, markerSymbol, pointAttributes).
setInfoTemplate(pointTemplate); //add graphics to maps' graphics layer;

Adding graphics to the graphics layer

Before any of your graphics are displayed on the map, you must add them to the graphics layer. Each map has a graphics layer, which contains an array of graphics that is initially empty until you add the graphics. This layer can contain any type of graphic object. This means that you can mix-in points, lines, and polygons at the same time. Graphics are added to the layer through the add() method and can also be removed individually through the remove() method. In the event that you need to remove all the graphics simultaneously, the clear() method can be used. The graphics layer also has a number of events that can be registered, including click, mouse-down, and others.

Multiple graphics layers

Multiple graphics layers are supported by the API, making it much easier to organize different types of graphics. Layers can be easily removed or added, as required. For example, you can put polygon graphics that represent counties in one graphics layer and point graphics that represent traffic incidents in another graphics layer. Then you can easily add or remove either layer as required.


This article described how to display lines, points, and polygons in GraphicsLayer on the map. It showed how to symbolize graphics, assign attributes to graphics, displaying attributes in an info window, and adding the graphics to the graphics layer.

Resources for Article:

You've been reading an excerpt of:

Building Web and Mobile ArcGIS Server Applications with JavaScript

Explore Title