html.master.html Maven / Gradle / Ivy
Show all versions of geomajas-plugin-printing-documentation
Geomajas printing plug-in Table of Contents
List of Figures
List of Examples
Table of Contents
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.
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.
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).
Table of Contents
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.
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>
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.
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:
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:
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:
