Geomajas printing plug-in

Geomajas Developers and Geosparc

2.5.0-SNAPSHOT


Table of Contents

1. Introduction
1. Back-end
2. Configuration
1. Dependency configuration
2. GWT face configuration
2.1. GWT module definition
2.2. Example toolbar configuration
3. Usage
4. How-to

List of Figures

1.1. Print components
2.1. Toolbar icon for printing
3.1. Printing preferences dialog
3.2. Example print

List of Examples

2.1. printing plug-in dependency for GWT face using geomajas-dep
2.2. printing plugin dependencies - including source
2.3. Inherit the GWT module for the printing plug-in.
2.4. example toolbar

Chapter 1. Introduction

Table of Contents

1. Back-end

This printing plugin provides a simple yet compelling example of how platform independent web map printing might be implemented. Our implementation bypasses the browsers native printing functionality by rendering server side to a PDF document, which is then automatically downloaded to the browser. The PDF document can either be saved to the file system or opened in a new browser window from which native PDF printing is possible. As different browsers are allowed to - and will - render identical HTML pages in a slightly different manner, an absolute format like PDF is a necessity for creating reproducible prints.

Our implementation makes extensive use of the excellent iText library[1], which allows direct drawing operations on a graphics context. This has the advantage of preserving the vectorial nature of the features in a layer, allowing crisp vector rendering at any zoom level.

1. Back-end

The printing plug-in consists of a client part (the GWT face) that is responsible for the user interaction and a back-end part that is responsible for the generation of the PDF document. To achieve sufficient flexibility in the layout and composition of the PDF document, the document is conceptually a tree of nested components, each of which is responsible for its own rendering.

The following set of components have been implemented:

  • PageComponent: a container component for the complete PDF page.

  • MapComponent: this represents the main map. The layers, scale bar, legend and other components are child members of the map.

  • LabelComponent: can be used for an arbitrary text label, e.g. a title.

  • ImageComponent: represents an arbitrary static image, e.g. a north arrow on a map.

  • VectorlayerComponent: draws a vector layer on the map.

  • RasterLayerComponent: draws a raster layer on the map.

  • ScaleBarComponent: draws a scale bar on the map.

  • LegendComponent: draws a legend on the map.

  • ViewPortComponent: a view port is a smaller map that is an inset of the main map and is used to highlight details of the main map.

Figure 1.1. Print components

Print components

The layout is determined by recursively calculating the preferred size of each component first (which can vary according to font sizes, margins, etc...) followed by a second pass in which the layout constraints of each component are used to align the component with respect to its parent. This approach is top-down, starting with the root PageComponent. The following layout constraints are possible:

  • width: the preferred width of the component.

  • height: the preferred height of the component.

  • marginX: the margin in the x-direction or the x-position in case of absolute alignment in the x-direction.

  • marginY: the margin in the y-direction or the y-position in case of absolute alignment in the y-direction.

  • alignmentX: the alignment type in the x-direction (left, right, justified or absolute).

  • alignmentY: the alignment type in the y-direction (left, right, justified or absolute).



[1] "iText is a library that allows you to generate PDF files on the fly", see http://itextpdf.com/

Chapter 2. Configuration

Apart from the maven dependency configuration, most of the configuration options of the printing plugin are currently provided by the end user at runtime. To provide access to the plugin's functionality from the GWT face, an action has been provided that pops up a printing preferences window.

1. Dependency configuration

To use the printing plugin, you have to include the plug-in dependencies in your pom. When using this in the GWT face and you already have a dependency on geomajas-dep version 1.10.36 or higher, you can declare this as :

Example 2.1. printing plug-in dependency for GWT face using geomajas-dep

<dependency>
    <groupId>org.geomajas.plugin</groupId>
    <artifactId>geomajas-plugin-printing-gwt</artifactId>
</dependency>

When not using the version from geomajas-dep, you may need to declare versions for both the back-end part of the plug-in and the GWT face part.

Example 2.2. printing plugin dependencies - including source

        <dependency>
            <groupId>org.geomajas.plugin</groupId>
            <artifactId>geomajas-plugin-printing-gwt</artifactId>
        </dependency>
        

2. GWT face configuration

2.1. GWT module definition

In order to be able to use the printing plug-in in a GWT application, you will need to include the GWT module for the printing plug-in in your applications GWT module definition. In order to do this, add the following configuration line to your applications .gwt.xml file:

Example 2.3. Inherit the GWT module for the printing plug-in.

    
    <inherits name="org.geomajas.plugin.printing.gwt.example.PrintingExample"/>


This will make the GWT widgets and their source (assuming you have the jars on the classpath) available for the GWT compiler.

2.2. Example toolbar configuration

To use the printing functionality in a map, the following ClientToolInfo bean should be added to the map's toolbar:

Example 2.4. example toolbar

<property name="toolbar">
    <bean name="printingMapToolbar" class="org.geomajas.configuration.client.ClientToolbarInfo">
        <property name="tools">
            <list>
                <ref bean="ShowDefaultPrint"/>
            </list>
        </property>
    </bean>
</property>

The name of the ClientToolInfo bean should be exactly as spelled in the above program listing.

If configured correctly, the following tool icon will show up in the toolbar:

Figure 2.1. Toolbar icon for printing

Toolbar icon for printing

Chapter 3. Usage

To start using the printing functionality, the user should activate the printing tool in the toolbar by clicking the tool button ().

The following printing preferences dialog will now appear:

Figure 3.1. Printing preferences dialog

Printing preferences dialog

The user can customize the PDF print according to the following options:

  • Title: textbox that allows the user to add an optional title to the print. The title appears centered at the top.

  • Size: dropdown box to choose the page size, defaults to A4

  • Orientation: landscape or portrait orientation

  • Show north arrow: if checked, a north arrow will be added at the upper right of the map

  • Show scale bar: if checked, a scalebar will be added at the lower left of the map

  • Raster DPI: slidebar to choose a DPI value for raster layers. The DPI (Dots Per Inch) value, or - more correctly, but less generally known - PPI (Pixel Per Inch) value, indicates the number of pixels that will be used per inch in the print. In general, good resolution printing requires a value of at least 300-400 PP, much more than the average screen resolution. PDF size and rendering time will increase proportionally with the square of the DPI.

  • Dowload method: the PDF document can be saved on the file system or immediately opened in the browser. The latter option requires the user to allow popups for the main page.

  • Status: an activity bar to indicate printing progress. The activity bar does not show real progress as it is impossible to determine the file size or rendering time up front.

After configuring the preferences, the user should click the print button to start printing. This initiates the following proces:

  • A printing command is sent to the server

  • The PDF document is generated in-memory and a unique key is returned to the client. During this stage, the activity bar is activated

  • The client fetches the PDF by opening a URL with the generated key as parameter, either in a new window or in an invisible iframe (for download to the file system).

The final result looks as follows:

Figure 3.2. Example print

Example print

Chapter 4. How-to