Abstract
This document describes the procedures for implementing an HTML legend in MapServer applications.
Last Updated: 07/07/2004
Table of Contents
The HTML legend is an alternative to the traditional GIF legend in MapServer. The following document describes the process for implementing an HTML legend in MapServer CGI applications (NOTE: MapServer version > 3.5 is required, e.g. v3.5.1 is valid)
This document assumes that you are already familiar with certain aspects of MapServer:
Setting up MapServer mapfiles and templates.
The HTML legend is enabled by a new TEMPLATE parameter in the Legend Object of the mapfile. If TEMPLATE is set in the Legend Object, then the HTML legend template file is read and used to generate an HTML legend which will be inserted at the location of the [legend] tag in the main HTML template. Similar to other MapServer templates, the HTML legend template filename MUST end with an ".html" extension.
Example 1. Sample Legend Object with the new TEMPLATE parameter:
...
# LEGEND object
LEGEND
STATUS ON
KEYSIZE 18 12
# LABEL object
LABEL
TYPE BITMAP
SIZE MEDIUM
COLOR 0 0 89
END
TEMPLATE "legend.html"
END
...
If TEMPLATE is not set, then the [legend] tag produces a regular image in a GIF/PNG image (the traditional behaviour).
The traditional [legend] tag returns the URL of an image, so it is usually used inside an <IMG SRC=[legend]> tag in the HTML. The new HTML [legend] tag returns a block of HTML, so when converting an existing application template from using a traditional image legend to the new HTML legend, you have to remove the IMG tag in the main application template. Also note that if legend mode is specified in the URL, then MapServer will return a gif containing the whole legend if no template is specified.
Example 2. [legend] tag in the main HTML template (with TEMPLATE set)
... <FONT SIZE=+1><B>Legend</B></FONT><BR><HR><[legend]<HR> ...
Example 3. [legend] tag in the main HTML template (with TEMPLATE not set)
... <FONT SIZE=+1><B>Legend</B></FONT><BR><HR><IMG SRC="[legend]"><HR> ...
The HTML legend template file contains 0 or 1 of each of the following tags that define blocks of HTML to use in building the legend:
[leg_group_html] ... [/leg_group_html]
[leg_layer_html <OPTIONAL PARAMS>] ... [/leg_layer_html]
[leg_class_html <OPTIONAL PARAMS>] ... [/leg_class_html]
Any text or HTML tags outside the [leg_*_html] tag pairs in the legend template file are ignored by the template parser.
The following example shows what an HTML legend TEMPLATE file could look like:
Example 4. An HTML legend TEMPLATE file
[leg_group_html]
<tr>
<td colspan=3 bgcolor=#cccccc><b>[leg_group_name]</b></td>
</tr>
[/leg_group_html]
[leg_layer_html order_metadata=legend_order opt_flag=5]
<tr>
<td>
<input type=checkbox name="map_[leg_layer_name]_status"
value=1 [if name=layer_status oper=eq value=2]CHECKED[/if]>
</td>
<td colspan=2>
<a href="[metadata name=href]">[metadata name=layer_title]</a>
</td>
</tr >
[/leg_layer_html]
[leg_class_html]
<tr>
<td width=15> </td>
<td>
<img src="[leg_icon width=20 height=10]" width=20 height=10>
</td>
<td>
[leg_class_name]
</td>
</tr>
[/leg_class_html]
TAG: [leg_group_html]...[/leg_group_html]
HTML block to use for layer group headers if layers should be grouped in the legend. If not set then layers are not grouped in the legend.
When the [leg_group_html] tag is used, then layers that don't belong to any group (i.e. LAYER GROUP not set in the mapfile) and their classes will not show up at all in the legend. The group list is decided by the order_metadata parameter, which is explained later.
Supported tags in the [leg_group_html] block:
TAG: [leg_group_name]
DESCRIPTION: Returns the group's name.
TAG: [layer_status]
DESCRIPTION: Returns the status of the first layer in the group.
TAG: [leg_icon width=<optional_width> height=<optional_height>]
DESCRIPTION: In the group context, the [leg_icon] tag returns the URL of a legend icon for the first class in the first layer that's part of this group.
TAG: [metadata name=<metadata_field_to_display>]
DESCRIPTION: Returns specified metadata value from web's metadata.
TAG: [leg_layer_html <OPTIONAL PARAMS>] ... [/leg_layer_html]
HTML block to use for layer header. If not set then no layer headers are displayed (could allow a legend with only classes in it).
Optional parameters for the [leg_layer_html] tag:
PARAMETER: order_metadata=<field_to_order_by>
DESCRIPTION:
specifies that the value of the layer metadata <field_to_order_by> controls the order and visibility of the layers in the legend.
Layers with <field_to_order_by> >= 0 are sorted in order of this value, with multiple layers with same value being accepted, in which case the map layer order applies between those layers.
Layers with <field_to_order_by> < 0 are always hidden in the legend.
PARAMETER: opt_flag=<bit_mask>
DESCRIPTION: Control the layer display process. Add the values below to acquire the desired options:
1: If set, show layer even if out of scale (default: hide layers out of scale).
2: If set, show layer even if status is OFF (default: hide layers with STATUS OFF).
4: If set, show layer even if type is QUERY (default: hide layers of TYPE QUERY)
8: If set, show layer even if type is ANNOTATION (default: hide layers of TYPE ANNOTATION)
e.g. opt_flag=12 means show all layer types, including QUERY and ANNOTATION layers (4 + 8)
Supported tags in the [leg_layer_html]...[/leg_layer_html] block:
TAG: [leg_layer_name]
DESCRIPTION: Returns the current LAYER NAME value.
TAG: [leg_icon width=<optional_width> height=<optional_height>]
DESCRIPTION: In the layer context, the [leg_icon] tag returns the URL of a legend icon for the first class in this layer.
TAG: [metadata name=<metadata_field_to_display>]
DESCRIPTION: Returns specified metadata value from this layer's metadata and web's metadata.
TAG: [leg_class_html <OPTIONAL PARAMS>] ... [/leg_class_html]
HTML block to use for classes. If not set then no classes are displayed (could allow a legend with only layer headers in it).
Classes with NULL (i.e. empty) NAMEs are not displayed.
Optional parameters for this tag:
PARAMETER: opt_flag=<bit_mask>
DESCRIPTION: same meaning as in [leg_layer_html] tag
Supported tags in this specific block:
TAG: [leg_class_name]
DESCRIPTION: Returns the CLASS NAME value.
TAG: [leg_class_title]
DESCRIPTION: Returns the CLASS TITLE value.
TAG: [leg_icon width=<optional_width> height=<optional_height>]
DESCRIPTION: In the layer context, the [leg_icon] tag returns the URL of a legend icon for the first class in this layer.
TAG: [metadata name=<metadata_field_to_display>]
DESCRIPTION: Returns specified metadata value from the metadata of the layer to which this class belongs and web's metadata.
[if] tags can be used in any of the [leg_*_html] tags above to place conditional text. The syntax is:
[if name=<field_to_check> oper=<eq|neq|isset|isnull> value=<to_compare_with_field>] ... [/if]
Nested IF's are supported. Parameter "oper" can be "eq" for equal, "neq" for not equal, "isset" (self-explanatory), or "isnull" (self-explanatory). The default value is equal.
Example 5. [if] tag can be used to maintain the state of a layer checkbox
[leg_layer_html order_metadata=legend_order opt_flag=5]
<tr>
<td>
<input type=checkbox name="map_[leg_layer_name]_status"
value=1 [if name=layer_status oper=eq value=2]CHECKED[/if] >
</td>
<td colspan=2>
<a href="[metadata name=href]">[metadata name=layer_title]</a>
</td>
</tr >
[/leg_layer_html]
The possible values that can be tested in an [if] tag depend on the context in which the [if] tag is used. At the moment, the number of values that can be tested is limited, but new values may be added as needed. The possible values that can be tested are as follows:
In a [leg_group_html] Context:
[if name=any_web_metadata value=...] ... [/if]
[if name=layer_status value=...] ... [/if]
(value is the layer status of the first layer that belongs to the group in integer format: 0=OFF, 1=ON, 2=DEFAULT)
[if name=layer_visible value=...] ... [/if]
(value is the visibility of the first layer in the group: 0=NOT VISIBLE, 1=VISIBLE)
In a [leg_layer_html] Context:
[if name=layer_status value=...] ... [/if]
(value is the layer's status in integer format: 0=OFF, 1=ON, 2=DEFAULT)
[if name=layer_type value=...] ... [/if]
(value is the layer's type in integer format: 0=POINT, 1=LINE, 2=POLYGON, 3=RASTER, 4=ANNOTATION, 5=QUERY, 6=CIRCLE)
[if name=layer_name value=...] ... [/if]
(value is the layer's name in string format)
[if name=layer_group value=...] ... [/if]
(value is the layer's group name in string format)
[if name=any_web_metadata value=...] ... [/if]
[if name=any_layer_metadata value=...] ... [/if]
[if name=layer_visible value=...] ... [/if]
(value is the visibility of the layer: 0=NOT VISIBLE, 1=VISIBLE)
In a [leg_class_html] Context:
[if name=layer_status value=...] ... [/if]
(value is the status of the layer in which the class is located)
[if name=layer_type value=...] ... [/if]
(value is the layer's type in integer format: 0=POINT, 1=LINE, 2=POLYGON, 3=RASTER, 4=ANNOTATION, 5=QUERY, 6=CIRCLE)
[if name=layer_name value=...] ... [/if]
(value is the layer's name in string format)
[if name=layer_group value=...] ... [/if]
(value is the layer's group name in string format)
[if name=any_web_metadata value=...] ... [/if]
[if name=any_layer_metadata value=...] ... [/if]
[if name=layer_visible value=...] ... [/if]
(value is the visibility of the layer: 0=NOT VISIBLE, 1=VISIBLE)
http://www2.dmsolutions.ca/msapps/itasca_legend/demo_init.html
This demo is based on the MapServer Itasca demo and contains several variations of HTML Legends, some of which are listed below:
"HTML Legend 1" - displays classes only, similar to the traditional legends:
[leg_class_html opt_flag=15]
<img src=[leg_icon]> [leg_class_name]<br>
[/leg_class_html]
"HTML Legend 2" - displays layer titles with HREF links and classes:
[leg_layer_html order_metadata=WMS_ORDER visibility_flag=15]
<a href="[leg_layer_name]">[metadata name=WMS_TITLE]</a><BR>
[/leg_layer_html]
[leg_class_html visibility_flag=15]
<img src=[leg_icon]> [leg_class_name]<br>
[/leg_class_html]
"HTML Legend 3" - displays layers by group, with checkboxes to turn layers on/off:
[leg_group_html]
<tr><td colspan=2><b>[leg_group_name]</b></td></tr>
[/leg_group_html]
[leg_layer_html order_metadata=WMS_ORDER opt_flag=15]
<tr>
<td><input type=checkbox name=layer value=[leg_layer_name]
[if name=layer_status value=1]CHECKED[/if]>
[if name=layer_type value=4]
<img src=[leg_icon width=22 height=18]>
[/if]
[if name=layer_type oper=neq value=4]<img src=[leg_icon]>[/if]
</td>
<td>
<a href="[leg_layer_name]">[metadata name=WMS_TITLE]</a>
</td>
</tr>
[/leg_layer_html]
Copyright (c) 2004, Jeff McKenna, DM Solutions Group Inc.
This documentation is covered by the same Open Source license as the MapServer software itself. See MapServer's License and Credits page for the complete text.
No liability for the contents of this document can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies that may be damaging to your system. Although this is highly unlikely, the author(s) do not take any responsibility for that: proceed with caution.
| Add a Comment |