The CWC2 incorporates the ability to quickly set up new applications from a
common pool of "widgets" that can be placed in an HTML template file.
These widgets provide a fixed piece of functionality, but the representation
of the widget is normally highly configurable. This guide presents a tutorial
approach to building a basic CWC2 application template and then describes the
advanced configuration that is possible for widgets. 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 an Internet-accessible 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
Context
A Context is an XML description of the geographic data. The CWC2 Service
Instance uses the Context to determine what images to request from which WMS
servers in order to display a Map to the user.
Widget
A Widget is the basic element of a CWC2 application. Widgets are represented
by an XML-like tag 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 purely through the creation of an Application Template.
CWC2 Service Instance
This is the heart of CWC2. The CWC2 Service Instance is an Internet-accessible
service that can interpret a 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 the CWC2 Service Instance
The 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 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
its local filesystem to particular directories or to prevent it 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 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 its local filesystem to particular directories or to prevent it 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: TEMPLATE=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 an additional requirement that the tags be complete. This means that every
tag have a closing element. There are two valid ways of closing an XML tag.
The first is to include a "/" before the closing bracket. 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 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
will 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. The CWC2 Service Instance administrator
may also have created additional widgets.
Most widgets will also require some values to configure them. These values are
normally specified in one of two ways. The first, and most common, is to specify
a value in the CWC2 tag in the same way as the TYPE attribute is specified.
For instance:
<CWC2 TYPE="WidgetName" TEST="false"/>
This creates a widget of type WidgetName with an attribute TEST that is set
to the string "false". Some widgets require attributes to be passed
as nested tags inside a CWC2 tag. For instance:
This creates the same widget but normally allows for multiple copies of the
nested tags. Note that nested tags have the same formatting restrictions as
the 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. You
will find in the sample tags that the type of value for each attribute is provided.
All attributes in the 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.
Also in the documentation, you will 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 default behaviour or
appearance of a widget.
Building a Template
This section of the guide will step you through the creation of a basic template
that can be used to create a simple Web Mapping application with the CWC2 Service
Instance. 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 normally being creating a new CWC2 application by copying an existing
template or creating a brand new template. In this case, we will 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:
a <html></html> section
a <head></head> section
a <body></body> section with
an onload event specified. The onload event must call CWC2OnLoadFunction()
or call a function that calls CWC2OnLoadFunction().
a <form></form> in the body
section.
a stylesheet link to cwc2.css or a stylesheet that at least defines all
the required widget styles.
The stylesheet link is actually optional but is normally highly desirable to
allow widgets to obtain their default settings and to allow customization of
these settings.
A sample of a minimum HTML template that is correctly configured for the CWC2
Service Instance is:
The basic element of any mapping application is a map. The CWC2 Widget that
represents a Map is the MapDHTMLWidget widget. This widget requires the following
attributes:
TYPE: [String] - This is required by all widgets to define their type and,
therefore, their behaviour. For this widget the type is "MapDHTMLWidget".
WIDTH: [Integer] - This attribute defines the overall map image width in
pixels.
HEIGHT: [Integer] - This attribute defines the overall map image height
in pixels.
Additional optional attributes are as follows (detailed information can be
found in the annex in the back of this guide): VISIBLE, ENABLED, MARQUEECOLOR,
MARQUEEWIDTH, MARQUEEHEIGHT, MARQUEEVERTICALIMAGE, MARQUEEHORIZONTALIMAGE, MINSCALE,
MAXSCALE, and ALLOWRESIZE.
Here is what the tag looks like as implemented in this example:
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:
Your template is now functional and ready to be tested. To test the template
you need only to add it as a URL parameter to the main CWC2 Service Instance,
and specify a context as well. For instance:
<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 the context. This forms the basis of any mapping
application, but it isn't a very useful application yet. In the next step you
will add other widgets to improve the application's usefulness.
Step 5 - Adding Navigation
In the previous step you were able to see that your template was indeed working
but your application wasn't very useful. In this step we will add two additional
widgets that will 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 CWC widget of
type "ZoomIn". This widget has the following required attributes:
TYPE: [String]] - This is required by all widgets to define their type and,
therefore, their behaviour.
IMAGE: [String] - This attribute is the image file to display for the button.
The optional attributes are as follows (detailed information can be found in
the annex in the back of this guide): VISIBLE, ENABLED, IMAGEWIDTH, IMAGEHEIGHT,
IMAGETIP, IMAGECLASS, IMAGESTYLE, TOOLSET, IMAGESELECTED, IMAGEHOVER, DEFAULT,
WIDGETSTYLE, and MINMUMZOOMRECTANGLE.
Here is what the tag looks like as implemented in this example:
To add a zoom out tool to your template you will need to add a CWC widget of
type "ZoomOut". This widget has the following required attributes:
TYPE: [String]] - This is required by all widgets to define their type and,
therefore, their behaviour.
IMAGE: [String] - This attribute is the image file to display for the button.
The optional attributes are as follows (detailed information can be found in
the annex in the back of this guide): VISIBLE, ENABLED, IMAGEWIDTH, IMAGEHEIGHT,
IMAGETIP, IMAGECLASS, IMAGESTYLE, TOOLSET, IMAGESELECTED, IMAGEHOVER, DEFAULT,
and WIDGETSTYLE.
Here is what the tag looks like as implemented in this example:
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 the map 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 experiment with the parameters of each widget
to discover how flexible the CWC2 widgets 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
customizing TextButtons
customizing Projections
customizing WaitImage
Customizing with CSS
All core widgets provided with the CWC2 are designed to allow the application
developer to configure the application's appearance using CSS. The CWC2 provides
default CSS files that provide 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 is familiar with CSS.
Widget Classes
The first CSS stylesheet that can be modified is cwc2.css. It 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:
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 map unit 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 a <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 that the map is displayed
in. 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.
.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 time filter
widget. The class is applied to <p> tags.
.CWCTimeFilterInputClass
This class defines the appearance of input boxes used in the time filter
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
using 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 using
a SharedResource widget. The format of this widget is as follows:
By placing this tag anywhere in the application template, all popup dialogs
will use a link to 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 sub content areas. This allows for more
advanced designs and is intended to be used with subLayoutTable (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 useage sets the size, colour and
font of any labels of input elements.
.note
Defines the style of text notes. Basic useage 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 useage sets the size, colour and
font of <p>, <span> or <div> tags.
.list
Defines the style of ordered and unordered lists. Basic useage sets the
size, colour and font of any <ul>, <ol> tag.
.listItem
Defines the style of list items. Basic useage sets the size, colour and
font of any <li> tag. Normally would be the same as list, but more advanced
techniques can be used as well.
.inputBox
Defines the style of text input elements. Basic useage sets the font and
size of any input elements' text. More advanced useage sets the styling of
the input area as well.
.inputList
Defines the style of list input elements. Basic useage sets the font and
size of any input elements' text. More advanced useage 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 is only having to provide translated text,
not generate a set of new buttons). Text buttons are very flexible elements
and because of this, they seem quite complex. However, with only a few simple
changes, the appearance of an application can be dramatically changed.
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:
a border style
a background image or color
a button graphic image
a label
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 width/height. 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 it is cropped
if it is too big. The button graphic is placed at the left edge of the center
portion and is vertically centered in the button. 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 the 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 this example instead of the proper "TEXTBUTTONBORDER"
for visual purposes only.
Any widget that uses a TextButton as it's graphical representation has all
the attbributes 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 since every widget must be changed individually (i.e. changing a background
color). Finally, popups created by widgets also use TextButtons and these popups
are not generally modifyable by the application developer. To solve these problems,
the TextButton will take its values from the following places in order of appearance:
Widget Tag attributes
TextButton SharedResource widget
Default values hard-coded in TextButton
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 they will assume the documented default values. The structure of the
TextButton SharedResource is as follows:
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 support multilingual applications and to allow for customized
look and feels.
Customizing Projections
The ProjectionSelector and ProjectionLabel widgets provide a convenient mechanism
for choosing the projection to display a map in and for the user to see what
the projection is. CWC2 currently supports only projections that are defined
in the 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 CWC2 to allow 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 display it will access the information in the Projection
SharedResource if possible. The structure of the Projection SharedResource is
as follows:
It is up to the application developer to understand the meaning of projections
and 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 a single image
and is typically an 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 application designer to replace the default WaitImage
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:
Each <WaitImage> element of the SharedResource requires a language (application
specific), a WaitImage to identify the image to use, and a WaitImageWidth and
WaitImageHeight (the width and height of the associated image).