Working with TextSymbol in the ArcGIS JavaScript API

This post discusses how you can add text to your map using the ArcGIS JavaScript API. Your map service probably already has some labeling in it, but you may want to add descriptive information about graphics that you add on top of your map through tasks or queries. The ArcGIS JavaScript API does not have a built-in labeling engine with conflict detection and label placement algorithims, but you can use the TextSymbol class to add text at a specific point location on the map.

The TextSymbol class has several properties that you can use to fine-tune the position and content of the text element such as angle, offset, font, and kerning (spacing between the letters).

Use the TextSymbol.setFont() method to specify a font for the text. You can use the Font class to set properties like text size, style and weight.

Creating a text graphic

Let’s look at a code snippet that uses several of the Font and TextSymbol properties to create a new TextSymbol and add it to our map as a text graphic. This graphic will denote an unexplored area on our map using an old cartographic phrase “Here be dragons”. First, we’ll create the Font object and specify the font weight and size.

    
var font = new esri.symbol.Font();
font.setSize("12pt");
font.setWeight(esri.symbol.Font.WEIGHT_BOLD);

Now we need to create a new TextSymbol and specify that it should be maroon, set at a 15-degree angle and be aligned to the start of our input point.Next, we use the setFont() method to assign the font we just created to the TextSymbol. Finally, we create a new graphic, assign it the newly created TextSymbol, then add the graphic to the map.

         var textSymbol = new esri.symbol.TextSymbol("Here be dragons");
textSymbol.setColor( new dojo.Color([128, 0, 0]));
textSymbol.setAlign(esri.symbol.TextSymbol.ALIGN_START);
textSymbol.setAngle(15);

textSymbol.setFont(font);

var pt= new esri.geometry.Point(x,y,map.spatialReference)
var gra = new esri.Graphic(pt,textSymbol);
map.graphics.add(gra);

Simplifying the code

The code above is written in a verbose style to make it easier to examine the values we set for the TextSymbol and Font properties. We can reduce the length of the code snippet by using object constructors and chaining method calls. Let’s explore this approach a bit:

  • First, use map.graphics to get access to the map’s default graphics layer.
  • The GraphicsLayer has an add method that takes a Graphic object as a parameter, we’ll create a new graphic within the method call using the Graphic constructor.
  • Graphics consist of geometry, symbol, attributes and an infoTemplate. In our example, we don’t need attributes or an infoTemplate so we’ll use the Graphic constructor and provide only a geometry (Point) and symbol (TextSymbol)
  • Let’s examine the TextSymbol section a bit more closely. Many of the JavaScript objects, like Graphic and TextSymbol, have setter methods that return the object. Because of this we can chain method calls. In the snippet below, we create a new TextSymbol, define the text in the constructor, then chain setColor, setAlign, setAngle and setFont to reduce the amount of code we have to write.
     map.graphics.add(
new esri.Graphic(
new esri.geometry.Point(x,y, map.spatialReference),
new esri.symbol.TextSymbol("Here be dragons").setColor(
new dojo.Color([128,0,0])).setAlign(esri.symbol.TextSymbol.ALIGN_START).setAngle(45).setFont(
new esri.symbol.Font("12pt").setWeight(esri.symbol.Font.WEIGHT_BOLD))
)
)

One caveat to this approach is that it can make the code more difficult to read; however, with a bit of practice it becomes second nature.

Samples

  • Click here to see a live sample that generates text graphics
  • The Graphic Symbology Code Generator on the Code Gallery generates JavaScript code for symbols and is a great tool to explore various symbol properties.
  • To label polygon graphics, use the GeometryService.labelPoints() method to generate a point inside the polygon. You can then designamte this point as the label position. View the Create points for labeling sample for details on how to use this method.
  • Some text information may be better suited to display in an info window. The Show an info window sample shows how to display text in an info window at a specific location

Notes

There are several browser-specific issues to be aware of when working with fonts and text symbols. These issues are well documented in the dojox.gfx documentation. Some of the more common issues are:

  • The font family property does not work in Internet Explorer 7; Arial is always used.
  • Several browsers including Internet Explorer 7, Firefox and Opera 9 do not support the rotated and decoration properties for text symbols.

Contributed by Kelly Hutchins of the ArcGIS JavaScript API development team.

This entry was posted in Services and tagged , , . Bookmark the permalink.

Leave a Reply

One Comment

  1. gcriloux says:

    It seems to be working fine in Firefox 3.5