|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| Author: | Frank Koormann |
|---|---|
| Contact: | frank.koormann at intevation.de |
| Author: | Jeff McKenna |
| Contact: | jmckenna at gatewaygeomatics.com |
| Revision: | $Revision$ |
| Date: | $Date$ |
Table of Contents
Templates are used:
They guide the presentation of results, either a query or a map, to the user. Templates are almost always HTML files although they can also be a URL (e.g.. http://www.somewhere.com/[ATTRIBUTE]/info.html). URL templates can only be used with simple QUERY or ITEMQUERY results so many substitutions defined below are not available for them. Simple pan/zoom interfaces use a single template file while complicated queries often require many templates. Templates often use JavaScript to enhance the basic interface.
Templates must contain the magic string ‘mapserver template’ in the first line of the template. Often this takes the form of an HTML, javascript or XML comment. This line is not written to the client. The magic string is not case sensitive.
All CGI parameters can be referenced in template substitutions, MapServer specific parameters as well as user defined ones. In principle parameters are handed through by the MapServer 1:1. This feature is essential for implementing MapServer applications.
The reference below only lists special template substitution strings which are needed to obtain information modified by the MapServer, e.g. a new scale, query results, etc.
Template substitution strings are case sensitive.
Attribute item substitutions must be the same case as the item names in the dbase file.
ArcView and ArcInfo generally produce dbase files with item names that are all uppercase. Appropriate URL encoding (i.e. ‘ ‘ to ‘+’) is applied when templates are URLs.
Some substitutions are also available in escaped form (i.e. URL encoded).
As an example this is needed when generating links within a template. This might pass the current mapextent to a new MapServer call. [mapext] is substituted by a space delimited set of lower left and upper right coordinates. This would break the URL. [mapext_esc] is substituted by a proper encoded set.
Templates are simply HTML files or URL strings that contains special characters that are replaced by mapserv each time the template is processed. The simple substitution allows information such as active layers or the spatial extent to be passed from the user to mapserv and back again. Most often the new values are dumped into form variables that will be passed on again. The list of special characters and form variables is given below. HTML templates can include just about anything including JavaScript and Java calls.
In HTML files, the attribute values can be inside quotes(“”). Writing attribute values inside quotes allows you to set special characters in value that you couldn’t use normaly (ie: ],=,” and space). To write a single quote in a attribute value, just use two quotes (“”).
Outputs the date (as per the web server’s clock). The default format is the same as is used by Apache’s Common Log format, which looks like:
01/Dec/2010:17:34:58 -0800
Available arguments:
A format string as supported by the standard C strftime() function. As an example, the default format is defined as:
[date format="%d/%b/%Y:%H:%M:%S %z"]
timezone to use for the date returned. Default is “local”. Valid values are:
Output date will be Greenwich time
Output the time in the web server’s local time zone.
Additionally or alternatively, the %z and %Z strftime format strings allow the timezone offset or name to be output.
The contents of any variables passed to the MapServer, whether they were used or not, can be echoed this way. One use might be to have the user set a map title or north arrow style in an interactive map composer. The system doesn’t care about the values, but they might be real important in creating the final output, e.g. if you specified a CGI parameter like myvalue=.... you can access this in the template file with [myvalue].
Also available as escaped version.
Web object meta data access (e.g [web_projection]
Also available as escaped version.
Current error stack output. Various error messages are delimited by semi-colons.
Also available as escaped version.
Path (relative to document root) of the new image, just the image name if IMAGE_URL is not set in the mapfile.
In a map interface template, [img] is substituted with the path to the map image. In a query results template, it is substituted with the path to the querymap image (if a QUERYMAP object is defined in the Mapfile).
Path (relative to document root) of new legend image rendered by the MapServer.
Since version 3.5.1 a new HTML Legend template is provided by MapServer. If a template is defined in the Mapfile the [legend] string is replaced by the processed legend as. See the HTML Legends with MapServer for details.
Current image size in cols and rows (separated by spaces).
Also available as escaped version.
Full mapextent (separated by spaces).
Also available as escaped version. (mapext_esc is deprecated in MapServer 5.2. You should use the “escape=” argument instead)
The default template [mapext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
Escape the coordinates returned. Default is “none”. Valid values are:
Use URL escape codes to encode the coordinates returned.
Do not escape.
Expand the bounds of the extents by a specific value. Specified in map coordinates. For example, [mapext] might return:
123456 123456 567890 567890
and [mapext expand=1000] would therefore return:
122456 122456 568890 568890
Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add commas to the coordinates you would use:
[mapext format="$minx,$miny,$maxx,$maxy"]
The number of decimal places to output for coordinates (default is 0).
The differences of minimum / maximum X or Y coordinate of new map extent.
Useful for creating cachable extents (i.e. 0 0 dx dy) with legends and scalebars
Raw mapextent, that is the extent before fitting to a window size (separated by spaces). In cases where input came from imgbox (via Java or whatever) rawext refers to imgbox coordinates transformed to map units. Useful for spatial query building.
Also available as escaped version. (rawext_esc is deprecated in MapServer 5.2. You should use the “escape=” argument instead)
The default template [rawext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
Escape the coordinates returned. Default is “none”. Valid values are:
Use URL escape codes to encode the coordinates returned.
Do not escape.
Expand the bounds of the extents by a specific value. Specified in map coordinates. For example, [rawext] might return:
123456 123456 567890 567890
and [rawext expand=1000] would therefore return:
122456 122456 568890 568890
Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add commas to the coordinates you would use:
[rawext format="$minx,$miny,$maxx,$maxy"]
The number of decimal places to output for coordinates (default is 0).
The following substitutions are only available if the MapServer was compiled with PROJ support and a PROJECTION is defined in the Mapfile.
Full mapextent (separated by spaces). Available only when projection enabled.
Also available as escaped version. (mapext_latlon_esc is deprecated in MapServer 5.2. You should use the “escape=” argument instead)
The default template [mapext_latlon] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
Escape the coordinates returned. Default is “none”. Valid values are:
Use URL escape codes to encode the coordinates returned.
Do not escape.
Expand the bounds of the extents by a specific value. Specified in map coordinates. For example, [mapext_latlon] might return:
123456 123456 567890 567890
and [mapext_latlon expand=1000] would therefore return:
122456 122456 568890 568890
Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add commas to the coordinates you would use:
[mapext_latlon format="$minx,$miny,$maxx,$maxy"]
The number of decimal places to output for coordinates (default is 0).
Reference map extent (separated by spaces).
This template has been added with version 4.6 on behalf of an enhancement request. See the thread in the MapServer ticket#1102 for potential use cases.
Also available as escaped version. (refext_esc is deprecated in MapServer 5.2. You should use the “escape=” argument instead)
The default template [refext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
Escape the coordinates returned. Default is “none”. Valid values are:
Use URL escape codes to encode the coordinates returned.
Do not escape.
Expand the bounds of the extents by a specific value. Specified in map coordinates. For example, [refext] might return:
123456 123456 567890 567890
and [refext expand=1000] would therefore return:
122456 122456 568890 568890
Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add commas to the coordinates you would use:
[refwext format="$minx,$miny,$maxx,$maxy"]
The number of decimal places to output for coordinates (default is 0).
All active layers space delimited. Used for a “POST” request.
Also available as escaped version.
List of all layers that can be toggled, i.e. all layers defined in the Mapfile which status is currently not default.
Also available as escaped version.
Used for making the zoom factor persistent. Zoom values can range from -25 to 25 by default. The string is replaced with the HTML keyword “checked”, “selected” or “” depending on the current zoom value.
E.g. if the zoom is 12, a [zoom_12_select] is replaced with “selected”, while a [zoom_13_select] in the same HTML template file is not.
The following substitutions are only available when the template is processed as a result of a query.
Extent of current shape plus a 5 percent buffer. Available only when processing query results.
The default template [shpext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
Escape the coordinates returned. Default is “none”. Valid values are:
“url”
Use URL escape codes to encode the coordinates returned.
Do not escape.
Expand the bounds of the extents by a specific value. Specified in map coordinates. For example, [shpext] might return:
123456 123456 567890 567890
and [shpext expand=1000] would therefore return:
122456 122456 568890 568890
Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add commas to the coordinates you would use:
[shpext format="$minx,$miny,$maxx,$maxy"]
The number of decimal places to output for coordinates (default is 0).
The list of shape coordinates, with list formatting options, especially useful for SVG.
The default template [shpxy] returns a comma separated list of space delimited of coordinates (i.e. x1 y1, x2 y2, x3 y3).
Available only when processing query results.
Available attributes (h = header, f=footer, s=separator):
Buffer size, currently the only unit available is pixels. Default is 0.
Should only the centroid of the shape be used? true or false (case insensitive). Default is false.
Coordinate separator. Default is ”,”.
irh=, irf=, orh=, orf=
Characters to be put before (irh) and after (irf) inner rings, and before (orh) and after (orf) outer rings of polygons with holes. Defaults are “”.
Note
Within each polygon, the outer ring is always output first, followed by the inner rings.
If neither irh nor orh are set, rings are output as “parts” using ph/pf/ps.
Characters to put before (ph) and after (pf) and separators between (ps) feature parts (e.g. rings of multigeometries). Defaults are ph=””, pf=”” and ps=” ”.
The number of decimal places to output for coordinates. Default is 0.
The output projection definition for the coordinates, a special value of “image” will convert to image coordinates. Default is none.
Scaling factor for coordinates: Both axes (scale), x axis (scale_x) and y axis (scale_y). Defaults are 1.0.
Characters to put before (sh) and after (sf) a feature. Defaults are “”.
Characters to put before (xh) and after (xf) the x coordinates. Defaults are xh=”” and xf=”,”).
Characters to put before (yh) and after (yf) the y coordinates. Defaults are “”.
As a simple example:
[shpxy xh="(" yf=")"] will result in: (x1 y1),(x2 y2),(x3 y3)
And a more complicated example of outputting KML for multipolygons which may potentially have holes (note that the parameters must all be on one line):
<MultiGeometry>
<Point>
<coordinates>[shplabel proj=epsg:4326 precision=10],0</coordinates>
</Point>
[shpxy ph="<Polygon><tessellate>1</tessellate>" pf="</Polygon>" xf=","
xh=" " yh=" " yf=",0 " orh="<outerBoundaryIs><LinearRing><coordinates>"
orf="</coordinates></LinearRing></outerBoundaryIs>"
irh="<innerBoundaryIs><LinearRing><coordinates>"
irf="</coordinates></LinearRing></innerBoundaryIs>" proj=epsg:4326
precision=10]
</MultiGeometry>
An attribute table “item”, with list formatting options. The “name” attribute is required.
Available only when processing query results.
Available attributes:
The name of an attribute, case insenstive. (required)
The number of decimal places to use for numeric data. Use of this will force display as a number and will lead to unpredicable results with non-numeric data.
Regular expression to compare the value of an item against. The tag is output only if there is a match.
Set this attribute to “true” to convert the attribute value to upper case.
Set this attribute to “true” to convert the attribute value to lower case.
Set this attribute to “true” to add commas to a numeric value. Again, only useful with numeric data.
Default escaping is for HTML, but you can escape for inclusion in a URL (=url), or not escape at all (=none).
A format string used to output the attribute value. The token “$value” is used to place the value in a more complex presentation. Default is to output only the value.
String to output if the attribute value is NULL, empty or doesn’t match the pattern (if defined). If not set and any of these conditions occur the item tag is replaced with an empty string.
As a simple example:
[item name="area" precision="2" commify="2" format="Area is $value"]
Attribute name from the data table of a queried layer. Only attributes for the active query layers are accessible. Case must be the same as what is stored in the data file. ArcView, for example, uses all caps for shapefile field names. Available only when processing query results.
By default the attributes are encoded especially for HTML representation. In addition the escaped version (for use in URLs) as well as the raw data is available.
[Join name_attribute name],[Join name_attribute name_esc], [Join name_attribute name_raw]
One-to-one joins: First the join name (as specified in the Mapfile has to be given, second the tables fields can be accessed similar to the layers attribute data. Available only when processing query results.
By default the attributes are encoded especially for HTML representation. In addition the escaped version (for use in URLs) as well as the raw data is available.
Queried layer meta data access (e.g [metadata_projection]
Also available as escaped version.
For query modes that allow for multiple result sets, the following string substitutions are available. For FEATURESELECT and FEATURENSELECT modes the totals a re adjusted so as not to include the selection layer. The selection layer results ARE available for display to the user.
A small example to give an idea how to work with templates. Note that it covers MapServer specific templates (e.g. the [map], [mapext]) and user defined templates (e.g. [htmlroot] or [program]) used to store application settings.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 | <!-- MapServer Template -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/transitional.dtd">
<html>
<head>
<title>MapServer Template Sample</title>
</head>
<body>
MapServer Template Sample<br>
<!-- The central form the application is based on. -->
<form method="GET" action="[program]">
<!-- CGI MapServer applications are server stateless in principle,
all information must be "stored" in the client. This includes
some basic settings as below.
The example is based on the pan and zoom test suite:
http://maps.dnr.state.mn.us/mapserver_demos/tests36/ -->
<input type="hidden" name="map" value="[map]">
<input type="hidden" name="imgext" value="[mapext]">
<input type="hidden" name="imgxy" value="149.5 199.5">
<input type="hidden" name="program" value="[program]">
<input type="hidden" name="htmlroot" value="[htmlroot]">
<input type="hidden" name="map_web" value="[map_web]">
<!-- A table for minimal page formatting. -->
<table border=0 cellpadding=5>
<tr>
<!-- First column: Map and scale bar -->
<td align=center>
<!-- The map -->
<input type="image" name="img" src="[img]"
style="border:0;width:300;height:400">
<br>
<!-- The scale bar-->
<img src="[scalebar]" alt="Scale Bar">
</td>
<!-- Second column: Zoom direction, Legend and Reference -->
<td valign=top>
<!-- Zoom direction -->
<b>Map Controls</b><br>
Set your zoom option:<br>
<select name="zoom" size="1">
<option value="2" [zoom_2_select]> Zoom in 2 times
<option value="1" [zoom_1_select]> Recenter Map
<option value="-2" [zoom_-2_select]> Zoom out 2 times
</select>
<br>
<!-- Legend -->
<b>Legend</b><br>
<img src="[legend]" alt="Legend"><br><br><br><br>
<!-- Reference map -->
<input type="image" name="ref" src="[ref]"
style="border:0;width:150;height:150">
</td>
</tr>
</table>
</form>
</body>
</html>
|