Overlay API Reference

From Ka-Map Wiki

1 Source
2 kaXmlOverlay Quick HOW-TO
3 kaXmlOverlay Reference
4 FAQs
5 TODOs

[edit] Source

index_overlay.html, startup_overlay.js - based on CVS 3.0

[edit] kaXmlOverlay Quick HOW-TO

1 Import scripts in your page:

<script type="text/javascript" src="xhr.js"></script>
<script type="text/javascript" src="excanvas.js"></script>
<script type="text/javascript" src="wz_jsgraphics.js"></script>
<script type="text/javascript" src="XMLOverlay/kaXmlOverlay.js"></script>

2 Let ka-Map initialize itself: the next steps should wait at lest the KAMAP_MAP_INITIALIZED event.

3 Create a kaXmlOverlay object:

myXmlOverlay = new kaXmlOverlay( myKaMap, 250 );

4 Add some objects on the overlay layer. There are two ways to do that

- Call the loadXml method: this method load an XML document from the web server.

myXmlOverlay.loadXml('points.xml');

- Write a JavaScript function to add your objects:

var my_point = myXmlOverlay.addNewPoint('Point ID', longuitude, latitude);
var my_symbol = new kaXmlSymbol();
my_symbol.size = 12;
my_symbol.color = '#ff0000';
my_point.addGraphic(my_symbol);

5 To have a periodic update:

myInterval = setInterval("myMovingOverlay.loadXml('xmlget.php')",5000);

[edit] kaXmlOverlay Reference

This document describe the interface of the JavaScript kaXmlOverlay library as well as the XLM documents describing overlays. The document is divided in to three sections:

A summary of JavaScript objects and functions
The definition of the XML
An in depth description of attributes common to both XML and JavaScript functions

[edit] JavaScript API

In this section there is a list of main classes with methods and properties that you can use to programmatically add overlays to your map. A detailed and updated documentation for each function is maintained as JavaDoc like comments in the source code.

[edit] Class kaXmlOverlay

This class represents a map layer where it's possible to add overlays. To instantiate this class use the constructor

kaXmlOverlay( oKaMap, zIndex )

oKaMap: A kaMap object
zIndex: The z index of the layer

To load an XML document with overlay description call the method

kaXmlOverlay.prototype.loadXml = function(xml_url)

xml_url: URL of th XML with points to plot

To add a new point to an overlay

kaXmlOverlay.prototype.addNewPoint = function(pid, x, y)

pid: Point ID
x: X geo-coordinate
y: Y geo-coordinate
return: A kaXmlPoint object with the given point ID.

To retrieve an existing point from an overlay call

kaXmlOverlay.prototype.getPointObject = function(pid)

pid: Point ID
return: The kaXmlPoint object given the point ID. null if not found.

To remove one or more points from the overlay

kaXmlOverlay.prototype.removePoint = function( pid )

pid: Point ID or a regexp. If pid is null or not present remove all points.

[edit] Class kaXmlPoint

A kaXmlPoint represents a group of graphic object on the overlay layer. The point is placed on the map at specified geographic coordinates. A point can be moved on the map without the need of redrawing all its graphic objects.

To instantiate a new point don't use the constructor but call the kaXmlOverlay.addNewPoint() function.

To place or move a kaXmlPoint on the map call

kaXmlPoint.prototype.setPosition = function( x, y )

x: X geo-coordinate
y: Y geo-coordinate

To clear all graphics associated with the point call the method

kaXmlPoint.prototype.clear = function()

To add graphic objects to a point use the method

kaXmlPoint.prototype.addGraphic = function( obj )

obj: an object of type kaXmlSymbol, kaXmlIcon, kaXmlLabel, kaXmlLinestring or kaXmlPolygon

To manually set the HTML content of a kaXmlPoint use the method

kaXmlPoint.prototype.setInnerHtml = function(ihtml)

ihtml: A string containing the HTML

This function delete any other content of the point.

[edit] Graphic objects classes

The graphic objects that can be displayed are:

kaXmlSymbol
kaXmlLabel
kaXmlIcon
kaXmlLinestring
kaXmlPolygon

All this classes have a constructor without parameters and different attributes: the attributes are described in the following of the document.

To use one of these objects create a new instance, configure it setting its properties ad add it to a kaXmlPoint with the method addGraphic.

Using CANVAS for vector graphics

Symbols, linestrings and polygons are drawn using <canvas>. To change this behaviour and use the previous implementation (drawgeom.php and wz_jsgraphcs) use

xmlOverlayUseCanvas = false;

[edit] XML Document Type Definition

<!ELEMENT overlay (delete*, point*)>

<!ELEMENT delete EMPTY>

<!ELEMENT point (ihtml?, symbol*, icon*, label*, linestring*, polygon*)>

<!ELEMENT ihtml (#PCDATA)>


<!ELEMENT symbol EMPTY>
<!ELEMENT icon EMPTY>

<!ELEMENT label (#PCDATA)>

<!ELEMENT linestring EMPTY>

<!ELEMENT polygon EMPTY>

<!ATTLIST delete id CDATA #IMPLIED>

<!ATTLIST point id CDATA #REQUIRED>
<!ATTLIST point x CDATA #REQUIRED>
<!ATTLIST point y CDATA #REQUIRED>
<!ATTLIST point redraw (false|true) "false">

<!ATTLIST symbol shape CDATA #IMPLIED>
<!ATTLIST symbol size CDATA #IMPLIED>
<!ATTLIST symbol color CDATA #IMPLIED>
<!ATTLIST symbol bcolor CDATA #IMPLIED>
<!ATTLIST symbol stroke CDATA #IMPLIED>
<!ATTLIST symbol opacity CDATA #IMPLIED>

<!ATTLIST icon src CDATA #REQUIRED>
<!ATTLIST icon w CDATA #REQUIRED>
<!ATTLIST icon h CDATA #REQUIRED>
<!ATTLIST icon px CDATA #IMPLIED>
<!ATTLIST icon py CDATA #IMPLIED>
<!ATTLIST icon opacity CDATA #IMPLIED>

<!ATTLIST label color CDATA #IMPLIED>
<!ATTLIST label boxcolor CDATA #IMPLIED>
<!ATTLIST label w CDATA #IMPLIED>
<!ATTLIST label h CDATA #IMPLIED>
<!ATTLIST label px CDATA #IMPLIED>
<!ATTLIST label py CDATA #IMPLIED>
<!ATTLIST label fsize CDATA #IMPLIED>
<!ATTLIST label font CDATA #IMPLIED>

<!ATTLIST linestring color CDATA #IMPLIED>
<!ATTLIST linestring stroke CDATA #IMPLIED>
<!ATTLIST linestring opacity CDATA #IMPLIED>

<!ATTLIST polygon color CDATA #IMPLIED>
<!ATTLIST polygon bcolor CDATA #IMPLIED>
<!ATTLIST polygon stroke CDATA #IMPLIED>
<!ATTLIST polygon opacity CDATA #IMPLIED>

[edit] XML document example

<overlay>
 <point x="7435386.24" y="6172463.1" id="p1">
   <label>just a label</label>
   <symbol shape="bullet" size="10" opacity="1" color="#FF0000" />
 </point>
</overlay>

[edit] Overlay objects attributes

[edit] POINT (<point>)

The POINT is the father of all objects you can display on the overlay layer. Wherever you want dislay someting on the overlay layer you have to define a POINT than add to the POINT icons, symbols, labels, etc.

POINT attributes:

id: (string, mandatory) This string is used to identify the point. It's needed to translate, delete, redraw the POINT.
x: (number, required) The X coordinate in map units.
y: (number, required) The Y coordinate in map units.

[edit] SYMBOL (kaXmlSymbol, <symbol>)

A symbol is a graphic element drawn at POINT coordinates. It's similar to an icon, but it has a parametric color and size.

SYMBOL attributes:

shape: (string, optional) The shape of the symbol. Today implementation allows only the shapes bullet and square.
color: (string, optional) The fill color of the symbol (HTML syntax).
bcolor: (string, optional) Border color (HTML syntax).
size: (integer, optional) The size in pixels of the symbol.
stroke: (integer, optional) Line width in pixels.
opacity: (number, optional) 1.0 is opaque, 0.0 is fully transparent.

[edit] ICON (kaXmlIcon, <icon>)

An icon drawn at POINT coordinates. The image is defined with an URL. Width and height of the image must be provided, because the icon will be centred at POINT coordinates.

ICON attributes

src: (string, required) The relative or absolute URL of the image
w: (integer, required) Width of the image in pixels
h: (integer, required) Height of the image in pixels
px: (integer, optional) Horizontal offset in pixels (positive to move the icon on the right).
py: (integer, optional) Vertical offset in pixels (negative to rise the icon).
opacity: (number, optional) 1.0 is opaque, 0.0 is fully transparent.

[edit] LABEL (kaXmlLabel, <label>)

A text label is written near the POINT. POINT coordinates represent the top-left corner of the LABEL.

LABEL attributes

color: (string, optional) Text color (HTML syntax).
boxcolor: (string, optional) Background color behind the text (HTML syntax).
w: (integer, optional) Width of the label in pixels.
h: (integer, optional) Height of the label in pixels.
px: (integer, optional) Horizontal offset in pixels (positive to move the label on the right).
py: (integer, optional) Vertical offset in pixels (negative to rise the label).
font: (string, optional) The text font (HTML syntax).
fsize: (string, optional) Font size (HTML syntax).
text: (string, required) The label text: this attribute is present only in JavaScript: in the XML syntax the text is the content of the <label> element.

[edit] LINESTRING (kaXmlLinestring, <linestring>)

This element represent a geographic feature, a single line in geographic coordinates that will be scaled with the map. The coordinates of the line must be expressed a string in the form

x0 y0, x1 y1, [...], xn yn

The coordinates string is the text node of the XML element. In JavaScript the coordinates string is passed to the object with the method readCoordinates().

LINESTRING attributes

color: (string, optional) Line color (HTML syntax).
stroke: (integer, optional) Line width in pixels.
opacity: (number, optional) 1.0 is opaque, 0.0 is fully transparent.

[edit] POLYGON (kaXmlPolygon, <polygon>)

This element represent a geographic feature, a single polygon in geographic coordinates that will be scaled with the map.

POLYGON attributes

color: (string, optional) Surface color (HTML syntax).
bcolor: (string, optional) Border color (HTML syntax).
stroke: (integer, optional) Border width in pixels.
opacity: (number, optional) 1.0 is opaque, 0.0 is fully transparent.

[edit] FAQs

Error: xmlDocument has no properties

The XML is served with a wrong mime type by your web server. It should have a mime type "text/xml". Configure your server to associate ".xml" files with the correct mime, or, if you generate the XML dynamically, use a directive to set the mime type.

If your XML is created on the fly by a PHP script use this as first lines:

<?php
header("Content-Type: text/xml");
header("Cache-Control: no-store, no-cache, must-revalidate");
echo '<?xml version="1.0" encoding="UTF-8"?>'
?>

In IE6 with excanvas.js canvas are not displayed

The HTML page must begin with

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

[edit] TODOs

Evaluate the use of custom onclick or ondblclick events on points
Add a tooltip for overlay points
Make the label management smarter

Retrieved from "http://ka-map.ominiverdi.org/wiki/index.php/Overlay_API_Reference"