Short Tutorial on MapFish Printing

From:
Date:
Author(s):
Email:
Version:

Just Objects B.V.

August 31, 2009
Just van den Broecke
just@justobjects.nl
1.0

Introduction
MapFish Printing is a module within the MapFish (MF) framework. This framework is described on
www.mapfish.org as follows:
MapFish is an easy-to-use and extensible web 2.0 mapping application framework.
MapFish is composed of two parts: MapFish Client and MapFish Server. MapFish Client is a JavaScript
framework based on OpenLayers for the mapping part, on ExtJS and GeoExt for the GUI part. MapFish
Server is responsible for server side treatments and is composed of several modules which can be
implemented in several languages such as Python, Java, Ruby, PHP or others.
MapFish is cartographic server agnostic. It can be used with MapServer, GeoServer, MapGuide or whatever
cartographic server that is able to communicate with open protocols like WMS or WFS.
For the server-side of MapFish there are several implementations, including Java. Although MapFish
provides many mainly GUI (widgets) functions, we will focus here on the MF Printing module, and in
particular its integration with GeoServer.

How MapFish Printing Works

Basically MapFish printing is a standardized web service API, although direct invocation in Java is also
possible. The MF printing standard has two main parts that work in concert:
1. MapFish printing protocol (client spec)
This is a protocol for requests mainly to create and/or fetch PDF files from a server. In order to indicate
what exactly needs to be printed the protocol-client supplies a specification (the client spec), for
example which layers in a map, and other parameters. Some parameters in the client spec are not fixed
but depend on the second part of the MF Print standard: the MF Print configuration (the YAML file).
This is discussed below under (2).
Any client in Java or other language may invoke the MapFish protocol service. Web clients usually will
use GeoExt/OpenLayers but Java-based clients are possible as well. The protocol format is using JSON
encoding. See Appendix 1 for an example. A JS implementation is available in the MapFish core:
http://www.mapfish.org/apidoc/trunk/files/mapfish/core/PrintProtocol-js.html
2. MapFish Printing configuration file (the YAML file)
The server side uses a YAML configuration/template file that defines the page layouts and allowed
values. YAML, see www.yaml.org, is basically a mark-up language and chosen over XML by the MF
team. Best is to look at the MF YAML-file documentation:
http://trac.mapfish.org/trac/mapfish/wiki/PrintModuleServer . The YAML file defines a set of layouts that a
client can specify in the print PDF request. In addition, and here MF printing becomes really powerful,
specific parts of the YAML file can be parameterized with actual values supplied by the client at requesttime. For example, a cadastral parcel may have an area that is specified as a parameter in the YAML file
using a declaration like ${parcel_area}. The client, who may have the actual parcel area from another
web service, provides the actual value during the PDF creation request {...parcel_area: 35414...} in the
client spec. See Appendix 2 for an example YAML file.
Basic Print Scenario
The following steps denote the core MF print scenario between client and server.

1. client: sends print spec to MF server URL (see example Appendix 1).
The main parameters in the spec are: map-center, map-scale, layout, dpi. For each map-layer the client
mainly supplies the base URL of each WMS. Also parameters to be substituted are supplied.
2. server: generates PDF and returns unique URL to this PDF
Within the actual processing and rendering the server will construct the WMS URLs for each layer in the
client spec and will fetch the map images from each remote WMS server. The server uses the YAML file
to render the PDF.
3. client: fetches PDF from the returned PDF URL in step 2.

MF Print Server Java Implementation

Since MF Printing is basically a web service protocol plus a configuration file, multiple server-side
implementations can be realized. Besides Python, MF printing is also provided through a Java library. This
Java library (called print-lib) can be invoked through a related Java Servlet (part of print-lib) in any webapplication or directly. For PDF generation print-lib uses the open source iText PDF Java library (http://
www.lowagie.com/iText). The print-lib is also available in a Maven repository, such that it could be
included into a Maven-build.
The GeoServer integration is provided by a wrapper for print-lib that plugs this library into GeoServers
Spring Beans framework as a GeoServer Community Extension. The steps to install the Printing Community
Extension are described in:
http://geoserver.org/display/GEOS/Printing+2.0+HOWTO

So there are three ways to integrate MF Printing:

1) as a JavaServlet in your web application (war)
2) as a GeoServer community extension (in the GS war)
3) directly by using classes in the print-lib library

Appendix 1: Example Client Spec

The JSON spec below is POSTed e.g. through the URL
http://www.myserver.nl/geoserver/pdf/create.json?url=&geoserver&pdf&create.json
{"pages":[

{


"center":[4.984375,51.50390625],


"mapTitle":"Map title",


"comment":"Some comments", // substitutes into ${comment} in YAML


"scale": 50000,


"rotation":"0"

}

],"dpi":"75","units":"degrees","srs":"EPSG:4326","layers":[

{


"baseURL":"http://labs.metacarta.com/wms/vmap0",


"opacity":1,


"singleTile":false,


"customParams":{},


"type":"WMS",


"layers":["basic"],


"format":"image/jpeg",


"styles":[],


"overview":true

},

{


"baseURL":"http://demo.mapfish.org/mapfishsample/trunk/wms?",


"opacity":1,


"singleTile":true,


"customParams":{"TRANSPARENT":true},


"type":"WMS",


"layers":["countries"],


"format":"image/svg+xml",


"styles":[],


"overview":false

},

{



"baseURL":"http://localhost:8080/geoserver/wms?",


"opacity":1,


"singleTile":true,


"customParams":{"TRANSPARENT":true},


"type":"WMS",


"layers":["topp:states"],


"format":"image/png",


"styles":[],


"overview":false

}
],"layout":"A4 portrait"}

Appendix 2: Example Server YAML Config File

#===========================================================================
# allowed DPIs
#===========================================================================
dpis: [75, 150, 300]
#===========================================================================
# the allowed scales
#===========================================================================
scales:
- 25000
- 50000
- 100000
- 200000
- 500000
- 1000000
- 2000000
- 4000000
#===========================================================================
# the list of allowed hosts
#===========================================================================
hosts:
- !localMatch
dummy: true
- !ipMatch
ip: www.camptocamp.org
- !dnsMatch
host: labs.metacarta.com
port: 80
- !dnsMatch
host: terraservice.net
port: 80
- !dnsMatch
host: sigma.openplans.org
- !dnsMatch
host: demo.mapfish.org
layouts:
Legal:
mainPage:
pageSize: LEGAL
items:
- !map
spacingAfter: 30
width: 440
height: 483
#===========================================================================
A4 portrait:
#===========================================================================
metaData:
#
title: '${mapTitle}'

author: 'MapFish print module'

subject: 'Simple layout'
keywords: 'map,print'
creator: 'MapFish'
titlePage:
pageSize: A4
items:
- !text
spacingAfter: 150
- !text
font: Helvetica
fontSize: 40
spacingAfter: 100
align: center
text: '${layout}'
- !image
maxWidth: 160
maxHeight: 160
spacingAfter: 100
align: center
url: http://trac.mapfish.org/trac/mapfish/attachment/ticket/3/
logo_v8_sphere.svg?format=raw
footer: &commonFooter
height: 30
items:
- !columns
config:
cells:
- paddingBottom: 5
items:
- !text
backgroundColor: #FF0000
align: left
text: a red box
- !text
align: right
text: 'Page ${pageNum}'
- !image
align: center
maxWidth: 100
maxHeight: 30
spacingAfter: 200
url: 'http://geoserver.org/download/attachments/10158143/pbGSBttn228x68.png'

#
#
#
#
#
#
#
#

#------------------------------------------------------------------------mainPage:
pageSize: A4
rotation: true
header:
height: 50
items:
- !text
font: Helvetica
fontSize: 30
align: right
text: '${layout}'
items:
- !text
text: '${mapTitle}'
fontSize: 30
spacingAfter: 30
- !map
spacingAfter: 30

width: 440
height: 483
- !columns
# columns can have an absolute position. In that case, they need the 3
following fields:
absoluteX: 410
absoluteY: 310
width: 100
items:
- !scalebar
type: bar
maxSize: 100
barBgColor: white
fontSize: 8
align: right
- !text
text: '${comment}'
spacingAfter: 30
- !attributes
source: data
spacingAfter: 30
columnDefs:
id:
columnWeight: 2
header: !text
text: ID
backgroundColor: #A0A0A0
cell: !text
text: '${id}'
name:
columnWeight: 5
header: !text
text: Name
backgroundColor: #A0A0A0
cell: !columns
config:
cells:
- backgroundColor: '${nameBackgroundColor}'
borderWidth: 1
borderColor: '${nameBorderColor}'
items:
- !text
text: '${name}'
icon:
columnWeight: 2
header: !text
text: Symbol
backgroundColor: #A0A0A0
cell: !image
align: center
maxWidth: 15
maxHeight: 15
url: 'http://www.mapfish.org/svn/mapfish/trunk/MapFish/client/mfbase/
mapfish/img/${icon}.png'
- !text
font: Helvetica
fontSize: 9
align: right
text: '1:${scale} ${now MM.dd.yyyy}'
footer: *commonFooter