.. index::
single: Template-driven output
.. _template_output:
*****************************************************************************
Template-Driven Output
*****************************************************************************
:Author: Chris Hodgson
:Contact: chodgson at refractions.net
:Last Updated: 2011-04-13
.. contents:: Table of Contents
:depth: 2
:backlinks: top
Introduction
============
RFC 36 added support for defining template-driven OUTPUTFORMATs for use with
feature queries, including WMS GetFeatureInfo and WFS GetFeature. This allows
for custom text-oriented output such as GeoJSON, KML, or XML.
The templates are essentially the same as with the standard MapServer query
:ref:`Template`, however there are some additional tags to allow for template
definition in a single file instead of the standard header/template/footer.
.. note::
There are other, simpler, ways to output some of these formats
using MapServer. However, template-driven output provides maximal
flexibility and customization of the output, at the cost of
additional complexity and configuration.
.. index::
pair: Template-driven output; OUTPUTFORMAT
OUTPUTFORMAT Declarations
=========================
Details of template-driven output formats are controlled by an
:ref:`OUTPUTFORMAT` declaration. The declarations define the template
file to be used, as well as other standard OUTPUTFORMAT options.
Examples:
.. code-block:: mapfile
OUTPUTFORMAT
NAME "kayml"
DRIVER "TEMPLATE"
MIMETYPE "application/vnd.google-earth.kml+xml"
FORMATOPTION "FILE=myTemplate.kml"
FORMATOPTION "ATTACHMENT=queryResults.kml"
END
OUTPUTFORMAT
NAME "geojson"
DRIVER "TEMPLATE"
FORMATOPTION "FILE=myTemplate.json"
END
OUTPUTFORMAT
NAME "customxml"
DRIVER "TEMPLATE"
FORMATOPTION "FILE=myTemplate.xml"
END
The template file to be used is determined by the "FILE=..." FORMATOPTION.
The template filename is relative to the mapfile's path. As is standard with
MapServer template files, the file must containt the magic string
‘mapserver template’ in the first line of the file, usually within a comment,
but this line is not output to the client.
Note that both the MIMETYPE and FORMATOPTION "ATTACHMENT=..." parameters are
very useful for controlling how a web browser handles the output file.
.. index::
pair: Template-driven output; Template substitution tags
Template Substitution Tags
==========================
These tags only work in query result templates, and their purpose is primarily
to simplify the templating to a single file for custom ouput formats.
[include src="otherTemplate.txt"]
Includes another template file; the path to the template file is relative
to the mapfile path.
Attributes:
* src: The file to be included.
[resultset layer=layername]...[/resultset]
Defines the location of the results for a given layer.
Attributes:
* layer: The layer to be used
* nodata: (optional) A string to return if no results are returned.
[feature]...[/feature]
Defines the loop around the features returned for a given layer.
Attributes:
* limit: (optional) Specifies the maximum number of features to
output for this layer.
* trimlast: (optional) Specifies a string to be trimmed off of the
end of the final feature that is output. This is intended to
allow for trailing record delimiters to be removed. See the
examples below.
[join name=join1]...[/join]
defines the loop around the features join from another layer.
.. seealso::
:ref:`template`
Examples
========
This example shows how to emulate the old 3-file system using the new system,
to compare the usage:
::
[include src="templates/header.html"]
[resultset layer=lakes]
... old layer HEADER stuff goes here, if a layer has no results
this block disappears...
[feature]
...repeat this block for each feature in the result set...
[join name=join1]
...repeat this block for each joined row...
[/join]
[/feature]
...old layer FOOTER stuff goes here...
[/resultset]
[resulset layer=streams]
... old layer HEADER stuff goes here, if a layer has no results
this block disappears...
[feature]
...repeat this block for each feature in the result set...
[/feature]
...old layer FOOTER stuff goes here...
[/resultset]
[include src="templates/footer.html"]
A specific GML3 example:
::
[resultset layer=mums]
Area: [AREA_KILOMETERS_SQUARED] sq km
]]>