[mapserver-commits] r11605 - trunk/docs/en/output
svn at osgeo.org
svn at osgeo.org
Wed Apr 20 12:56:02 EDT 2011
Author: tbonfort
Date: 2011-04-20 09:56:01 -0700 (Wed, 20 Apr 2011)
New Revision: 11605
Added:
trunk/docs/en/output/template_output.txt
Modified:
trunk/docs/en/output/index.txt
Log:
add documentation for template output (#3838)
Modified: trunk/docs/en/output/index.txt
===================================================================
--- trunk/docs/en/output/index.txt 2011-04-19 21:57:08 UTC (rev 11604)
+++ trunk/docs/en/output/index.txt 2011-04-20 16:56:01 UTC (rev 11605)
@@ -18,5 +18,6 @@
pdf
svg
tile_mode
+ template_output
kml_output
Added: trunk/docs/en/output/template_output.txt
===================================================================
--- trunk/docs/en/output/template_output.txt (rev 0)
+++ trunk/docs/en/output/template_output.txt 2011-04-20 16:56:01 UTC (rev 11605)
@@ -0,0 +1,295 @@
+.. _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.
+
+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.
+
+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.
+
+[resultset name=layername]...[/resultset]
+ Defines the location of the results for a given layer.
+
+[feature]...[/feature]
+ Defines the loop around the features returned for a given layer.
+
+ Optional arguments:
+
+ - limit=
+ specifies the maximum number of features to output for this layer.
+
+ - trimlast=
+ 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.
+
+Examples
+========
+
+This example shows how to emulate the old 3-file system using the new system,
+to compare the usage:
+
+::
+
+ <!-- mapserver template -->
+ [include src="templates/header.html"]
+ [resultset name=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 name=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:
+
+::
+
+ <!-- mapserver template -->
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+ [resultset layer=mums]
+ <MapServerUserMeetings xmlns="http://localhost/ms_ogc_workshop" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://localhost/ms_ogc_workshop ./mums.xsd">
+ <gml:description>This is a GML document which provides locations of all MapServer User Meeting that have taken place</gml:description>
+ <gml:name>MapServer User Meetings</gml:name>
+ <gml:boundedBy>
+ <gml:Envelope>
+ <gml:coordinates>-93.093055556,44.944444444 -75.7,45.4166667</gml:coordinates>
+ </gml:Envelope>
+ </gml:boundedBy>
+ [feature]
+ <gml:featureMember>
+ <Meeting>
+ <gml:description>[desc]</gml:description>
+ <gml:name>[name]</gml:name>
+ <gml:location>
+ <gml:Point srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">
+ <gml:pos>[x] [y]</gml:pos>
+ </gml:Point>
+ </gml:location>
+ <year>[year]</year>
+ <venue>[venue]</venue>
+ <website>[url]</website>
+ </Meeting>
+ </gml:featureMember>
+ [/feature]
+ <dateCreated>2007-08-13T17:17:32Z</dateCreated>
+ </MapServerUserMeetings>
+ [resultset]
+
+A GeoJSON example:
+
+::
+
+ // mapserver template
+ [resultset layer=mums]
+ {
+ "type": "FeatureCollection",
+ "features": [
+ [feature trimlast=',']
+ {
+ "type": "Feature",
+ "id": "[id]",
+ "geometry": {
+ "type": "PointLineString",
+ "coordinates": [
+ {
+ "type": "Point",
+ "coordinates": [[x], [y]]
+ }
+ ]
+ },
+ "properties": {
+ "description": "[description]",
+ "venue": "[venue]",
+ "year": "[year]"
+ }
+ },
+ [/feature]
+ ]
+ }
+ [/resultset]
+
+A more complicated KML example. Note the use of [shpxy] to support multipolygons
+with holes, and also that a point placemark is included with each feature using
+[shplabel]:
+
+::
+
+ <!--MapServer Template-->
+ <?xml version="1.0" encoding="UTF-8"?>
+ <kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom">
+ <Document>
+ <Style id="parks_highlight">
+ <IconStyle>
+ <scale>1.4</scale>
+ <Icon>
+ <href>http://maps.google.com/mapfiles/kml/shapes/parks.png</href>
+ </Icon>
+ <hotSpot x="0.5" y="0" xunits="fraction" yunits="fraction"/>
+ </IconStyle>
+ <LineStyle>
+ <color>ffff5500</color>
+ <width>4.2</width>
+ </LineStyle>
+ <PolyStyle>
+ <color>aaaaaaaa</color>
+ </PolyStyle>
+ <BalloonStyle>
+ <text>
+ <![CDATA[
+ <p ALIGN="center"><b>$[name]</b></p>
+ $[description]
+ ]]>
+ </text>
+ </BalloonStyle>
+ </Style>
+ <Style id="parks_normal">
+ <IconStyle>
+ <scale>1.2</scale>
+ <Icon>
+ <href>http://maps.google.com/mapfiles/kml/shapes/parks.png</href>
+ </Icon>
+ <hotSpot x="0.5" y="0" xunits="fraction" yunits="fraction"/>
+ </IconStyle>
+ <LineStyle>
+ <color>ffff5500</color>
+ <width>4.2</width>
+ </LineStyle>
+ <PolyStyle>
+ <color>ff7fff55</color>
+ </PolyStyle>
+ <BalloonStyle>
+ <text>
+ <![CDATA[
+ <p ALIGN="center"><b>$[name]</b></p>
+ $[description]
+ ]]>
+ </text>
+ </BalloonStyle>
+ </Style>
+ <StyleMap id="parks_map">
+ <Pair>
+ <key>normal</key>
+ <styleUrl>#parks_normal</styleUrl>
+ </Pair>
+ <Pair>
+ <key>highlight</key>
+ <styleUrl>#parks_highlight</styleUrl>
+ </Pair>
+ </StyleMap>
+ [resultset layer=parks]
+ <Folder>
+ <name>Parks</name>
+ [feature trimlast=',' limit=1]
+ <Placemark>
+ <name>[NAME]</name>
+ <Snippet/>
+ <description>
+ <![CDATA[
+ <p>Year Established: [YEAR_ESTABLISHED]</p>
+ <p>Area: [AREA_KILOMETERS_SQUARED] sq km</p>
+ ]]>
+ </description>
+ <styleUrl>#parks_map</styleUrl>
+ <ExtendedData>
+ <Data name="Year Established">[YEAR_ESTABLISHED]</Data>
+ <Data name="Area">[AREA_KILOMETERS_SQUARED]</Data>
+ </ExtendedData>
+ <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>
+ </Placemark>
+ [/feature]
+ </Folder>
+ [/resultset]
+ </Document>
+ </kml>
More information about the mapserver-commits
mailing list