Print Module : general architecture

This module is split in two:

1. Client side, a set of JS classes (see the demo):
   • mapfish.PrintProtocol: Non-GUI dependant class for communicating with the server side.
   • mapfish.widgets.print.SimpleForm: Ext panel allowing to print a single page document.
   • mapfish.widgets.print.MultiPage: Ext panel allowing to print a multipage document.
   • mapfish.widgets.print.PrintAction: An Ext action for getting a PDF in a simple click.
2. Server side, four implementations:
   • ShellMapPrinter: A command line implementation of the map printing service. Used mainly by the python/ruby implementations and for debug.
   • MapPrinterServlet: A java servlet implementing the protocol used by mapfish.PrintProtocol.
   • PrinterController: A Pylons servlet implementing the protocol used by mapfish.PrintProtocol. It uses ShellMapPrinter to enter the java world and do the work.
   • Print a Ruby on Rails controller implementing the protocol used by mapfish.PrintProtocol.

The server side uses a YAML configuration file that defines the page layouts and allowed values. For more details see the "Server side Configuration" chapter.

The client side, before displaying the forms, can request the server side about the available page layouts, the allowed scales and resolutions.

Requirements

If you use MapServer, you'll certainly have to change you MAP file and add a MAXSIZE parameters. By default, MapServer has a limitation of 2048x2048 which is often not enough for high DPIs. For SVG output, it's even worse since the print module asks for higher map sizes to have a better accuracy for the feature's coordinates.

Installation

See Print Module Installation.

Tutorial

Mapfish printing (WMS) for newbies?

Server side Configuration

See Print Module Server.

Protocol

Four commands are available and are documented in the next sections.

Every command uses the HTTP status code to notify errors.

info.json

HTTP command:

GET {PRINT_URL}/info.json?url={PRINT_URL}%2Finfo.json&var=printConfig

Returns a JSON structure as such:

var printConfig = {
    "scales":[
        {"name":"25000"},
        {"name":"50000"},
        {"name":"100000"}
    ],
    "dpis":[
        {"name":"190"},
        {"name":"254"}
    ],
    "layouts":[
        {
            "name":"A4 portrait",
            "map":{
                "width":440,
                "height":483
            }
        }
    ],
    "printURL":"http:\/\/localhost:5000\/print\/print.pdf",
    "createURL":"http:\/\/localhost:5000\/print\/create.json"
}

This can be loaded through an HTML script tag like that:

<script type="text/javascript"
        src="http://localhost:5000/print/info.json?var=printConfig"></script>

Or through an AJAX request by omitting the "var" query parameter. All the print widget implementations have a "configUrl" parameter. If this parameter is set, the widget will do this request by AJAX automatically.

The "url" query parameter is here to help the print servlet to know what URL is used by the browser to access the servlet. This parameter is here because the servlet can be behind a proxy, hiding the real URL.

print.pdf

HTTP command:

GET {PRINT_URL}/print.pdf?spec={SPEC}

The "SPEC" parameter is a JSON structure like that:

{
    layout: 'A4 portrait',
    ...CUSTOM_PARAMS...
    srs: 'EPSG:4326',
    units: 'degrees',
    layers: [
        {
            type: 'WMS',
            layers: ['basic'],
            baseURL: 'http://labs.metacarta.com/wms/vmap0',
            format: 'image/jpeg'
        }
    ],
    pages: [
        {
            center: [6, 45.5],
            scale: 4000000,
            dpi: 190,
            ...CUSTOM_PARAMS...
        }
    ]
}

The location to show on the map can be specified with a center and a scale as show or with a bbox like that:

   bbox: [5, 45, 6, 46]

The print module will use the nearest scale and will make sure the aspect ratio stays correct.

There are two locations where custom parameters can be added. Those will be ignored by the web service but, will be accessible from the layout templates.

For the format of the layers section, please look at the implementations pointed by mapfish.PrintProtocol.SUPPORTED_TYPES.

This command returns the PDF file directly.

create.json

HTTP command:

POST {PRINT_URL}/create.json?url={PRINT_URL}%2Fcreate.json

The spec defined in the "print.pdf" command must be included in the POST body.

Returns a JSON structure like that:

{
    getURL: 'http:\/\/localhost:5000\/print\/56723.pdf'
}

The URL returned can be used to retrieve the PDF file. See the next section.

{ID}.pdf

This command's URL is returned by the "create.json" command.

HTTP command:

GET {PRINT_URL}/{ID}.pdf

Returns the PDF. Can be called only during a limited time since the server side temporary file is deleted afterwards.

Client side

See Print Module Client

FAQ

See Print Module Faq