CWC2 JavaScript API

Introduction

The CWC2 JavaScript API (JSAPI) is a programming interface for creating client applications in JavaScript that utilize the capabilities of a CWC2 Service Instance. Client applications can use the JSAPI to customize navigation and display of maps in several ways.

CWC2 provides the capability to create very complex applications using only HTML-based templates and existing widgets. As well, it is possible to modify existing widgets or create entirely new widgets to perform additional functions. However, this customization requires knowledge of the internal architecture of CWC2, knowledge of the PHP programming language, and administrative 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 (as is Java). The language does not contain the ability to declare classes and methods in those classes. It does provide a pseudo-object mechanism through the 'this' identifier and the 'prototype' property. The end result is that JavaScript developers can create pseudo-objects that contain methods and properties. It is assumed that developers using the JSAPI are experienced JavaScript developers that are familiar with these concepts.

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 operates in "JavaScript" mode. This means that, whenever possible, user actions do not result in the application page being submitted. Instead, the JSAPI communicates 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 results in a more responsive application that puts less load on the server. For this reason, it may be desirable to incorporate the JSAPI even when no custom development is done.

Developing Using the JSAPI

In order to use the JSAPI for more than making CWC2 applications run primarily on the client side, the application developer typically adds 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 example, 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;
}

Developing 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 extents 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 that enables 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 returns "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 those errors and 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 JSAPI provides a method of accessing the value of CWC2 Service Instance configuration parameters that affect an application. They are accessed by name through a GetProperty method on the global CWC2 Application instance. The following properties are exposed though this API:

ows_schemas_location: string. URL pointing to the root of a repository of OGC schemas. http://ogc.dmsolutions.ca is an example of such a root directory.
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 (e.g., 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 (e.g., 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, scale bar, 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, under the following circumstances it is necessary to cause the page to be submitted :

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 which 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 you allow any of these actions to be taken, then you are also responsible for providing a mechanism for preserving state between page submits. The CWC2 JSAPI manages its own state, but it does not preserve any other state. The CWC2 JSAPI preserves state through the use of hidden form variables (i.e., input type="hidden"), and this is also the suggested solution for preserving custom application state.

Object Model Details

As previously discussed, the CWC2 JSAPI is composed of several JavaScript "objects" working together in a framework that allows an application developer to access data and make changes to an application's 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 relevant events provided by the CWC2 JSAPI event manager.

CWCApplication

The CWCApplication object provides the execution context for a CWC2 application. A single global CWCApplication object is 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 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 name of the HTML form that contains all the CWC2 widgets.

oMap

CWCMapObject.    The one and only instance of CWCMapObject that defines the current map context.

mouseclick

array.    An array of two integer values that defines the last position at which 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 Events Details section below.
Parameters

nEvent - integer. Event ID to register for. See Event Details section for a list of implemented events.

szCallbackFunction - string. The name of a valid JavaScript function implemented in the template that is 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" otherwise.

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 returns "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 while 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.

AppendContext( szContext )

Append a context into the existing context. The layers from the new context are added into the existing context.

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 )

Initiate saving of a context. This function executes asynchronously on the server. When this save 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 and 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 current map units.

miny

float. The minimum Y extent in current map units.

maxx

float. The maximum X extent in current map units.

maxy

float. The maximum Y extent in 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. For example, a value of "2" makes the extent twice as large when zooming out and one-half as large when zooming in.

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 occurs.

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".

szName - The name of the layer to get.

Return:

An instance of CWCLayer or "false" if an error occurs.

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 successfully, "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 font. Note: At this time, only "BITMAP" is supported. All font names are transparently changed to "BITMAP" and the label 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.

fMinInterval - float. The minimum interval for grid spacing in map units (depends on current projection).

fMaxInterval - float. The maximum interval for grid spacing in map units (depends on current projection).

fMinArcs - float. A hint to the subdividing engine to try to produce at least this many subdivisions, if possible.

fMaxArcs - 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, bDisplay )

Add a new layer to a map of a given name and type. This method is used to create "feature" layers. When points and rectangles are added to a 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.

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".

bDisplay - integer. Optional. Value can be 0 or 1. It is set to 0 by default. If set to 0, the new layer will have a metadata called CWC_TMP_LAYER which will be used in the Legend in order to not display the layer.

Returns:

boolean. "true" if the layer was created successfully, "false" otherwise.

GetProjection( )

Return the projection of a Map as an EPSG code.

Parameters:

None.

Returns:

string. The EPSG code in the form "EPSG:xxxxx".

ChangeProjection( szProjection )

Set the projection of a 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 declares 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.

Parameters:

nFactor - integer. The new zoom factor. Must be greater than or equal to 2.

Returns:

boolean. Always returns "true".

ZoomIn( )

Zoom in by the current zoom factor at the center of the view.

Parameters:

None.

Returns:

boolean. Always 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 rectangle 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 layer at the last index being drawn on top of all layers. For a map with four layers, the following array will reverse the drawing order of the layers: Array( 3, 2, 1, 0 ). Note: After setting the layer drawing orders, the layers appear at the new indexes. In the previous example, the layer previously at index 3 is 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 returns "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. 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 geographic 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", "DEGREES" and "PIXELS". If one of the units is not valid or an error occurs, the return value is "false".

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 returns "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 is 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 CWCMap 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 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 in which format to render this layer.

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 )

set a layer's 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 does not immediately trigger a change in the map view, which allows 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 is 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( )

return the status of this layer as a string value of "ON", "OFF", or "DELETED".

Parameters

None.

Returns

string. Returns the status code, one of "ON", "OFF", or "DELETED".

SetStyle( szStyle )

set the style of the layer to the named style, which must be one of the names from the valid style list obtained from a call to GetStyleList( ).

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( )

return an array of valid style names.

Parameters

None.

Returns

array. An array of style names that are valid for this layer.
GetStyle( )

return 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 )

set 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.

Parameters

None.

Returns

String - one of "POINT", "LINE", "POLYGON", "RASTER", "ANNOTATION", "QUERY", "CIRCLE", or "GRATICLE".

Promote( )

move the layer towards the top of the drawing order.

Parameters

None.

Returns

boolean. Always returns "true".

Demote( )

move the layer 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 has no methods, only 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 to which the rectangle is added.

xmax

float. The right edge of the rectangle. The units of this property depend on the projection of the layer to which the rectangle is added.

ymin

float. The bottom edge of the rectangle. The units of this property depend on the projection of the layer to which the rectangle is added.

ymax

float. The right edge of the rectangle. The units of this property depend on the projection of the layer to which the rectangle is added.

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 example, black is "0,0,0" and 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 has no methods, only 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 example, black is "0,0,0" and 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 example, black is "0,0,0" and 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 font in. RGB colors are specified in a comma delimited list of values between 0 and 255. For example, black is "0,0,0" and white is "255,255,255".

font_outlinecolor

string. An RGB color to draw around the font. RGB colors are specified in a comma delimited list of values between 0 and 255. For example, black is "0,0,0" and 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 preloaded 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 the resource 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 passed is not the current language.

Parameters

szLanguage - string. The new language code. Normally this is in the format "lang-COUNTRY", e.g., 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 an array containing one error condition or "false" if no errors are available. 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 ++;

Constructor

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( )

Return an array of error information, or "false" if no error occurred. 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 check happens during normal processing and forcing it 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 uses a registration system that links JavaScript function names to event ids. When a change happens, it triggers events 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 variables 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 also be triggered by a programmatic manipulation of the map view.
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 of a layer (i.e., its visibility or it is deleted) 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 (i.e., a 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 occur 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] );
    }
  }
}