/******************************************************************************
* kaXmlOverlay - XML server side generated overlay for kaMap.
*
* Piergiorgio Navone
*
* $Id: kaXmlOverlay.js 51 2006-04-26 20:21:11Z pg $
*****************************************************************************/
/******************************************************************************
* BEGIN section in Wiki syntax
!!! kaXmlOverlay Quick HOW-TO
* __1__ Import scripts in your page:
* __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);
--------------------------------------------
!!! 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 tree sections:
# A summary of JavaScript objects and functions
# The definition of the XML
# An in deep description of attributes common to both XML and JavaScript functions
!! JavaScript API
In this section there is a list of main classes with methods an properties that you ca use to programmatically add overlays to your map.
A detailed an updated documentation for each function is maintained as JavaDoc like comments in the source code.
! Class kaXmlOverlay
This class represent a map layer where is possible to add overlays.
To instantiate this class use the constructor
kaXmlOverlay( oKaMap, xml_url )
;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.
! 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.
! 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''.
!! XML Document Type Definition
----------
----------
! XML document example
----------
TODO
----------
!! Overlay objects attributes
! 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.
! SYMBOL (kaXmlSymbol, )
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 allow only the shape ''bullet''.
;color: (string, optional) The color of the symbol (HTML syntax).
;size: (integer, optional) The size in pixels of the symbol.
;opacity: (number, optional) 1.0 is opaque, 0.0 is fully transparent.
! ICON (kaXmlIcon, )
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.
! LABEL (kaXmlLabel,