CWC2 Application Developer's Guide
 

Introduction

The CWC2 incorporates the ability to set up new applications quickly from a common pool of "widgets" that can be placed in an HTML template file. While these widgets provide fixed pieces of functionality, the representation of the widgets is usually highly configurable.

This guide presents a tutorial approach to building a basic CWC2 Application Template and then describes the advanced widget configuration. It assumes that you have access to a configured CWC2 Service Instance.

Key Concepts

Web Mapping Service (WMS)
WMS is an OGC standard that defines a service that provides access to geographic information over the Internet using a standard protocol. WMS supports a variety of different requests for accessing images and metadata.
Template
A CWC2 Application Template is an HTML file that includes CWC2 tags. The template is passed to a CWC2 Service Instance which turns it into an actual mapping application.
Context
A Context is an XML description of the geographic data. The CWC2 Service Instance uses a Context to determine what images to request from which WMS servers in order to display a Map to the user. Most CWC2 developers do not create their own Contexts, but use existing ones instead. For Context examples, please visit http://www2.dmsolutions.ca/msapps/contexts/.
Widget
A Widget is the basic element of a CWC2 application. Widgets are represented by XML-like tags in a CWC2 Template. A wide variety of widgets are included with the basic CWC2 Service Instance, enough to allow the development of complex Web mapping applications.
CWC2 Service Instance
This is the heart of CWC2. The CWC2 Service Instance is an Internet-accessible service that can interpret a CWC2 Application Template and load a Context to create a fully interactive Web mapping application.

Configuring CWC2

For the purpose of this guide, it is assumed that you have access to a properly configured CWC2 Service Instance. See the CWC2 Administrator's Guide for information on setting up and configuring a CWC2 Service Instance.

Communicating with a CWC2 Service Instance

A CWC2 Service Instance supports two parameters that can be passed to it via URL parameters. The parameters that can be passed are:

TEMPLATE
This parameter allows you to specify the location of an application template. The value of this parameter can be either a path to a file on the local file system of the CWC2 Service Instance or a URL to an Internet-accessible template file.

NOTE: The CWC2 Service Instance can be configured to restrict access to files in particular directories within its local filesystem, or to prevent access entirely. Similarly, it can be configured to prevent loading a template from a URL. In either case, the file specified in this parameter must be an HTML file.

Example:

    TEMPLATE=http://myserver/templates/myTemplate.html
CONTEXT
This parameter allows you to specify the location of a Context file. The value of this parameter can be either a path to a Context file on the local file system of the CWC2 Service Instance or a URL to an Internet-accessible Context file.

NOTE: The CWC2 Service Instance can be configured to restrict access to files in particular directories within its local filesystem, or to prevent access entirely. Similarly, it can be configured to prevent loading a Context from a URL. In either case, the file specified in this parameter must be an XML file.

Example:

    CONTEXT=http://myserver/contexts/myContext.xml

Widget Basics

Widgets are represented in an HTML template using familiar HTML-like notation. (Actually, the tags conform to XML specifications, which are a super-set of HTML.) As such, tags are written using the standard HTML opening and closing brackets with the additional requirement that the tags be complete. This means that every tag must have a closing element. There are two valid ways of closing an XML tag. The first is to include a "/" before the closing bracket of the first tag. The second is to include a second tag that uses the same name as the opening tag but starts with a "/". Here are examples of minimal CWC2 tags that are valid:

<CWC2/>

and

<CWC2></CWC2>

These simple tags don't actually represent any widgets and would be ignored by the CWC2 Service Instance. In order to create a tag that represents a widget, you need to add a TYPE attribute to the tag:

<CWC2 TYPE="WidgetName"/>

This tag represents a Widget called "WidgetName". There isn't a widget available by that name, so the CWC2 Service Instance would generate an error if you included this in an actual template. The list of available widgets is documented in the CWC2 Core Widget Reference. Your CWC2 Service Instance administrator may also have created additional widgets.

Most widgets will also require some configuration values. These values are normally specified in one of two ways. The first, and most common, way is to specify a value in the CWC2 tag in the same way the TYPE attribute is specified. For instance:

<CWC2 TYPE="WidgetName" TEST="false"/>

This creates a widget of TYPE WidgetName with a TEST attribute that is set to the string "false". Some widgets require attributes to be passed as nested tags inside a CWC2 tag. For instance:

<CWC2 TYPE="WidgetName">
<TEST value="1"/>
<TEST value="2"/>
</CWC2>

This creates the same widget but allows for multiple copies of the nested tags. Nested tags have the same formatting restrictions as CWC2 tags in that they must be closed. Widgets that require nested tags will specify the format for the nested tags in their documentation.

The CWC2 Widget Documentation provides sample tags for all the widgets in which the type of value for each attribute is provided. All attributes in a tag are written as string values in the template, but the widget will interpret the values as specified in the documentation. Any errors in interpretation will generate an error message when the template is processed by the CWC2 Service Instance.

In the documentation, you will also see that some attributes are in red. These attributes are mandatory and must be specified in the template. Other attributes are optional and normally have reasonable default values. You will only need to specify optional parameters if you want to modify the "normal" behaviour or appearance of a widget.

Building a Template

This section of the guide will step you through the creation of a basic template, with a CWC2 Service Instance, which can be used to create a simple Web Mapping application . This section assumes that you have access to a properly configured CWC2 Service Instance and a Context file.

Step 1 - Where to begin

You will typically create a new CWC2 application by either copying an existing template or starting a brand new template. In this example, start with a brand new template so you can see the whole process. Create a new, empty HTML document in the editor of your choice and add the necessary "html", "head", and "body" tags.

In order for the CWC2 Service Instance to work correctly, there are several formatting requirements for any template. These are:

NOTE: The stylesheet link is actually optional, but it is usually highly desirable to include it in order to allow widgets to obtain their default settings and allow customization of these settings.

A sample of a minimum HTML template that is correctly configured for a CWC2 Service Instance is:

<html>
<head>
<title>Widgets</title>
<link href="cwc2.css" rel="stylesheet" type="text/css">
</head>
<body onload="CWC2OnLoadFunction()">
<form></form>
</body>
</html>

Step 2 - Adding a Map Widget

The basic element of any mapping application is a map. The CWC2 Widget that represents a map is the MapDHTMLWidget widget, which requires the following attributes:

Additional optional attributes are as follows: VISIBLE, ENABLED, MARQUEECOLOR, MARQUEEWIDTH, MARQUEEHEIGHT, MARQUEEVERTICALIMAGE, MARQUEEHORIZONTALIMAGE, MINSCALE, MAXSCALE, and ALLOWRESIZE. (Detailed information can be found in the CWC Widget Documentation.)

Here is what the tag looks like as implemented in this example:

<CWC2 TYPE="MapDHTMLImage" VISIBLE="true" WIDTH="400"
HEIGHT="300" ALLOWRESIZE="true" MARQUEECOLOR="#FF3333"
MARQUEEWIDTH="2" MINSCALE="1"/>

All widgets must be added inside the <form></form> tag on the page, but can be inline with any other HTML formatting such as tables. Here is an example of how the map image widget might be included in the default template from before:

<html>
<head>
<title>Widgets</title>
<link href="cwc2.css" rel="stylesheet" type="text/css">
</head>
<body onload="CWC2OnLoadFunction()">
<form>
<table border="0" cellspacing="2" cellpadding="0">
<tr>
<td colspan="3" align="center"><CWC2 TYPE="MapDHTMLWidget"
VISIBLE="true" WIDTH="400" HEIGHT="300" ALLOWRESIZE="true"
MARQUEECOLOR="#FF3333" MARQUEEWIDTH="2" MINSCALE="1"/></td>
</tr>
</table>
</form>
</body>
</html>

Step 3 - Ready for Testing

Your template is now functional and ready to be tested. To test the template you need only add it as a URL parameter to the main CWC2 Service Instance, and specify a Context as well. For example:

<url to service instance>/cwc2.php?TEMPLATE=myApp.html&CONTEXT=myContext.xml

If your template is working properly, you should see a map on the resulting page with an image of the data in your Context. This forms the basis of any mapping application, but isn't very useful yet. In the next step you will add other widgets to improve the application's usefulness.

Step 4 - Adding Navigation

In the previous step you were able to verify that your template was indeed working. In this step you will add two additional widgets that allow the user of your application to zoom in and out.

To add a zoom in tool to your template, you will need to add a CWC2 widget of TYPE "ZoomIn". This widget has the following required attributes:

The optional attributes are as follows: VISIBLE, ENABLED, IMAGEWIDTH, IMAGEHEIGHT, IMAGETIP, IMAGECLASS, IMAGESTYLE, TOOLSET, IMAGESELECTED, IMAGEHOVER, DEFAULT, WIDGETSTYLE, and MINIMUMZOOMRECTANGLE. (Detailed information can be found in the CWC Widget Documentation.)

Here is what the tag looks like as implemented in this example:

<CWC2 TYPE="ZoomIn" VISIBLE="true" IMAGE="images/tool_zoomin_off.gif"
IMAGESELECTED="images/tool_zoomin_on.gif" IMAGEHOVER="images/tool_zoomin_over.gif"
IMAGETIP="Zoom In" IMAGEWIDTH="24" IMAGEHEIGHT="24" TOOLSET="Navigation"/>

To add a zoom out tool to your template you will need to add a CWC2 widget of TYPE "ZoomOut". This widget has the following required attributes:

The optional attributes are as follows: VISIBLE, ENABLED, IMAGEWIDTH, IMAGEHEIGHT, IMAGETIP, IMAGECLASS, IMAGESTYLE, TOOLSET, IMAGESELECTED, IMAGEHOVER, DEFAULT, and WIDGETSTYLE. (Detailed information can be found in the annex in the back of this guide.)

Here is what the tag looks like as implemented in this example:

<CWC2 TYPE="ZoomOut" VISIBLE="true" IMAGE="images/tool_zoomout_off.gif"
IMAGESELECTED="images/tool_zoomout_on.gif" IMAGEHOVER="images/tool_zoomout_over.gif"
IMAGETIP="Zoom Out" IMAGEWIDTH="24" IMAGEHEIGHT="24" TOOLSET="Navigation"/>

Adding these tags to your template should result in something like the following:

<html>
<head>
<title>Widgets</title>
</head>
<body onload="CWC2OnLoadFunction()">
<form>
<table border="0" cellspacing="2" cellpadding="0">
<tr>
<td colspan="3" align="center"><CWC2 TYPE="MapDHTMLImage"
VISIBLE="true" WIDTH="400" HEIGHT="300" ALLOWRESIZE="true"
MARQUEECOLOR="#FF3333" MARQUEEWIDTH="2" MINSCALE="1"/></td>
<td valign=top><CWC2 TYPE="ZoomIn" VISIBLE="true"
IMAGE="images/tool_zoomin_off.gif" IMAGESELECTED="images/tool_zoomin_on.gif"
IMAGEHOVER="images/tool_zoomin_over.gif" IMAGETIP="Zoom In"
IMAGEWIDTH="24" IMAGEHEIGHT="24" TOOLSET="Navigation"/><br>
<CWC2 TYPE="ZoomOut" VISIBLE="true" IMAGE="images/tool_zoomout_off.gif"
IMAGESELECTED="images/tool_zoomout_on.gif" IMAGEHOVER="images/tool_zoomout_over.gif"
IMAGETIP="Zoom Out" IMAGEWIDTH="24" IMAGEHEIGHT="24"
TOOLSET="Navigation"/></td>
</tr>
</table>
</form>
</body>
</html>

Save your template, load and reload your application. You should have a map and two navigation buttons. The new navigation tools provide you with the ability to zoom into and out of the map view.

This step concludes the basics of building a CWC2 Application Template. You can now add additional widgets to the template and investigate their behaviour in the application. There are many aspects of configuring widgets that are not addressed in this document, so experimentation is encouraged. Try the parameters of each CWC2 Widget to discover how flexible they are and how easily you can generate fully customized web mapping applications without writing any code.

Advanced Customization

In addition to the basic customization provided for every widget through its attributes, there are several additional ways of achieving a high level of customization. These are:

Customizing with CSS Files

All core widgets provided with the CWC2 are designed to allow application developers to configure an application's appearance using CSS files. The CWC2 provides default CSS files that define all the classes and styles used in the default appearance of CWC2 applications.

It is assumed that developers wishing to control the appearance of applications using CSS files are already familiar with CSS.

Widget Classes

The first CSS stylesheet that can be modified is cwc2.css, which defines the styles used by the widgets in the main application template. This file should be accessible from the same URL as the CWC2 service instance. For example, if the service instance is installed at http://my.server.com/cwc2/cwc2.php, then the CSS file would be accessible from http://my.server.com/cwc2/cwc2.css.

The developer can include this file in an application by including the following HTML link tag in the HEAD section of the application template:

<link href="cwc2.css" rel="stylesheet" type="text/css">

Because the CWC2 Service Instance is generating the application, the lack of a URL in the href of the link tag means that it is referring to the default CSS file provided with the service instance. To reference a different CSS file on another server, simply replace the href with a valid URL to the desired CSS file.

The following classes are defined in the default cwc2.css file:

.CWCExtentWidgetClass
This class defines the appearance of the Extent widget's display. The Extent widget displays one of the current extents of the map image. If the application is not using the JavaScript API, then the class is applied to a <p> tag. If the application is using the JavaScript API, then the class is applied to a <input type="text"> tag.
.CWCLabelClass
This class defines the appearance of all labels. Many widgets can be displayed with a label. The class is applied to a <p> tag containing the label text.
.CWCMapUnitClass
This class defines the appearance of the MapUnit widget's output, which displays a value such as "degrees" or "meters" depending on the current coordinate system in use. If the application is not using the JavaScript API, then the class is applied to a <p> tag. If the application is using the JavaScript API, then the class is applied to an <input type="text"> tag.
.CWCProjectionLabelWidgetClass
This class defines the appearance of the ProjectionLabel widget's output, which is a textual description of the current projection in which the map is displayed. If the application is not using the JavaScript API, then the class is applied to a <p> tag. If the application is using the JavaScript API, then the class is applied to an <input type="text"> tag.
.CWCRulerResultWidgetClass
This class defines the appearance of the RulerResult widget's output. The Ruler measures approximate distances on the map image. The RulerResult widget displays the cumulative distance in real time.The class is applied to an <input type="text"> tag.
.CWCCursorPositionWidgetClass
This class defines the appearance of the CursorPosition widget's output. The CursorPosition widget tracks the location of the cursor over the map image (in geographic coordinates) in real time.The class is applied to an <input type="text"> tag.
.CWCTimeFilterLabelClass
This class defines the appearance of labels displayed in the TimeFilter widget. The class is applied to <p> tags.
.CWCTimeFilterInputClass
This class defines the appearance of input boxes used in the TimeFilter widget. The class is applied to <select> tags.
.CWCHelpTitle1
This class defines the appearance of level 1 titles in help templates. The class is applied to <p> tags.
.CWCHelpTitle2
This class defines the appearance of level 2 titles in help templates. The class is applied to <p> tags.
.CWCHelpTitle3
This class defines the appearance of level 3 titles in help templates. The class is applied to <p> tags.
.CWCHelpTitle4
This class defines the appearance of level 4 titles in help templates. The class is applied to <p> tags.
.CWCHelpText
This class defines the appearance of text that appears in help templates. The class is applied to <p> tags.

Popup Classes

The second CSS stylesheet that can be modified is the popup.css stylesheet. This stylesheet controls the appearance of popup dialog boxes generated by some widgets. The popup.css file is located in the widgets directory of the CWC2 Service Instance installation, and can be referenced via http://my.server.com/cwc2/widgets/popup.css as described in the previous example. Unfortunately, it is not possible to replace the stylesheet directly in popup dialogs, but it is possible to specify a new CSS stylesheet for all popup dialogs to use in the main application template, by using a SharedResource widget. The format of this widget is as follows:

<SharedResource NAME="PopupCSSt" VALUE="<url-to-custom-stylesheet>"/>

By placing this tag anywhere in the application template, all popup dialogs will use the custom stylesheet rather than the default one provided.

The following classes should be defined in a custom popup stylesheet:

.page
Defines the page style. Basic usage sets the background colour.
.layoutTable
Defines the style of the main layout table. Basic usage sets the background colour, which acts as an outline.
.titleArea
Defines the style for the title table. Every popup has a title table as the first table within the layout table
.title
Defines the style for the title text. Every popup has a title. This sets the font, size, colour, etc.
.contentArea
Defines the style of content layout tables. Basic usage sets the background colour of the content areas.
.subLayoutTable
Defines the style of secondary (nested) layout tables. Basic usage sets the background colour, which acts as an outline. Similar in usage to .layoutTable.
.subContentArea1
Defines the style of tables or cells in secondary layout tables. Basic usage sets the background colour of a subContent area. This allows for more advanced designs and is intended to be used with .subLayoutTable (i.e., either styling cells or nested-tables).
.subContentArea2
Defines an alternate style of tables or cells in secondary layout tables. Used in the same way as .subContentArea1.
.helpArea
Defines the style of the help area. Basic usage sets the styling of the <p> that surrounds the help text.
.label
Defines the style of text labels. Basic usage sets the size, colour, and font of any labels of input elements.
.note
Defines the style of text notes. Basic usage sets the size, colour, and font of any small notes. Also used in the legend for small text.
.text
Defines the style of text blocks. Basic usage sets the size, colour, and font of any <p>, <span>, or <div> tags.
.list
Defines the style of ordered and unordered lists. Basic usage sets the size, colour, and font of any <ul> or <ol> tags.
.listItem
Defines the style of list items. Basic usage sets the size, colour, and font of any <li> tags. Normally would be the same as .list, but allows more advanced techniques to be used.
.inputBox
Defines the style of text input elements. Basic usage sets the font and size of any input elements' text. More advanced usage sets the styling of the input area as well.
.inputList
Defines the style of list input elements. Basic usage sets the font and size of any input elements' text. More advanced usage sets the styling of the input area as well.
.nnInputWrap
Workaround to define the style of input elements for nn4.x. Sets the font and size of input elements' text.

Customizing Text Buttons

Text buttons are dynamically generated images that are formatted in a specific way. Text buttons are used as the interface for many widgets that pop up a dialog box. They were originally developed to allow for simple translation of buttons in the application template (simple in that only having to provide translated text, not generate a set of new buttons). Text buttons are very flexible elements and, because of this, they can seem quite complex. However, with only a few simple changes in this area, the appearance of an application can be dramatically altered.

Text Button Components

Before describing how to customize text buttons in an application, it is necessary to define what a text button is and how it is dynamically built. A text button is a single graphic image that is composed of several components:

The two components of a text button are its border and its center. The border is composed of eight (8) separate graphic images that can be individually specified to allow for the creation of complex buttons.

The center portion is the rectangular area outlined by the border and its size is determined by the overall size specified less the border widths/heights. The center is filled with a background color. An optional background graphic is aligned centrally within the center area if it doesn't fill it, or is cropped if it is too large. The button graphic is placed at the left edge of the center portion and is vertically centered in the area. The label is drawn and aligned horizontally in the remaining horizontal area between the right edge of the graphic and the right edge of the center portion.

The following table demonstrates the layout of a full text button:

TBB_TOPLEFT_IMAGE TBB_TOP_IMAGE TBB_TOPRIGHT_IMAGE
TBB_LEFT_IMAGE
IMAGE LABEL
TBB_RIGHT_IMAGE
TBB_BOTTOMLEFT_IMAGE TBB_BOTTOM_IMAGE TBB_BOTTOMRIGHT_IMAGE

NOTE: The prefix "TBB" is being used in the above table (instead of the proper "TEXTBUTTONBORDER") for visual purposes only.

Any widget that uses a TextButton as its graphical representation has all the attributes of the TextButton group. (See CWC2 Widget Documentation.) Because the number of attributes is quite large, it is inefficient for an application developer to repeat them for every widget, especially since most buttons will share many of the same values. It is also difficult to modify the style of all buttons (e.g., changing a background color), since every widget must be changed individually. Finally, popups created by widgets also use TextButtons and these popups are not generally modifiable by the application developer. To solve these problems, the TextButton will take its values from the following places, in order of appearance:

TextButton SharedResource

If a particular attribute is provided as part of a widget's tag then that value will take precedence over all other values. Any values not provided by the widget's tag will be initialized from a TextButton SharedResource if it is available. Otherwise, the documented default values will be used. The structure of the TextButton SharedResource is as follows:

<CWC2 TYPE="SharedResource" NAME="TextButton">
<TEXTBUTTONCOLOR VALUE="5070A8"/>
<TEXTBUTTONWIDTH VALUE="124"/>
<TEXTBUTTONHEIGHT VALUE="28"/>
<TEXTBUTTONBACKGROUNDIMAGE VALUE=""/>
<TEXTBUTTONBORDER_TOPLEFT_IMAGE VALUE="images/tl.png"/>
<TEXTBUTTONBORDER_TOP_IMAGE VALUE="images/t.png"/>
<TEXTBUTTONBORDER_TOPRIGHT_IMAGE VALUE="images/tr.png"/>
<TEXTBUTTONBORDER_RIGHT_IMAGE VALUE="images/r.png"/>
<TEXTBUTTONBORDER_BOTTOMRIGHT_IMAGE VALUE="images/br.png"/>
<TEXTBUTTONBORDER_BOTTOM_IMAGE VALUE="images/b.png"/>
<TEXTBUTTONBORDER_BOTTOMLEFT_IMAGE VALUE="images/bl.png"/>
<TEXTBUTTONBORDER_LEFT_IMAGE VALUE="images/l.png"/>
<TEXTBUTTONPADDING VALUE="2"/>
<TEXTBUTTONNUDGE VALUE="0"/>
<LABELCOLOR VALUE="FFFFFF"/>
<LABELFONT VALUE="../etc/arial.ttf"/>
<LABELALIGN VALUE="left"/>
<LABELFONTSIZE VALUE="10"/>
<LABELANTIALIAS VALUE="true"/>
<USETEXTBUTTONCACHE VALUE="true"/>
</CWC2>

The TextButton SharedResource is also used to define default values for all popup dialogs that incorporate TextButtons. Using TextButtons on popup dialogs is essential to supporting multilingual applications and to allowing for customized look and feel.

Customizing Projections

The ProjectionSelector and ProjectionLabel widgets provide a convenient mechanism for choosing the projection in which to display a map and for the user to see what that projection is. CWC2 currently supports only projections that are defined in European Petroleum Survey Group (EPSG) code format, such as EPSG:42304 (NRCan LCC for Canada). Unfortunately, these codes have very little meaning to most users.

In order to provide a portable mechanism for users to select and view projection information, the Projection SharedResource was added to CWC2. Any widgets that need to be aware of the current projection (and either allow changing it or displaying it) access the information from the Projection SharedResource, if possible. The structure of the Projection SharedResource is as follows:

<CWC2 TYPE="SharedResource" NAME="Projection">
<PROJECTION NAME="NAD 83 / Geographic" srs="epsg:4269"/>
<PROJECTION NAME="WGS 84 / Geographic" srs="epsg:4326"/>
<PROJECTION NAME="WGS 84 / Auto UTM" srs="AUTO:42001"/>
<PROJECTION NAME="WGS 84 / Auto Tr. Mercator" srs="AUTO:42002"/>
<PROJECTION NAME="WGS 84 / Auto Orthographic" srs="AUTO:42003"/>
<PROJECTION NAME="WGS 84 / Auto Equirectangular" srs="AUTO:42004"/>
<PROJECTION NAME="WGS 84 / LCC Canada" srs="epsg:42101"/>
<PROJECTION NAME="NAD 83 / NRCan LCC Canada" srs="epsg:42304"
default="true"/>
</CWC2>

It is the responsibility of the application developer to understand the meaning of projections and to determine exactly how to use this SharedResource. Each <projection> element of the SharedResouce requires a name (which is actually displayed to the user) and an SRS (which is the EPSG code).

Customizing the WaitImage

In the map widget and several popup dialogs, a progress indicator is displayed during potentially long operations. This progress indicator is typically a single, animated GIF image that gives the impression that the operation is still working. In CWC2, this progress indicator is referred to as the WaitImage. In order to allow the default WaitImage to be replaced with one that matches the look and feel of the application or to provide multilingual WaitImages, a WaitImage SharedResource is available, with the following structure:

<CWC2 TYPE="SharedResource" NAME="WaitImage">
<WAITIMAGE LANGUAGE="en-CA" WAITIMAGE="images/spinner.gif"
WAITIMAGEWIDTH="205" WAITIMAGEHEIGHT="35"/>
<WAITIMAGE LANGUAGE="fr-CA" WAITIMAGE="images/spinner_f.gif"
WAITIMAGEWIDTH="253" WAITIMAGEHEIGHT="35"/>
</CWC2>

Each <WaitImage> element of the SharedResource requires an application-specific language, an image to use, and the width and height of the associated image.