02-Time Templates

This tutorial is targeted for GeoServer 1.5.2 and above. This tutorial assumes that GeoServer is running on http://localhost:8080/geoserver.

Getting Started
Checking the Setup
Creating the Template
Trying it Out
Reference

Getting Started

For this tutorial we will using a Shapefile which contains information about the number of Internet users in the countries of Western Europe for a rang of years.

1. Download and unzip inet_weu.zip
2. Configure GeoServer to serve the Shapefile inet_weu.zip. (A tutorial is available for publishing a Shapefile in GeoServer.)
3. Add the SLD inet_weu.sld to GeoServer. ( A tutorial is available for adding a style in GeoServer)
4. Set the style of the feature type added in step 2 to the style added in step 3

Checking the Setup

If all is configured properly you should be able to navigate to http://localhost:8080/geoserver/wms/kml?layers=topp:inet_weu&format=openlayers&bbox=-33.780,26.266,21.005,56.427 and see the following map:

Creating the Template

Next we will create a template which allows us to specify the temporal aspects of the dataset. The schema of our dataset looks like:

The temporal attribute is RPT_YEAR and is the one that matters to us. Ok, time to create the template.

1. In your text editor of choice, create a new text file called time.ftl.
2. Add the following text:

   ${RPT_YEAR.value?date('yyyy')}
   

3. Save the file to the <GEOSERVER_DATA_DIR>/featureTypes/inet_weu_inet_weu directory. Where <GEOSERVER_DATA_DIR> is the location of the "data directory" of your GeoServer installation. Usually pointed to via the GEOSERVER_DATA_DIR environment variable.

See the Reference section for more information about specifying a date format.

Trying it Out

Ok time to try it out.

1. Navigate to http://localhost:8080/geoserver/wms/kml_reflect?layers=inet_weu&legend=true. This should cause Google Earth to open.
   
   
   
2. In Google Earth, adjust the time bar so that it captures a time interval that is approximately 1 year wide
   
   
   
3. Slide the time bar forward in time and notice how the polygon colors change
   

Reference

Specifying a Date Format

When setting up a time template for your own dataset the most important issue is the format of your temporal data. It may or may not be in a format in which GeoServer can read directly. You can check if the date/time format can be used directly by GeoServer by using the following time template.

${DATETIME_ATTRIBUTE_NAME.value}

While GeoServer will try its best to parse the data there are cases in which your data is in a format which it cannot parse. When this occurs it is necessary to explicitly specify the format. Luckily Freemarker provides us with functionality to do just this.

Consider the date time 12:30 on January 01, 2007 specified in the following format: 01?01%2007&12$30!00. When creating the template we need to explicitly tell Freemarker the format the date time is in with the datetime function.

${DATETIME_ATTRIBUTE_NAME.value?datetime("M?d%y&H:m:s")}

The process is similar for dates (no time). The date 01?01%2007 would be specified in a template as:

${DATETIME_ATTRIBUTE_NAME.value?date("M?d%y")}

So when must you specify the date format in this manner? The following table illustrates the date formats that GeoServer can understand:

The '-' character can be one of any of the following characters: '/' (forward slash), ' ' (space), '.' (period), ',' (comma)


The set of date time formats which GeoServer can be understand is formed by appending the timestamp formats hh:mm and hh:mm:ss to the entries in the above table:

Setting the Timezone Be aware that the KML output for date time formats will reflect the timezone of the java virtual machine, which can be set using the user.timezone parameter in the startup script. For example, the following command starts GeoServer using the Coordinated Universal Time (UTC) timezone. exec "$_RUNJAVA" -DGEOSERVER_DATA_DIR="$GEOSERVER_DATA_DIR" -Djava.awt.headless=true -DSTOP.PORT=8079 -Duser.timezone=UTC -DSTOP.KEY=geoserver -jar start.jar If the timezone is not set, it will default to the timezone of the operating system.

Specifying a Date Range

In the above example a single time stamp is output for the dataset. GeoServer also supports specifying date ranges via a template. The syntax for ranges is:

<begin>||<end>

Where begin is the first date in the range, end is the last date in the range, and || is the delimiter between the two. As an example:

01/01/2007||06/01/2007

Would the date range starting at January 1, 2007 and ending June 1, 2007. Date ranges can also be open ended:

||06/01/2007
06/01/2007||

The first date specifies a date range where the beginning is open-ended. The second specifies a date range where the end is open-ended.