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.
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.
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.
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.
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.
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.
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".
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]
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.
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] );
}
}
}