Gulf of Maine Mapping Portal - GoMMaP

Mapping Resources

How to Build a Mapping Application

How to Publish Data

Open Standards

Frequently Asked Questions
 

Template Requirements

It is important to understand the following terminology and concepts:

HTML Template
A Chameleon application template is an HTML file that includes CWC2 tags. This HTML template describes the Chameleon functionality you will be using as well as all interface styling information for your Web mapping application. Exactly how to format your HTML template in order for Chameleon to successfully interpret it is discussed further down in this document.
Widget
A widget is the basic element of a Chameleon Web mapping application and are typically placeholders for a specific Web mapping functionality. Widgets are represented by XML-like tags in a Chameleon template. A wide variety of widgets currently exist within Chameleon, enough to allow the development of complex Web mapping applications.
Attributes
Attributes is the general term for all optional and required variables (parameters) placed within a widget tag that determine how the widget operates and how it looks.
Subtags
Subtags are XML-like tags that hold a group of nested widget parameters related to a specific widget. Often Subtags are dependant on a specific widget attribute found in a widget tag. Subtags can also contain other Subtags, depending on the relationships between attribute and sub-attributes.
Shared Resource
A Shared Resource is a unique type of Chameleon widget with many faces. This widget type allows Chameleon application developers to have flexibility and management power over widget attributes (or groups of widget attributes). Shared Resources can "share" their defined global attributes with multiple widgets found within a single HTML template. How a Shared Resource is defined determines its reach and how it affects your Web mapping application. By using Shared Resources, you help keep the main part of your HTML template clear of distracting widget attribute clutter.

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, but that isn't important here.) 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 a 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 "/".

CWC Tag

Here are examples of minimal valid Chameleon CWC2 tags: 

    <CWC2/>

        and

    <CWC2></CWC2>

These simple tags above don't actually represent any functionality and would be ignored by the Chameleon HTML parser. "CWC2" is the marker used so that other HTML tags (for styling, tables, etc.) can be distinguished from Chameleon tags.

Defining A Widget

In order to create a tag that represents an actual Chameleon widget, you need to add a TYPE attribute to the tag: 

    <CWC2 TYPE="WidgetName"/>

This CWC2 tag represents a widget called "WidgetName". Since there isn't a widget available by that name, the Chameleon HTML parser would generate an error if this tag was defined in an HTML template. The list of available widgets is documented in the Chameleon Widget Documentation. Your CWC2 Service Instance administrator may also have created additional widgets for you to use.

Widget Configuration and Flexibility

Most widgets also require additional configuration attributes to be defined. These values are normally specified in one of two ways. The first, and most common, way is to specify other values in the CWC2 tag in the same way the TYPE attribute is specified. For example: 

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

This creates a widget of TYPE "WidgetName" with a TEST attribute that is set to "false".

Nested Subtags

Some widgets require (or allow) attributes to be passed as nested tags inside a CWC2 tag. This is often caused by the widget requiring a list of a common attributes or groups of dependent attributes. For example: 

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

This allows for multiple copies of nested tags and attributes. Nested tags have the same formatting restrictions as CWC2 tags in that they must be closed properly. Widgets that require nested tags will specify the necessary format in their documentation. Often Shared Resources widgets are structured in this manner.

Widget Attributes that Point To Files

Even though this topic is related to individual attributes it is important enough to be included in widget basics.

In some cases, widget attributes hold a string value that defines a path to a file to be used. The file could be used for anything that the widget may need, including an image for a button, a map file to display a map, XML code, or even another HTML template. Defining these paths properly so that they can be understood by Chameleon can be confusing.

Chameleon tries to locate these files in any possible location that it could be found, based on the configuration for each widget attribute path. These paths can be defined as:

  • A local path relative to the Chameleon HTML template.
  • A server side local path relative to the Chameleon installation itself.
  • Any URL located anywhere that is accessible to the Chameleon Service Instance.
  • An absolute path on a local machine relative to either the Chameleon Service Instance or the template. The template may not be on the same machine as the Chameleon Service Instance.

Building a Template

This section of the guide discusses the following details:

  • Introducing the GoMMaP Sample Chameleon HTML Template
  • Defining basic requirements or components for a Chameleon HTML template
  • Showing how to create the simplest functional Chameleon HTML template

First Step - The GoMMaP Sample HTML Template

You will typically create a new Chameleon application by copying an existing template and making changes to it specific to what you need. To help you, the Gulf of Maine Data Framework has provided a sample template for downloading. All GoMOOS organizations that wish to develop their own Web mapping application(s) can start with this basic sample template.

Of course, depending on your confidence with the Chameleon technology and HTML in general, you can also create an application template from scratch. However, it is much simpler to modify a more complete file.

Where can I Download this GoMMaP Sample HTML Template?

You can get this template here.

Second Step - Understanding Your Template

Whether you are using the GoMMaP Sample HTML Template, your own template, or starting from scratch, it is important to understand the basic requirements for a Chameleon HTML Template. The discussion below assumes that you are starting with no template. This does not mean that people with an existing Chameleon HTML template cannot follow along and find these features within their templates.

If you wish, you can follow section this like a tutorial and build your own simple template.

What are the Basic Requirements?

The basic requirements for Chameleon to read and parse your HTML web mapping application template are that all the following features are in your template:

  • A   <!DOCTYPE HTML PUBLIC...>    tag.
    • Note: This tag must be placed at the top of template.
  • An   <html></html>   section.
  • An   <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> section within the body section.
  • A stylesheet link to cwc2.css or a stylesheet that at least defines all the required widget styles.
    • Note: The stylesheet link is actually optional, but it is highly desirable to include it in order to allow widgets to obtain their default settings and to allow customization of these settings.

What does the Basic HTML Template Look Like?

Below is a sample of a minimal HTML template that is correctly configured for the Chameleon parser. Can you see all the required elements listed above?

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <html>
    <head>
      <title>Widgets</title>
      <link href="cwc2.css" rel="stylesheet" type="text/css">
    </head>

    <!-- All Shared Resources can be placed at the top of Template. -->
    <body onload="CWC2OnLoadFunction()">

    <!-- All other Chameleon Widgets live between the form elements. -->
      <form>
      </form>
    </body>
  </html>

Third Step - Adding a Map Widget

Now that you have a valid Chameleon HTML template, you can define further mapping elements for your application. The Chameleon mapping application elements are defined as "widgets" in the HTML template. The most basic mapping element of any application is a map itself. The widget type to be added to the template is called "MapDHTMLWidget".

How is the Map Widget Defined?

This Map widget requires the following widget attributes:

  • TYPE: [string] - This is required by all widgets to define their type and, therefore, their behavior. For this widget, the type is "MapDHTMLWidget".
  • WIDTH: [integer] - This defines the overall map image width in pixels.
  • HEIGHT: [integer] - This defines the overall map image height in pixels.

Additional optional attributes are as follows. Many of the following attributes have default values which are used most of the time.

  • VISIBLE: [boolean]
  • ENABLED: [boolean]
  • MARQUEECOLOR: [hex color]
  • MARQUEEWIDTH: [integer]
  • MARQUEEHEIGHT: [integer]
  • MARQUEEVERTICALIMAGE: [string]
  • MARQUEEHORIZONTALIMAGE: [string]
  • MINSCALE: [float]
  • MAXSCALE: [float]
  • ALLOWRESIZE: [boolean]
  • WAITIMAGE: [string]
  • WAITIMAGEWIDTH: [integer]
  • WAITIMAGEHEIGHT: [integer]

NOTE: Detailed information for this widget and all attribute descriptions can be found in the Chameleon Widget Reference Document.

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

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

How do I Place the Map Widget in my Chameleon HTML Template?

All widgets must be added inside the <form></form> tags on the page, but they can be inline with any other HTML formatting tags, such as those for 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>

      <!-- All Shared Resources can be placed at the top of Template. -->
      <body onload="CWC2OnLoadFunction()">

        <!-- All other Chameleon Widgets live between the form elements. -->
        <form>
          <table border="0" cellspacing="2" cellpadding="0">
            <tr>
              <td colspan="3" align="center">

                <!-- Display Map Here. -->
                <CWC2 TYPE="MapDHTMLWidget"
                    VISIBLE="true"
                    WIDTH="400"
                    HEIGHT="300"
                    ALLOWRESIZE="true"
                    MARQUEECOLOR="#FF3333"
                    MARQUEEWIDTH="2"
                    MINSCALE="1"/>
              </td>
            </tr>
          </table>
        </form>
      </body>
    </html>

Fourth Step - Adding a Widget Shared Resource

Depending on which widgets are on your template and their dependencies, this step of Chameleon application development may be optional. As a Chameleon application developer it is hoped you will continue to expand the design complexity of your mapping interfaces - using Shared Resource is one way to help manage increasingly complex application interfaces.

How is a Widget Shared Resource Defined?

A Shared Resource is a widget that requires the following widget attributes:

  • TYPE: [string] - This is required by all widgets to define their type and, therefore, their behavior. For this widget the type is "SharedResource".
  • NAME: [string] - This defines what kind of Shared Resource it will be.

These two required Shared Resource attributes help define what this widget represents. All the other widgets that use a Shared Resource help determine how that specific Shared Resource is defined. In other words, since a Shared Resource is a place holder for certain attributes of other widgets, it can take on many, many different forms.

What Shared Resource Can I Use for this Template?

The basic template defined above contains a widget called "MapDHTMLWidget". This widget can use the Shared Resource named "WaitImage". The WaitImage Shared Resource holds a language-specific, moving GIF image that is displayed if there is a prolonged waiting period during a user request. In this case, the "MapDHTMLWidget" widget use the wait image when the client is waiting for a new map image to load from the server.

The "WaitImage" Shared Resource looks like the following: 

    <!-- WaitImage Shared Resource -->
    <cwc2 type="SharedResource" name="WaitImage">
        <waitimage language="en-CA"
            waitimage="images/spinner.gif"
            waitimagewidth="216"
            waitimageheight="50"/>
        <waitimage language="fr-CA"
            waitimage="images/spinner_f.gif"
            waitimagewidth="216"
            waitimageheight="50"/>
    </cwc2>

You will notice in the <waitimage.../> subtag that there are four attributes. The "language" attribute is actually correlated with the "Language" widget, where the language used in the template is defined. The other three attributes - "waitimage", "waitimagewidth", and "waitimageheight" - are actually valid attributed within the "MapDHTMLWidget" widget. (See above.)

Instead of defining the three "waitimage"-based attributes within the map widget, use the "WaitImage" Shared Resource.

How do I Place the WaitImage Shared Resource in My Chameleon HTML Template?

In a previous step it was stated that "All widgets must be added inside the <form></form> tags...". Well, Shared Resource widgets are the exception. Shared Resources are not restricted to between <form> and </form> but, for general formatting and readability purposes, they should be placed above the <body> tag. In many complex Chameleon HTML templates, you will find more than one Shared Resource listed at this location. 

    <html>
      <head>
        <title>Widgets</title>
        <link href="cwc2.css" rel="stylesheet" type="text/css">
      </head>

      <!-- All Shared Resources can be placed at the top of Template. -->

      <!-- WaitImage Shared Resource -->
      <cwc2 type="SharedResource" name="WaitImage">
          <waitimage language="en-CA"
              waitimage="images/spinner.gif"
              waitimagewidth="216"
              waitimageheight="50"/>
          <waitimage language="fr-CA"
              waitimage="images/spinner_f.gif"
              waitimagewidth="216"
              waitimageheight="50"/>
      </cwc2>

      <body onload="CWC2OnLoadFunction()">

        <!-- All other Chameleon Widgets live between the form elements. -->
        <form>
          <table border="0" cellspacing="2" cellpadding="0">
            <tr>
              <td colspan="3" align="center">

                <!-- Display Map Here. -->
                <CWC2 TYPE="MapDHTMLWidget"
                    VISIBLE="true"
                    WIDTH="400"
                    HEIGHT="300"
                    ALLOWRESIZE="true"
                    MARQUEECOLOR="#FF3333"
                    MARQUEEWIDTH="2"
                    MINSCALE="1"/>
              </td>
            </tr>
          </table>
        </form>
      </body>
    </html>

Fifth Step - View the Chameleon Application

Your simplest of Chameleon HTML templates is now functional and ready to be used. You can now try to get Chameleon to parse this template in your browser using a Chameleon Service Instance and a map file. Please refer to the other associated documents for information on how to make this happen.

Once you call the proper URL, the following things should happen:

  • Onload of the HTML template through the Chameleon Service Instance. The wait image is displayed within the map area while the map is loaded.
  • The map in the map file you specified displays, and that is it!

Making is a "Real" Application

While the above sample application does not seem like much, creating it is a very important step in understanding how to build a more realistic Chameleon HTML template. Now that you have a working mapping application the world is your oyster. You can begin to add more widgets that interact with your map, like the "ZoomIn" and "ZoomOut" widgets: 


    <!-- ZOOM IN -->
    <cwc2 type="ZoomIn" visible="true" imagetip="Zoom In" toolset="Navigation"
        imagewidth="24" imageheight="24">
        <image state="normal" image="buttons/button_zoomin_1.png"/>
        <image state="hover" image="buttons/button_zoomin_2.png"/>
        <image state="selected" image="buttons/button_zoomin_3.png"/>
    </cwc2>

    <!-- ZOOM OUT -->
    <cwc2 type="ZoomOut" visible="true" imagetip="Zoom Out" toolset="Navigation"
        imagewidth="24" imageheight="24">
        <image state="normal" image="buttons/button_zoomout_1.png"/>
        <image state="hover" image="buttons/button_zoomout_2.png"/>
        <image state="selected" image="buttons/button_zoomout_3.png"/>
    </cwc2>

If everything works, you should now have a navigable mapping application!

GoMMaP Sample HTML Template

For details on the widgets discussed so far, as well as the other widgets found in the GoMMaP sample template, please go to the "GoMMaP - Chameleon Widget Reference" document. If you have not already done so, take a minute or two and review the information on all the widgets found in the GoMMaP Sample HTML Template. This Widget Reference can give you the information and confidence to enhance the GoMMaP Sample template and make it your own.

Where to from Here?

At this point, as a Chameleon application developer, you have the following options:

Option 1: Build your Context File using GoMMaP Applications
Since you have a template that works you can look into trying to build your map file using the GoMMaP - Map Viewer and GoMMaP - Map Builder applications. Once you have this OGC Context map file, you can come back to the template and customize your GoMMaP sample template accordingly.
Option 2: Chameleon CWC2 Service Instance
Try to load an OGC Context map file using a Chameleon CWC2 Service Instance. If you are unfamiliar with this concept, please refer to the other associated documents found on the GoMMaP site or the www.maptools.org resources for Chameleon.
Option 3: Use Chameleon Locally with an HTML Template
Try to load a OGC Context Map file (*.xml) or MapServer Map file (*.map) using a locally installed copy of Chameleon. For details on how this is done, please use the www.maptools.org resources for Chameleon.
Option 4: Continue Developing Your Chameleon HTML Template
Continue building your web mapping application by:
  • Adding more widgets to your Chameleon application to increase the interface functionality.
  • Organizing your widgets to make a more usable interface.
  • Adding and modifying the style of your HTML page as well as the widgets popup.css stylesheet.
  • Modifying the style of the interface by creating new graphics and/or exploring the different Chameleon widget button styling and labeling attributes.
  • Modifying the style of your HTML page by creating new cwc.css and/or popup.css stylesheets.