Chameleon    Home  |  Docs  |  Support  |  Bugs  |  CVS  |  Downloads 

MapTools.org

CWC2 JavaScript API
 

Introduction

The CWC2 JavaScript API (JSAPI) is a programming interface for creating client applications in JavaScript that use the capabilities of the CWC2 Service Instance. Client applications can use the JSAPI in several ways to control navigation and display of maps in custom ways. CWC2 provides the capability to create very complex applications using just templates and existing widgets. Additionally, it is possible to modify existing widgets or create entirely new widgets to perform some function. However, this requires knowledge of the internal architecture of CWC2, knowledge of the PHP programming language, and access to the CWC2 Service Instance.

In general, CWC2 application developers will not meet all these requirements. The CWC2 JSAPI object model is an abstraction of the internal architecture of CWC2 that provides a way for application developers to extend the built in behaviour of CWC2 and its widgets.

Note: JavaScript is not an "object oriented" language. The language does not contain the ability to declare classes and methods in those classes. It does provide a psuedo object mechanism through the 'this' identifier and the 'prototype' property. The end result is that JavaScript developers can create psuedo objects that contain methods and properties. It is assumed that developers using the JavaScript API are experienced JavaScript developers that are familiar with this concept.

Getting Started

In order to use the JSAPI in a CWC2 application, two additional tags need to be added to a CWC2 application template. The first is a SharedResource tag named CWCJSAPI that identifies to all other widgets that the JSAPI is to be used. In general, SharedResource tags should be defined at the beginning of a template, although this is not required. The CWCJSAPI SharedResource tag is declared as follows:

<CWC2 TYPE="SharedResource" NAME="CWCJSAPI"/>

The second is a widget tag that includes the CWC2 JSAPI code. Its purpose is to include the cwcjsapi.js file into the template and ensure that the JSAPI is properly initialized when the page is loaded. It has no visible user interface and can be declared anywhere in the template. Normally, it would be good practice to declare the CWCJSAPI tag with the associated CWCJSAPI SharedResource. The CWCJSAPI tag is declared as follows:

<CWC2 TYPE="CWCJSAPI" Debug="false"/>

With the addition of the above two tags in a CWC2 application template, the application will operate in "JavaScript" mode. This means that, whenever possible, user actions will not result in the application page being submitted. Instead, the JSAPI communciates with the server and updates the application interface directly by modifying text box contents and changing images. In some cases, especially on servers with high loads, this will result in a more responsive application that puts less load on the server. For this reason, it may be desirable to incorporate the JSAPI even though no custom development will be done.

Development using the JSAPI

In order to use the JSAPI for more than making CWC2 applications run primarily on the client side, the application developer will normally add code that allows the user to take some action or that responds to the user taking some action. In the first case, the developer can insert HTML elements and attach JavaScript functions to them to perform actions. For instance, the developer may wish to provide a button that the user can click to set the extents of the view to some previously recorded or predefined value. To do this, the developer could add an <INPUT TYPE="BUTTON" OnClick="MySetExtents()" value="Reset View"> inside the form tag on the page. Clicking this button would cause the following function to be executed:

/* Zoom the map to x1, y1, x2, y2,
   previously recorded extents */
function MySetExtents()
{
  goCWCJSAPI.oMap.SetExtents(x1, y1, x2, y2);
}

The developer could also provide a function to capture the current extents for later use in MySetExtents by adding <INPUT TYPE="BUTTON" OnClick="MyCaptureExtents()" value="Capture"> and the following function:

/* Capture the current extents for later processing */
function MyCaptureExtents()
{
  x1 = goCWCJSAPI.oMap.minx;
  x2 = goCWCJSAPI.oMap.maxx;
  y1 = goCWCJSAPI.oMap.miny;
  y2 = goCWCJSAPI.oMap.maxy;
}

Development using JSAPI Events

In addition to directly accessing or modifying the state of the application, the developer may also need the application to be notified when the user takes some action. The CWC2 JSAPI provides an Event framework that allows the developer to register JavaScript functions that are called when an Event happens. The CWC2 JSAPI provides several different event types that can be used when registering for events. They are listed at the end of this document. In order to register for events, the developer must provide code that registers function names with the JSAPI after the JSAPI has been initialized. This requires that the developer provide a custom OnLoad function for the BODY element and call the CWC2 on load function at the beginning of the function. The following code demonstrates how this is accomplished. The example provides a "zoom to last extents" capability that tracks the previous extents as the user navigates. To access this functionality, the developer would add an <INPUT TYPE="BUTTON" OnClick="MyPreviousExtents()" value="Previous Extents"> to the template.

<script language="JavaScript">
//state variables for capturing current as the user zooms
var cx1, cx2, cy1, cy2;
//state variables for remembering previous extents
var px1, px2, py1, py2;

function MyOnLoad()
{
  // make sure to initialize CWC2 first
  CWC2OnLoadFunction();
  goCWCJSAPI.RegisterEvent( MAP_EXTENTS_CHANGED,
                            "MyExtentsChanged" );
  //initialize the extents
  cx1 = goCWCJSAPI.oMap.minx;
  cx2 = goCWCJSAPI.oMap.maxx;
  cy1 = goCWCJSAPI.oMap.miny;
  cy2 = goCWCJSAPI.oMap.maxy;
  px1 = cx1;
  px2 = cx2;
  py1 = cy1;
  py2 = cy2;
}


/* this function is called whenever the map extents change,
 * capture the current extents and previous extents */
function MyExtentsChanged()
{
  px1 = cx1;
  px2 = cx2;
  py1 = cy1;
  py2 = cy2;
  cx1 = goCWCJSAPI.oMap.minx;
  cx2 = goCWCJSAPI.oMap.maxx;
  cy1 = goCWCJSAPI.oMap.miny;
  cy2 = goCWCJSAPI.oMap.maxy;
}

/* called when the user wants to go back
   to the previous extents */
function MyPreviousExtents()
{
  goCWCJSAPI.oMap.SetExtents( px1, py1, px2, py2 );
}

</script>
</head>
<body onload="MyOnLoad()">

<form>
<input type="button" onclick="MyPreviousExtents()"
       value="Previous Extents">
...

Handling Errors

During processing, the JSAPI may encounter error conditions. The CWC2 JSAPI provides an error management framework to enable developers to create robust applications that handle various error conditions in a consistent and reliable manner. The CWCErrorManager object is contained in the global CWCApplication object and can be accessed through the oErrorManager property. Error conditions can happen under two separate circumstances and developers need to be aware of both. The first is when an error happens as a direct consequence of using the JSAPI. These are "synchronous" errors and are reported during the processing of the method that was called. In this case, the method that was called will return "false". It is the responsibility of the developer to detect the false return value and check the CWCErrorManager for the last error message and error type using goCWCJSAPI.oErrorManager.PopLastError(). This method returns an array containing the Error type and the text associated with the last reported error, or false if no error happened (some functions can return false as a legal value). The second case is when errors occur on the server side as an indirect consequence of using the JSAPI. These are "asynchronous" errors and cannot be reported during regular processing. The CWCErrorManager checks for errors that have happened on the server side after each communication with the server. If errors have happened on the server, the CWCErrorManager retrieves these errors and then triggers an ERROR_OCCURRED event. The developer is responsible for registering a handler for the ERROR_OCCURRED event if handling of server side errors is required.

System Properties

When developing a CWC2-based application, it is sometimes necessary to retrieve information about how a CWC2 Service Instance is configured. The CWC2 JavaScript API provides a method of accessing the value of CWC2 Service Instance configuration parameters that affect an application. They are accessed through a GetProperty method on the global CWCApplication instance by name. The following properties are exposed though this API:

ows_schemas_location
string. URL pointing to the root of a repository of OGC schemas. See http://ogc.dmsolutions.ca for an example
wms_connectiontimeout
integer. Maximum time in seconds that the CWC2 Service Instance will wait for an answer from a WMS server when rendering a layer in the map image.
allow_upload_context
boolean. Controls whether the CWC2 Service Instance allows an application to specify a remote context via URL.
allow_upload_template
boolean. Controls whether the CWC2 Service Instance allows an application to specify a remote template via URL.
validate_template
boolean. Controls validation of the attributes of each tag in the input template. This should be set to true for debugging but may be set to false in a production environment to enhance performance.
default_language
string. Default language specifier. (en-CA or fr-CA)
fonts
array. An array of font names that can be used when rendering point labels.
image_type
string. Output image type (eg: PNG, PNG24, GIF, JPEG).
button_cache_web_path
string. The URL where a browser loads button images from.
tmp_web_path
string. The URL where a browser loads temporary map, scalebar and reference map images from, and where downloadable files are placed (such as when saving a context).
execution_timeout
The amount of time in seconds to allow PHP to process a PHP page. This includes (for now) the time required to draw remote WMS layers which can be lengthy.

Other Considerations

In general, the JSAPI attempts to handle all actions without submitting the current page, thus preserving application state and reducing load on the server. Unfortunately, it is necessary to cause the page to be submitted under the following circumstances:

  • changing the current language of the application. CWC2 provides multilingual interfaces via multiple templates, so when switching languages, a new application template must be loaded and this requires that the page be submitted to the server for processing. The application state is preserved when changing templates.
  • changing the size of the map image. The CWC2 interface uses DHTML layers to display the map image. These layers must be created and positioned as the page loads. The application state is preserved when modifying the map size.
  • loading a new context file. CWC2 JSAPI maintains the current state of the map. Loading a new context file invalidates most of this state. The application state is modified to reflect the new context information.

If the developer allows any of these actions to be taken, then they are also responsible to provide a mechanism for preserving their own state between page submits. The CWC2 JSAPI will manage its own state, but it will not preserve any other state. The CWC2 JSAPI preserves state through the use of hidden form variables (input type="hidden"), and this is the suggested solution for application developers to preserve custom application state.

Object Model Details

As discussed, the CWC2 JSAPI is composed of several JavaScript "objects" that work together in a framework that allows the application developer to access data and make changes to the application state. The remainder of this document describes the properties and methods of these objects in more detail. Following the description of each of the objects is a list of all the events provided by the CWC2 JSAPI event manager.

CWCApplication

The CWCApplication provides the execution context for a CWC2 application. There is a single global CWCApplication object created when the page is loaded. The CWCApplication contains a CWCMapObject that defines the view and layers in the map image. The CWCApplication provides the framework for event handling and error handling.

Constructor

None. The CWC2 JSAPI constructs and initializes a global instance of the CWCApplication during page initialization.

Properties

sid
string.    The session id for the current user session. This value is required when communicating with the CWC2 service instance.
form
string.    The session id for the current user session. This value is required when communicating with the CWC2 service instance.
oMap
CWCMapObject.    The one and only instance of CWCMapObject that defines the current map context.
mouseclick
Array.    An array of two integer values that define the last position that the user clicked the mouse button. The first element contains the X coordinate and the second element contains the Y coordinate.

Methods

RegisterEvent( nEvent, szCallbackFunction )
Register a callback function to be called whenever the specified event is triggered. Valid events are described in CWC2 Events below
Parameters
nEvent - integer. Event ID to register for. See CWC Events for a list of implemented events.
szCallbackFunction - string. The name of a valid javascript function implemented in the template that will be called when the event is triggered.
Returns
boolean - true if the event registration was successful, false otherwise.
UnregisterEvent( nEvent, szCallbackFunction )
Remove event registration for szCallbackFunction from nEvent event types. The callback function will not be called again.
Parameters:
nEvent - integer. Event ID to remove registration from.
szCallbackFunction - string. The name of a previously registered javascript function.
Returns:
boolean - true if the event was unregistered successfully, false if it was not.
RefreshMap()
Refresh the current map view. This commits any outstanding changes.
Parameters:
None.
Returns:
boolean - always returns true.
GetProperty( szPropertyName )
Retrieve a named system property.
Parameters:
szPropertyName - string. The name of the property to retrieve.
Returns:
mixed - returns a value appropriate to the system property that was requested. This method will return false if the property is not found. Some properties may return a boolean true/false, in which case check the Error Manager to see if an error happened requesting the property.
LoadContext( szContext )
Load a context into the current view. The layers in the current view are removed first.
Parameters:
szContext - string. The URL or name of a context file to load.
Returns:
boolean - returns true if the context is not an empty string, false if it is an empty string.
SaveContext( szCallback )
Initiates saving of a context. This function executes asynchronously on the server. When this is finished, the callback function is called with one parameter, the URL to the saved context file.
Parameters:
szCallback - string. The name of a function to call when the context has been saved.
Returns:
boolean - always returns true.

CWCMapObject

The CWCMapObject object represents a set of layers that are rendered to create the composite map image. The CWCMapObject contains properties and methods that affect the map image and view.

Constructor

None. The global application object contains a reference to the one and only Map object.

Properties

minx
float. The minimum X extent in the current map units.
miny
float. The minimum Y extent in the current map units.
maxx
float. The maximum X extent in the current map units.
maxy
float. The maximum Y extent in the current map units.
width
integer. The width of the current view window in pixels.
height
integer. The height of the current view window in pixels.
scale
float. The current ground scale of the map view. The ground scale is an approximation of the distance a unit on the screen represents in the real world. It is calculated from the extents of the current view, the current projection, and the resolution of the output device. In general, output device resolution varies widely and so the scale value is not always a reliable number.
cellsize
float. The size in current map units of a single pixel on the screen.
resolution
float. The number of pixels per inch (DPI) that the output device supports. This is typically between 72 and 96 for modern monitors.
zoomfactor
integer. The amount to zoom in or out by when zooming at a single point.
numlayers
integer. The number of layers in the map.

Methods

GetLayer( nIndex )
return a reference to a CWCLayer object for a given index. If the index is not valid, this method returns false.
Parameters
nIndex - The index of the layer to get.
Return:
An instance of CWCLayer or false if an error occured.
GetLayerByName( szName )
return a reference to a CWCLayer object based on the layer's name. If the name is not valid, this method returns false.
AddWMSLayer( szName, szTitle, szSRS, szConnection, szVersion, szFormat )
create a new CWCLayer object with the given name, title, SRS string, connection string, WMS version number and image format.
Parameters:
szName - string. The name of the layer.
szTitle - string. The title of the layer.
szSRS - string. The projection of the layer.
szConnection - string. The URL to the WMS server.
szVersion - string. The version resource of the WMS server
szFormat - string. The image format to retrieve the image in.
Returns:
boolean - true if the layer was added okay, false if something went wrong
AddGridLayer(szName, szProjection, szColor, szLabelFont, szLabelColor, szLabelSize,szLabelFormat, nMinSubdivide, nMaxSubdivide,fMinInterval, fMaxInterval, fMinArcs, fMaxArcs )
Add a Grid reference layer to the map image.
Parameters:
szName - string. The name of the layer, defaults to "grid"
szProjection - string. The EPSG projection to display the grid layer in
szColor - string. An RGB color to draw the grid in, specified as a comma separated set of RGB values between 0 and 255. "0,0,0" is black and "255,255,255" is white
szLabelFont - string, the font to display grid labels in, either a TrueType font supported by the service instance or "BITMAP" for a built in form. NOTE: at this time, only "BITMAP" is supported. All font names are transparently changed to "BITMAP" and the font_size is always interpreted as a string value.
szLabelColor - string, an RGB color to draw the labels in, specified as a comma separated set of RGB values between 0 and 255. "0,0,0" is black and "255,255,255" is white
szLabelSize -string/integer. If font is set to "BITMAP" then this parameter is a string value, one of "TINY", "SMALL", "MEDIUM", "LARGE", or "GIANT". If font is set to some other font name, then the font is a TrueType font and this parameter is interpreted as an integer value and used as the point size of the font.
szLabelFormat - string, a format specifier for labels. Use "DDMMSS" for DMS or "DDMM" for DM format. See http://mapserver.gis.umn.edu/cgi-bin/wiki.pl?MapServerGrid for more information on formatting grid labels and grids in general.
nMinSubdivide - integer, the minimum number of subdivisions per arc
nMaxSubdivide - integer, the maximum number of subdivisions per arc
nMinInterval - float, the minimum interval for grid spacing in map units (depends on current projection)
nMaxInterval - float, the maximum interval for grid spacing in map units (depends on current projection)
nMinArcs - float, a hint to the subdividing engine to try to produce at least this many subdivisions if possible
nMaxArcs - float, a hint to the subdividing engine to try to produce no more that this many subdivisions if possible
Returns:
boolean - always returns true.
CreateNewLayer( szName, szType )
Add a new layer to the map of a given name and type. This method is used to create "feature" layers. when adding points and rectangles to the map, they are added to a default point or line layer unless this function has been called, in which case they can be added to a named layer of the appropriate type. Valid values for szType are POINT and LINE.
Parameters:
szName - string. The name to give to the newly created layer.
szType - string. The type of layer to add. One of "POINT" or "LINE".
Returns:
boolean - true if the layer was created successfully, false if ti was not.
GetProjection()
Return the projection of the Map as an EPSG code.
Parameters:
none.
Returns:
string - the epsg code in the form "EPSG:xxxxx".
ChangeProjection( szProjection )
Set the projection of the Map to an EPSG code if supported.
Parameters:
szProjection - string. The new projection as an espg code in the form "EPSG:xxxx".
Returns:
boolean - true if the projection was changed, false if an error occurred.
ReprojectPoint( szCallback, fX, fY, szProjectionFrom, szProjectionTo )
Convert a geographic location from one projection to another. This function is asynchronous. The result of the projection is passed to the provided callback function.
Parameters:
szCallback - string. The name of a javascript function to call when the reprojected point is ready. This function should declare two parameters to receive the x and y values. X is passed as the first parameter and y is passed as the second parameter.
fX - float - the x coordinate to convert.
fY
- float - the y coordinate to convert.
szProjectionFrom
- string. The projection of the input point as an espg code in the form "EPSG:xxxx".
szProjectionTo
- string. The output projection as an espg code in the form "EPSG:xxxx".
Returns:
boolean - true if the input parameters were valid, false otherwise.
SetExtents( fX1, fY1, fX2, fY2 )
Set the map extents to x1, y1 and x2,y2. All values are in geographic coordinates in the current projection.
Parameters:
fX1 - float. The minimum x value for the new extents
fY1 - float. The minimum y value for the new extents
fX2 - float. The maximum x value for the new extents
fY2 - float. The maximum y value for the new extents
Returns:
boolean - always returns true.
SetZoomFactor( nFactor )
Set the zoom factor to a new value. nFactor must be greater than or equal to 2.
Parameters:
nFactor - integer. the new zoom factor.
Returns:
boolean - always returns true.
ZoomIn()
Zoom in by the current zoom factor at the center of the view.
Parameters:
None
Returns:
boolean - aways returns true.
ZoomOut()
Zoom out by the current zoom factor at the center of the view.
Parameters:
None
Returns:
boolean - always returns true
ZoomInPos( nX, nY )
Zoom in by the current zoom factor at a specified location. nX and nY are specified in pixels from the top, left corner of the map image. nX must be between 0 and the width of the view. nY must be between 0 and the height of the view.
Parameters:
nX - integer. The x coordinate in pixels to zoom at.
nY - integer. The y coordinate in pixels to zoom at.
Returns:
boolean - returns true if nX and nY are within the map size, false if not.
ZoomOutPos( nX, nY )
Zoom out by the current zoom factor from the specified location. nX and nY are specified in pixels from the top, left corner of the map image. nX must be between 0 and the width of the view. nY must be between 0 and the height of the view.
Parameters:
nX - integer. The x coordinate in pixels to zoom out at.
nY - integer. The y coordinate in pixels to zoom out at.
Returns:
boolean - returns true if nX and nY are within the map size, false if not.
ZoomRect( nMinX, nMinY, nMaxX, nMaxY )
Zoom to a rectangle defined in pixel coordinates. The top left corner of the zoom rectange is nMinX, nMinY and the bottom right corner is nMaxX, nMaxY. nMinX must be less that nMaxX and both must be between 0 and the width of the view. nMinY must be less than nMaxY and both must be between 0 and the height of the view.
Parameters:
nMinX - integer. The left edge of the zoom rectangle in pixels
nMinY - integer. The top edge of the zoom rectangle in pixels
nMaxX - integer. The right edge of the zoom rectangle in pixels
nMaxY - integer. The bottom edge of the zoom rectangle in pixels
Returns:
boolean - returns true if all parameters are within the extents of the map, false if one or more are not.
ZoomFull()
Zoom to the full extents of the current map. The full extents are defined by the extents specified in the Context when it was first loaded.
Parameters:
None
Returns:
boolean - always returns true
ZoomScale( fScale )
Zoom to a floating point scale value at the center of the map.
Parameters:
fScale - float. The new scale value to use. Must be greater than 0.
Returns:
boolean - returns true if fScale is greater than 0, false otherwise
Recenter( nX, nY )
Recenter the map at the pixel coordinates specified. nX and nY are specified in pixels from the top left of the map image. nX must be between 0 and the width of the view. nY must be between 0 and the height of the view.
Parameters:
nX - integer. The x coordinate in pixels to center the view at.
nY - integer. The y coordinate in pixels to center the view at.
Returns:
boolean - returns true if the parameters are within the size of the map, false otherwise.
Refresh()
Refresh the map image. Any outstanding changes to the map or layer objects are actioned at this point. Events may be triggered from calling this method depending on what changes were outstanding.
Parameters:
None
Returns:
boolean - always returns true
SetLayerDrawingOrder( aOrder )
Modify the layer drawing order.
Parameters:
aOrder - Array. An array of layer indexes. Layers are re-ordered as they appear in the array with the layer at index 0 being drawn first (beneath all other layers) and the last index being drawn on top of all layers. For a map with 4 layers, the following array will reverse the drawing order of the layers: Array( 3, 2, 1, 0 ). Note that after setting the layer drawing orders, the layers will appear at the new indexes. In the previous example, the layer at index 3 will now be at index 0.
Returns:
boolean - returns true if the array is the same size as the number of layers in the map and if each layer index is valid, otherwise returns false.
Geo2Pix( fX, fY )
convert geographic coordinates into a pixel location and return the value as an array of two values with X in the first element and Y in the second. fX and fY must lie within the current geographic extents of the map view.
Parameters:
fX - float. The X coordinate to convert to pixel coordinates.
fY - float. The Y coordinate to convert to pixel coordinates.
Returns:
Array - an array containing the converted coordinates with the x coordinate at index 0 and the y coordinate at index 1. This method will return false if the geographic extents lie outside the currently visible extents.
Pix2Geo( nX, nY )
convert pixel coordinates into a geographic location based on the current map units and projection. The return value is two floating point numbers in an array with the X coordinate in the first element and the Y value in the second element. nX and nY must lie within the current view size.
Parameters:
nX - integer. The X coordinate to convert from pixel to geographic units.
nY - integer. The Y coordinate to convert from pixel to geogrphic units.
Returns:
Array - an array containing the converted coordinates with the x coordinate at index 0 and the y coordinate at index 1. This method will return false if the pixel values lie outside the current map size.
GetDistance( fX1, fY1, fX2, fY2 )
return the distance between two pixel locations as a floating point number. The value is calculated as a Pythagorean distance.
Parameters:
fX1 - float. The X coordinate of the first point.
fY1 - float. The Y coordinate of the first point.
fX2 - float. The X coordinate of the second point.
fY2 - float. The Y coordinate of the second point.
Returns:
float - the distance between the two points, in the same units as the values passed in.
ConvertUnit( szUnitIn, szUnitOut, value )
convert a value from szUnitIn to szUnitOut. szUnitIn and szUnitOut are two valid unit specifications. Valid specifications are "INCHES", "FEET", "MILES", "METERS", "KILOMETERS", and "DEGREES". If one of the units is not valid or an error occurs, the return value is -1.
Parameters:
szUnitIn - string. The units to convert the value from. One of "INCHES", "FEET", "MILES", "METERS", "KILOMETERS", "DEGREES", or "PIXELS".
szUnitOut - string. The units to convert the value to. One of "INCHES", "FEET", "MILES", "METERS", "KILOMETERS", "DEGREES", or "PIXELS".
value - float. The value to convert.
Returns:
Float - the converted value, or false if one of the units is not valid.
SetViewSize( nWidth, nHeight )
set the view size to nWidth pixels wide by nHeight pixels high if allowed by the template. Check bAllowResize in the map object to see if resizing is allowed. If resizing is not allowed, this function will return false.
Parameters:
nWidth - integer. The width of the new view in pixels
nHeight - integer. The height of the new view in pixels
Returns:
boolean - returns true if nWidth and nHeight are greater than 0.
AddPoint( szLayerName, oPoint )
Add a point to the map on the named layer. If the layer name is not provided or is not valid, an error will be generated. oPoint is an instance of CWCPoint that represents the point to be added to the layer.
Parameters:
szLayerName - string. The name of the layer to add the point to.
oPoint - CWCPoint. A CWCPoint instance to add.
Returns:
boolean - returns true if the point was added, false if the layer name was not valid or the point object was not valid.
AddRectangle( szLayerName, oRectangle )
Add a rectangle to the map on the named layer. If the layer name is not provided or is not valid, an error will be generated. oRectangle is an instance of CWCRectangle that represents the rectangle to be added to the layer.
Parameters:
szLayerName - string. The name of the layer to add the rectangle to.
oRectangle - CWCRectangle. A CWCRectangle instance to add.
Returns:
boolean - returns true if the rectangle was added, false if the layer name was not valid or the rectangle object was not valid.

CWCLayer

The CWCLayer object represents a single layer of information in a composite map view. Instances of CWCLayer always belong to a CWCMap. The position of the layer in the map is determined by the layer index.

Constructor

None. Use the layer creation methods of the Map object to create new layers.

Properties

name
string. The name of the layer as required by the WMS server that renders this layer, or as set when adding a new layer. Layers can be retrieved from the map object by name.
index
integer. The drawing index of this layer. Indexes start at 0. Index 0 is the first layer to be drawn and is therefore the bottom-most layer when viewing the map.
data
string. A URL provided by the data provider that provides more information about the data.
title
string. A descriptive title for the layer. This is the value that is displayed in legends.
connection
string. A URL that provides the base connection to a WMS server that can render this layer.
srs
string. A space delimited list of EPSG codes that define all the projections supported by this layer
version
string. A WMS version identifier supported by the WMS server that renders this layer
format
string. An image format string that indicates the format to render this layer in
formatlist
string. A space delimited list of image format names that this layer supports
styles
string. A space delimited list of style names that this layer supports
currentstyle
String. The current style that this layer is being rendered with.

Methods

SetStatus( szStatus )
sets the layer status to one of ON, OFF or DELETED. Use "ON" to make a layer visible. Use "OFF" to make a layer invisible. Use "DELETED" to remove a layer permanently. Setting the layer status will not immediately trigger a change in the map view allowing for multiple changes to be made before updating the map view. If the status of one or more layers has been changed when the map is refreshed, a LAYER_STATUS_CHANGED event will be triggered when the map is refreshed.
Parameters
szStatus - string. The new status of the layer, one of "ON", "OFF", or "DELETED".
Returns
boolean - returns true if the status code was valid, false otherwise.
GetStatus()
returns the status of this layer as a string value of "ON", "OFF" or "DELETED".
Parameters
None.
Returns
String. The status code, one of "ON", "OFF", or "DELETED".
SetStyle( szStyle )
sets the style of the layer to the named style. The named style must be one of the names from the valid style list obtained from a call to getLayerStyleList().
Parameters
szStyle - string. The name of the style to select for this layer.
Returns
boolean - returns true if the style is valid, false otherwise.
GetStyleList()
returns an array of valid style names
Parameters
None.
Returns
Array - an array of style names that are valid for this layer.
GetStyle()
returns the name of the current style.
Parameters
None.
Returns
String - the name of the current style, or an empty string if there is no named style for this layer.
SetProjection( szProjection )
sets the projection of the layer to szProjection, which is an ESPG:xxxxx code. The projection code must be valid. Returns true if the projection was correctly set or false if an error occurred.
Parameters
szProjection - string. An epsg projection code to use for this layer. Any features added to this layer are in the coordinates of the projection of the layer, regardless of the projection of the map view. The layer may be in any supported projection, but will be rendered in the map projection.
Returns
boolean - returns true if the projection is valid, false otherwise.
GetType()
return a string identifying the type of this layer. One of "POINT", "LINE", "POLYGON", "RASTER", "ANNOTATION", "QUERY", "CIRCLE", or "GRATICLE".
Parameters
None.
Returns
String - one of "POINT", "LINE", "POLYGON", "RASTER", "ANNOTATION", "QUERY", "CIRCLE", or "GRATICLE"
Promote()
moves the layer towards the top of the drawing order.
Parameters
None.
Returns
boolean - always returns true.
Demote()
moves the alyer towards the bottom of the drawing order.
Parameters
None.
Returns
boolean - always returns true.

CWCRectangle

The CWCRectangle object defines a rectangular region and associates rendering styles with the region. The CWCRectangle object is used with the AddRectangle method on a CWCLayer object to create a rectangular region on a layer. CWCRectangle consists only of properties.

Constructor

CWCRectangle() - return a newly constructed CWCRectangle instance with default values.

Properties

xmin
float. The left edge of the rectangle. The units of this property depend on the projection of the layer that the rectangle is added to.
xmax
float. The right edge of the rectangle. The units of this property depend on the projection of the layer that the rectangle is added to.
ymin
float. The bottom edge of the rectangle. The units of this property depend on the projection of the layer that the rectangle is added to.
ymax
float. The right edge of the rectangle. The units of this property depend on the projection of the layer that the rectangle is added to.
color
String. An RGB color to draw the rectangle in. RGB colors are specified in a comma delimited list of values between 0 and 255, for instance black is "0,0,0", white is "255,255,255".

Methods

None.

CWCPoint

The CWCPoint object defines a geographic point and associates rendering styles with the point. The CWCPoint object is used with the AddPoint method on a CWCLayer object to create a point on a layer. CWCPoint consists only of properties.

Constructor

CWCPoint() - returns a newly allocated CWCPoint object with default values.

Properties

x
float. The X coordinate of the point. The units of the X coordinate depend on the projection of the layer that the point is added to.
y
float. The Y coordinate of the point. The units of the Y coordinate depend on the projection of the layer that the point is added to.
symbol
integer. The index of the symbol to use when rendering the point. Index 0 is a dot. Depending on the CWC2 Service Instance, other symbols may be available to render points differently.
symbol_color
string. An RGB color to draw the symbol in. RGB colors are specified in a comma delimited list of values between 0 and 255, for instance black is "0,0,0", white is "255,255,255".
symbol_outlinecolor
string. An RGB color to draw around the symbol. RGB colors are specified in a comma delimited list of values between 0 and 255, for instance black is "0,0,0", white is "255,255,255".
font
string. The name of a valid font provided by the CWC2 Service Instance, or "BITMAP" to use the built in bitmap font. This value affects the interpretation of font_size. NOTE: at this time, only "BITMAP" is supported. All font names are transparently changed to "BITMAP" and the font_size is always interpreted as a string value.
font_size
string/integer. If font is set to "BITMAP" then this parameter is a string value, one of "TINY", "SMALL", "MEDIUM", "LARGE", or "GIANT". If font is set to some other font name, then the font is a TrueType font and this parameter is interpreted as an integer value and used as the point size of the font.
font_color
string. An RGB color to draw the label in. RGB colors are specified in a comma delimited list of values between 0 and 255, for instance black is "0,0,0", white is "255,255,255".
font_outlinecolor
string. An RGB color to draw around the label. RGB colors are specified in a comma delimited list of values between 0 and 255, for instance black is "0,0,0", white is "255,255,255".
marquee
string. One of "ON" or "OFF". If set to ON, then a solid background is drawn in the font outline color to make the label more visible.
label_position
string. The position of the label relative to the point. One of UL (upper left), UC (upper center), UR (upper right), CL (center left), CC (center center), CR (center right), LL (lower left), LC (lower center) or LR (lower right).
label_x_off
integer. Number of pixels to horizontally offset the label from the point.
label_y_off
integer. Number of pixels to vertically offset the label from the point]

Methods

None.

CWCMLTObject

The CWCMLTObject is used to provide translation of error codes and status messages generated by the javascript API. The error messages are predefined and stored on the server. When a template is loaded, this object is pre-loaded with error messages based on the current language.

Constructor

None. The application object contains a reference to the one and only MLT object.

Properties

None.

Methods

Get( nId, szDefault )
Return the text associated with a given resource ID. If the ID is not defined, the default value is returned.
Parameters
nId - integer. The resource to retrieve.
szDefault - string. The string to return if the resource ID was not found.
Returns
String - the resource associated with nId, or szDefault if it wasn't found.
LoadResource()
Cause the MLT object to reload resources for the current language
Parameters
None.
Returns
boolean - always returns true.
SetLanguage( szLanguage )
Set the language of the MLT object to the passed value. This implicitly calls LoadResource() if the language is passed is not the current language.
Parameters
szLanguage - string. The new language code. Normally this is in the format "lang-COUNTRY", i.e. en-CA or fr-CA.
Returns:
boolean - returns true if the language is valid, false otherwise.

CWCErrorManagerObject

The CWCErrorManagerObject is used to manage errors reported by the JSAPI and CWC2. An instance of the Error Manager is always created in the CWCApplication global instance. When an error occurs in the JSAPI or CWC2, a new error is pushed onto the error manager's stack and the function returns false. The application can then check to see if an error was reported by calling PopLastError which returns false if no errors are available or an array containing one error condition. The array consists of an error code (index 0) and a text message associated with the error (index 1).

There are several error codes defined by the JSAPI as follows:

  • ERR_NOTICE: 0, associated with errors that are informational only
  • ERR_WARNING: 1,associated with error conditions that caused an operation to fail but the application was able to recover or take a default action
  • ERR_CRITICAL: 2, associated with error conditions that caused an operation to fail and the application was not able to take a default action or recover.
  • ERR_FILE_IO: 3, associated with error conditions caused by file IO problems.

Error codes are defined as javascript variables, so it is valid to call oErrorManager.Error( ERR_NOTICE, "hey, something happened" );

Applications can define there own error codes for specific purposes and use the JSAPI error manager to mange them. Because the JSAPI is an evolving work, application defined error codes should start at ERR_NEXT, which is the next available error code and should increment the value of ERR_NEXT as follows:

var MyErrorCode = ERR_NEXT ++;

Construtor

None. The global application object contains a reference to the one and only error manager.

Properties

None.

Methods

Error( nId, szError )
Set an error in the error manager. nId is an error type and szError is the text associated with the error.
Parameters:
nId - integer.The error code.
szError - string. The text associated with the error, hopefully informative about why the error happened.
Returns:
boolean - always returns true.
PopLastError()
Returns an array of { ErrorType, ErrorText } or false if no error occured. To access multiple errors, keep calling this function until it returns false.
Parameters:
None.
Returns
Array - an array containing the error code at index 0 and the error text at index 1 or false if there were no errors to report.
GetServerErrors()
Force the application to check with the server to see if errors occurred during processing. This happens during normal processing and should not be required.
Parameters
None.
Returns
boolean - always returns true.

Event Details

The CWC2 JavaScript API provides an event handling mechanism that informs your application of changes in the application, map or a layer object as they happen. The CWC2 event mechanism using a registration system that links javascript function names to event ids. When a change happens, it triggers events for one or more event ids by calling all the function names that were registered for the appropriate event ids. To register a function to be called when an event happens, pass the event id and a string containing the javascript function name to the RegisterEvent method of the global CWCApplication object.

Functions that are called in response to events happening are "callback" functions. Callback functions should define no parameters.

Event IDs are actually JavaScript variabled created by the CWC2 JavaScript API that contain the event ID of the associated event. When calling the RegisterEvent function, pass one of these variables as the first parameter. The following Event IDs are defined:

MAP_EXTENT_CHANGED
This event is triggered when the geographic extents of the map view are modified. This normally happens as the result of the user navigating the map in some way, but it can be triggered by a programmatic manipulation of the map view as well.
goCWCApp.RegisterEvent( MAP_EXTENT_CHANGED,
                        "myMapExtentChanged" );
// called when the map extents change
function myMapExtentChanged()
{
    oMap = goCWCApp.oMap;
    szExtents = "(" + oMap.minx + "," + oMap.miny + "),
                 (" + oMap.maxx + "," + oMap.maxy + ")";
    alert("map extents changed to " + szExtents);
}
MAP_PROJECTION_CHANGED
This event is triggered when the projection of the map is changed.
goCWCApp.RegisterEvent( MAP_PROJECTION_CHANGED,
                        "myMapProjectionChanged" );
// called when the map projection changes
function myMapProjectionChanged()
{
  alert("map projection changed to");
}
MAP_NEW_LAYER_ADDED
This event is triggered when one or more layers have been added to the current map.
goCWCApp.RegisterEvent( MAP_NEW_LAYER_ADDED,
                        "myLayerAdded" );
// called when a layer is added to the map
function myLayerAdded()
{
  alert("the user added a layer to the map");
}
LAYER_STATUS_CHANGED
This event is triggered when the status (visibility or a layer was deleted) of a layer is changed.
goCWCApp.RegisterEvent( LAYER_STATUS_CHANGED,
                        "myLayerStatusChanged");
// called when a layer status changes
function myLayerStatusChanged()
{
  alert("a layer changed status!");
}
LAYER_ORDER_CHANGED
This event is triggered when the drawing order of layers has been changed.
goCWCApp.RegisterEvent( LAYER_ORDER_CHANGED,
                        "myLayerOrderChanged" );
// called when a layer has changed its drawing order
function myLayerOrderChanged()
{
  alert("layer order changed");
}
MOUSE_CLICKED
This event is triggered when the user clicks on the map image.
goCWCApp.RegisterEvent( MOUSE_CLICKED,
                        "myMouseClicked");
// called when the mouse is clicked on the map
function myMouseClicked()
{
  oMap = goCWCApp.oMap;
  mousePos = "(" + oMap.mouseclick[0] + ","
                 + oMap.mouseclick[1] + ")";
  alert("mouse clicked at " + mousePos);
}
NEW_ELEMENT_ADDED
This event is triggered when a new element (point or rectangle) is added to the map.
goCWCApp.RegisterEvent( NEW_ELEMENT_ADDED,
                        "myNewElement" );
// called when a new element is added
   to the map function myNewElement()
{
  alert("new element added");
}
ERROR_OCCURRED
This event is triggered when one or more errors occurred during server side processing
goCWCApp.RegisterEvent( ERROR_OCCURRED,
                        "myErrorHandler" );
// called when a new element is added to the map
function myErrorHandler()
{
  while((lastErr=goCWCJSAPI.oErrorManager
         .PopLastError) != false)
  {
    switch( lastErr[0] )
    {
      case ERR_NOTICE:
        break; //ignore notices
      case ERR_WARNING:
        alert( "Warning: " + lastErr[1] );
        break;
      case ERR_CRITICAL:
        alert( "Error: " + lastErr[1] );
        break;
      case ERR_FILE_IO alert( "IO Error: "
                              + lastErr[1] );
        break;
      default:
        alert( "Unknown Error: " + lastErr[1] );
    }
  }
}

Printer Friendly

 

Docs

Installation - Linux

Application Dev Guide

Widget Guide

JavaScript API

Chameleon Wiki

Licensing

 

Related Links

MapServer Docs

 

Contact Information

Chameleon Users List