This tutorial will introduce you to a more in depth view of what FreeMarker templates are and how you can use the data provided to templates by GeoServer.

Freemarker is a simple yet powerful template engine that GeoServer uses whenever developer allowed user customization of outputs. In particular, at the time of writing it’s used to allow customization of GetFeatureInfo, GeoRSS and KML outputs.

Freemarker allows for simple variable expansions, as in ${myVarName}, expansion of nested properties, such as in ${feature.myAtt.value}, up to little programs using loops, ifs and variables.
Most of the relevant information about how to approach template writing is included in the Freemarker’s Designer guide and won’t be repeated here: the guide, along with the KML Placemark Templates and GetFeatureInfo Templates tutorials should be good enough to give you a good grip on how a template is built.

GeoServer looks up templates in three different places, allowing for various level of customization. For example given the content.ftl template used to generate WMS GetFeatureInfo content:

Look into GEOSERVER_DATA_DIR/workspaces/<workspace>/<datastore>/<featuretype>/content.ftl to see if there is a feature type specific template

Look into GEOSERVER_DATA_DIR/workspaces/<workspace>/<datastore>/content.ftl to see if there is a store specific template

Look into GEOSERVER_DATA_DIR/workspaces/<workspace>/content.ftl to see if there is a workspace specific template

Look into GEOSERVER_DATA_DIR/workspaces/content.ftl looking for a global override

Look into GEOSERVER_DATA_DIR/templates/content.ftl looking for a global override

Look into the GeoServer classpath and load the default template

Each templated output format tutorial should provide you with the template names, and state whether the templates can be type specific, or not. Missing the source for the default template, look up for the service jar in the geoserver distribution (for example, wms-x.y.z.jar), unpack it, and you’ll find the actual xxx.ftl files GeoServer is using as the default templates.

Freemarker calls “data model” the set of data provided to the template. Each output format used by GeoServer will inject a different data model according to the informations it’s managing, yet there are three very common elements that appear in almost each template, Feature, FeatureType and FeatureCollection. Here we provide a data model of each.

The data model is a sort of a tree, where each element has a name and a type. Besides basic types, we’ll use:

list: a flat list of items that you can scan thru using the FreeMarker <#list> directive;

map: a key/value map, that you usually access using the dot notation, as in ${myMap.myKey}, and can be nested;

listMap: a special construct that is, at the same time, a Map, and a list of the values.

Here are the data models (as you can see there are redundancies, in particular in attributes, we chose this approach to make template building easier):

FeatureType (map)

name (string): the type name

attributes (listMap): the type attributes

name (string): attribute name

namespace (string): attribute namespace URI

prefix (string): attribute namespace prefix

type (string): attribute type, the fully qualified Java class name

isGeometry (boolean): true if the attribute is geometric, false otherwise

Feature (map)

fid (string): the feature ID (WFS feature id)

typeName (string): the type name

attributes (listMap): the list of attributes (both data and metadata)

name (string): attribute name

namespace (string): attribute namespace URI

prefix (string): attribute namespace prefix

isGeometry (boolean): true if the attribute is geometric, false otherwise