Articles and Tutorials

SmartFIND Vector Graphics API Beta

Dynamically add polygon and line features to SmartFIND maps with the SmartFIND Vector Graphics API.

Introduction

When your maps application needs to display more than just Point Of Interest (POI) data, or support a higher level of user interaction, the SmartFIND Vector Graphics API adds an extended set of features that can be overlaid on the map.

The Vector Graphics API is a cross-plaftorm library that works in recent versions of Internet Explorer, Firefox, and Opera. While the underlying rendering engine used is platform-specific developers are shielded from implementation differences by a simple API that will be familiar to developers who have already used the Maps API.

For example the following code draws a red circle with a blue outline, centered at a specific coordinate, and with a radius of 40 kilometres: 

 
var style = {fill: 'red', stroke: 'blue'};
feature = new GSCircle({center: new GSPoint(2691566, 6462846), radius: 40000, style: style});
map.getLayer('base').addFeature(feature);

View Example

The Vector Graphics map features behave just like other map features, scaling in size as the map is zoomed and moving as the map is panned. The vector features can respond to user events so visual feedback can be provided when a feature is moused over or the map's info window can be opened over a vector feature when it receives a mouse click.

Some applications for the Vector Graphics API include the display of demographic data, visually showing the radius of a proximity search, or the provision of a drawing interface for the user to define a search polygon.

API Classes

The API provides a generic Path object, GSPath and a set of basic shape classes for drawing the following shapes:
  • line
  • polyline
  • polygon
  • rectangle
  • circle
  • ellipse

All vector features subclass the GSVectorGraphics class which provides a common interface for styling and event handling.

Creating a Vector Feature

A vector feature is instantiated with a number of name-value pairs to specify the shape and style of the feature. All features allow the appearance of the feature to be specified with a style argument, if the feature should contain text, the text string, its position and style can be provided as constructor arguments. The example below creates a circle with an associated text label: 
 
var style = {stroke: '#a80510', 'stroke-width': '1px', fill: '#a80510', 'fill-opacity': 0.4};
var text = '12345';
var textStyle = {color: '#a80510', 'font-weight': 'normal', 'font-size': '20px',
  'text-align': 'center', 'vertical-align': 'middle'};
var params = {
  origin: new GSPoint(2691566, 6462846),
  width: 100000,
  height: 50000,
  style: style,
  text: text,
  'text-style': textStyle
};
feature = new GSRect(params);
map.getLayer('base').addFeature(feature);

View Example

Painting

Both the path and basic shape features can be filled (painting the interior of the feature) and stroked (painting along the outline of the feature). Filling and stroking can be thought of in more general terms as painting.

Features can be painted with:

  • a solid color
  • a solid color with opacity
Support for gradients and patterns is planned for a later release.

Feature Styles

All of the fill and stroke properties for a vector feature can be set collectively as a feature style. A feature may be initialized with a particular style, or the style may be set at a later point using the GSVectorGraphics.setStyle() method. A features style is specified using an object literal, using the same property names as the equivalent SVG styling properties. An example of setting a feature's style follows: 
 
var style = {stroke: '#a80510', 'stroke-width': '3px', fill: 'red', 'fill-opacity': 0.6};
feature.setStyle(style);
The full list of currently supported style properties is:
  • stroke: this property paints along the outline of the given graphical element. It takes a paint value which may be none indicating that no paint is applied, or a color value specified using either an HTML4 keyword, RGB hex value, or rgb(...) functional value
  • stroke-width: the width of the stroke on the current object.
  • stroke-opacity: specifies the opacity of the painting operation used to stroke the current object. Value should be in the range of 0.0 (fully transparent) to 1.0 (fully opaque).
  • fill: this property paints the interior of the object. It takes a paint value which may be none indicating that no paint is applied, or a color value specified using either an HTML4 keyword, RGB hex value, or rgb(...) functional value
  • fill-opacity: specifies the opacity of the painting operation used to paint the interior of the current object.
  • opacity: the uniform opacity setting to be applied across an entire object.
  • visibility: controls whether the object is visible. Possible values are visible or hidden

Style properties may also be set independently using setter methods, for example to set the stroke property you would do this: 

 
feature.setStroke('blue');

Adding Text

All vector features have built-in support for adding text labels. Text may be explicitly positioned within the feature's coordinate system or automatically positioned. Some control over the text presentation is also possible.

Text information is either passed as arguments to the feature's constructor or set using the GSVectorGraphics.setText() method.

Positioning Text
Text can be explicitly positioned relative to the top-left corner of the feature's bounding box via the feature's text-position parameter. This parameter takes an object literal with x and y properties. The x and y values are interpreted as pixel values. 
 
var textPosition = {x: 10, y: 10};
Alternatively text may be centered on the x or y axes using the text-align and vertical-align properties of the text-style parameter.
Styling Text
Text is styled using the feature's text-style parameter. This parameter takes an object literal with font-family, font-size, font-weight, and color values. For more information on the possible values for these properties see GSVectorGraphics.setText(). 
 
var textStyle = {color: '#a80510', 'font-family: 'Verdana, Helvetica, Sans-serif',
  'font-weight': 'normal', 'font-size': '20px'};

Event Handling

Event handlers can be registered with vector features to respond to user mouse events. To register an event handler use the following syntax: 
 
feature.addEventHandler('mouseover', function(e) {
  this.setFillOpacity(0.6);
});

View Example

Using the Vector Graphics API

The vector graphics API is dependent upon the version 3 of the Maps API, to use it in your web pages insert the following script tag in the head of the document after the tag importing the Maps API: 

 
<script type="text/javascript" src="http://api.geosmart.co.nz/api?service=svg&v=1-rc2&user=your-user-name"></script>

Supported Browsers

Currently the vector graphics API is supported by the following browsers:
  • Microsoft Internet Explorer 6 and 7
  • Firefox 1.5 and above
  • Opera 8 and above
  • Camino 1.0

Note that there is currently a bug in the Gecko rendering engine for the Mac, used by Firefox and Camino on that platform, which prevents text added to vector shapes from being rendered.

To provide alternative content for browsers that do not meet the requirements for the vector graphics API, use the global object _browser object to test for vector API capability: 

 
var isVectorCapable = _browser.isVectorGraphicsCapable();

Configuration for Specific Rendering Engines

The vector graphics API aims to provide the same user experience across any of the supported browser platforms. When running under Internet Explorer it uses the Vector Markup Language (VML) for rendering, under Firefox and Opera Scalable Vector Graphics (SVG) is used.

Each of these rendering engines has specific environmental requirements.

For VML:

  • The html root element must bind the namespace prefix v to the URI urn:schemas-microsoft-com:vml
  • The head element must contain an object child with the id VMLRender
  • The head element must contain a CSS style element that specifies that all elements in the urn:schemas-microsoft-com:vml namespace should have the behavior property url(#VMLRender). This tells the Web browser to pass all elements in the VML namespace to the object with the ID VMLRender for display.
An example HTML document with support for VML would look like this: 
 
  <html xmlns:v="urn:schemas-microsoft-com:vml">
  <head>
    <object id="VMLRender" classid="CLSID:10072CEC-8CC1-11D1-986E-00A0C955B42E"></object>
    <style type="text/css">
      v\:* { behavior: url(#default#VML); }
    </style>
    <script type="text/javascript"
            src="http://api.geosmart.co.nz/api?service=svg&v=1-rc2&user=your-user-name"></script>
  </head>
  ...

For SVG:

  • Your web pages must be valid XHTML (an XML dialect). SVG-capable browsers will only recognise inline SVG when it is embedded in XML as the browser will use a separate parser for XML, and only this parser knows how to render the SVG content.
  • The XHTML namespace must be declared as the default namespace on the html root element
  • Your web server must be configured to return documents using the vector API with an XML MIME type, either text/xml or application/xhtml+xml
An example XHTML document with support for SVG would look like this: 
 
  <html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <script type="text/javascript"
            src="http://api.geosmart.co.nz/api?service=svg&v=1-rc2&user=your-user-name"></script>
  </head>
  ...

For SVG and VML:

Supporting both VML and SVG-capable browsers requires a little more effort due to the conflicting requirements of Internet Explorer and the SVG-capable browsers to have the document served as HTML/XML respectively. One solution is described here on the SVG Wiki.