12. PDF Export

Plugin exportPdf

12.1. Introduction

This chapter describes how to configure PDF export, using client_conf/exportPdf.ini parameters.

First part (Section 12.2, “Configuration Reference”) is a comprehensive reference of user-available configuration parameters. Second part (Section 12.3, “Tutorial”) is intended to be a small tutorial giving explanations and examples about how to configure the PDF exportation tool.

12.2. Configuration Reference

12.2.1. General Configuration

Parameters are named using a <object>.<property> convention. These parameters are grouped within dedicated objects that deal with separated aspects of the export. For instance:

general.horizontalMargin = 10
general.verticalMargin = 10

formats.A4.label = A4
formats.A4.bigDimension = 297

Some objects handle the general description of the PDF document as well as user form generation: "general" and "formats".

Other objects are "blocks"-typed. They deal with block presentation (color, size, content, etc.) and positioning. Blocks are basic entities of the PDF document: text, images. For instance overview, mainmap, scalebar, title are described with block objects.

To factorize blocks description, it is possible to describe a "template" block object that defines the default configuration of blocks. Those default settings are then overriden by each block specific description.

  • general.formats (comma-separated list of strings): ids of available sheet sizes. Must match format objects names (see Formats configuration below).
  • general.defaultFormat (string): default selected/used format. Must be one of the above list items.
  • general.resolutions (comma-separated list of integers): list of available resolutions in dot-per-inch (dpi).
  • general.mapServerResolution (integer): resolution set in mapfile. Generally it is no use to set this parameter since its value is retrieved directly from the CartoServer. However you can use it to override this value (but this will not change the effective MapServer resolution).
  • general.defaultResolution (integer): default selected/used resolution. Must be one of the above list items.
  • general.defaultOrientation (portrait|landscape): sheet orientation. The same orientation is used for every pages of the PDF document.
  • general.activatedBlocks (comma-separated list of strings): names of blocks that will be used in the document. Names must match block objects names. See Blocks configuration section.
  • general.overviewScaleFactor (float): sets the extension of the overview map. The bigger this parameter, the wider the extension. Default: 10.
  • general.pdfEngine (CwFpdf|PdfLibLite): name of the PDF engine to use. For now only FPDF is available and must be called using "CwFpdf" pdfEngine value. A PDFLib Lite version is (very) partially implemented and as a result should not be used for now (pdfEngine value: "PdfLibLite").
  • general.pdfVersion (string): PDF version that must be used (only available with "PdfLibLite" pdfEngine).
  • general.output (inline|attachment|link|redirection): indicates how generated PDF file must be output (default: redirection). "inline": file is generated and displayed on the fly (might not work with buggy IE). "attachment": generated on the fly but a dialog box asks the user weither the file must be opened or saved. "link": PDF file is actually written on the server and a link pointing towards it is displayed. "redirection": PDF file is written on the server and than user's browser is automatically redirected towards it.
  • general.filename (string): indicates how generated PDF files must be named. It is possible to specify a date-formatting using PHP date format (see http://php.net/date). Default is map-[date,dMY-His].pdf which gives for instance map-03Jan2005-193256.pdf.
  • general.distUnit (mm|cm|pt|in): unit used to measure blocks distance properties. Only one unit can be used in the whole configuration.
  • general.horizontalMargin (float): horizontal distance between the sheet border and the useful area (in distUnit).
  • general.verticalMargin (float): vertical distance between the sheet border and the useful area (in distUnit).
  • general.allowedRoles (comma-separated list of strings): list of roles allowed to print PDF documents.
  • general.importRemotePng (boolean): if true, remote PNG files (gathered using a URL) are copied in a local directory before being included in the PDF document. This option is recommended when using urlProvider = Miniproxy in CartoServer settings and/or physically separated CartoClient and CartoServer (See Chapter 4, Configuration Files).

PHP built-in default values:

  • pdfEngine: CwFpdf
  • pdfVersion: 1.3
  • distUnit: mm
  • horizontalMargin: 10
  • verticalMargin: 10
  • formats: NULL
  • defaultFormat: NULL
  • resolutions: 96
  • mapServerResolution: 96
  • defaultResolution: 96
  • activatedBlocks: NULL
  • filename: map-[date,dMY-His].pdf
  • overviewScaleFactor: 10
  • output: redirection
  • allowedRoles: (empty ie. nobody)
  • importRemotePng: false

12.2.2. Formats Configuration

Formats are described as a set of "formats" sub-objects. For instance:

formats.A4.bigDimension = 297
formats.A4.smallDimension = 210

formats.A3.label = A3
formats.A3.bigDimension = 420

Format ids (A3, A4, etc.) must match those listed in general.formats.

  • formats.<format_name>.label (string): user-friendly name. Is translated using Cw3I18n device Chapter 14, Internationalization.
  • formats.<format_name>.bigDimension (float): largest sheet side (in distUnit).
  • formats.<format_name>.smallDimension (float): smallest sheet side (in distUnit).
  • formats.<format_name>.horizontalMargin (float): optional, if set, overrides general.horizontalMargin for the given format.
  • formats.<format_name>.verticalMargin (float): optional, if set, overrides general.verticalMargin for the given format.
  • formats.<format_name>.maxResolution (integer): optional, maximum allowed resolution for the given format. If selected resolution is above maxResolution, it will be set to maxResolution value.
  • formats.<format_name>.allowedRoles (comma-separated list of strings): list of roles allowed to use the format.

PHP built-in default values: all format parameters have NULL default values except allowedRoles ("all").

12.2.3. Blocks Configuration

All blocks parameters are optional since default values are hard-coded in the PDF export plugin PHP code (see code documentation for PdfBlock class). Those default properties can be partially or totally overriden using a template object whose syntax is similar to this:

template.type = text
template.fontFamily = times
template.fontSize = 12
template.fontItalic = false

whereas real blocks are described this way:

blocks.title.weight = 10
blocks.title.verticalBasis = top
blocks.title.verticalMargin = 15

"Template"-described properties have a global scope whereas "blocks" ones are specific to the given block. Properties names are identical for both "template" and "blocks" objects. Properties not related with the given block type are generally ignored (for instance "fontSize" is not taken into account if block is an image). A lots of properties use CSS-like denominations and effects. All following parameters names must be precede by either "template." or "blocks.<block_name>." prefixes.

  • type (text|image|table|legend): block type, indicates what kind of processing must be applied.
  • content (string): optional, for "text" blocks: the textual content ; for "image" blocks, the image filename ; for "table" blocks, a comma-separated list of textual content (limited to one row, commas delimit cells).
  • fontFamily (string): name of font family to use. Naming depends on used pdfEngine.
  • fontSize (float) : font size in points (pt)
  • fontItalic (boolean): if true, text will be emphasized.
  • fontBold (boolean): if true, text will be bold-weighted.
  • fontUnderline (boolean): if true, text will be underlined.
  • color (string): color of text in hexadecimal code #rrggbb. A few color aliases ("white", "black") are available as well.
  • backgroundColor (string): background color in hexadecimal code or color aliases.
  • borderWidth (float): border line width in distUnit.
  • borderColor (string): border line color in hexadecimal code or color aliases.
  • borderStyle (solid|dashed|dotted): border line style. Only available with "PdfLibLite" pdfEngine. "solid" value is used for other pdfEngines.
  • padding (float): vertical and horizontal distance between block content and its borders in distUnit.
  • horizontalMargin (float): horizontal margin in distUnit around the block (outside borders).
  • verticalMargin (float): vertical margin in distUnit around the block (outside borders).
  • horizontalBasis (left|right): indicates what document side must be used for horizontal positioning.
  • verticalBasis (top|bottom): indicates what document side must be used for vertical positioning.
  • hCentered (boolean): if true, block is horizontally centered (overloads horizontalBasis property).
  • vCentered (boolean): if true, block is vertically centered (overloads verticalBasis property).
  • textAlign (center|left|right): indicates how content must be horizontally aligned within the block extent.
  • verticalAlign (center|top|bottom): indicates how content must be vertically aligned within the block extent.
  • orientation (horizontal|vertical): indicates if content will be displayed form left to right or from bottom to top (only for text blocks).
  • zIndex (integer): indicates how overlapping blocks must be stacked. The higher the zIndex, the higher the block in the stack (foreground).
  • weight (integer): indicates in what order, blocks with the same zIndex must be processed. Low-weighted blocks are handled first.
  • inNewPage (boolean): indicates if a new page must be added before printing the block.
  • inLastPages (boolean): indicates if block must be added in a new page at the end of the document.
  • width (float): block width in distUnit.
  • height (float): block height in distUnit.
  • multiPage (boolean): if true, given block will be displayed on every document page.
  • parent (string): if specified, current block will be printed inside given parent block.
  • inFlow (boolean): if true, block will be printed right after previous block, preserving the vertical alignment.
  • caption (string): for "table" blocks only: name of separated block used to describe table caption formatting.
  • headers (string): for "table" blocks only: name of separated block used to describe table headers (colunms titles) formatting.
  • allowedRoles (comma-separated list of strings): list of roles allowed to draw the current block.

Some additional block-properties are available but are automatically set depending on other parameter values and thus are not listed above ("private" access).

PHP built-in default values:

  • type: NULL
  • content: (empty string)
  • fontFamily: times
  • fontSize: 12
  • fontItalic: false
  • fontBold: false
  • fontUnderline: false
  • color: black
  • backgroundColor: white
  • borderWidth: 1
  • borderColor: black
  • borderStyle: solid
  • padding: 0
  • horizontalMargin: 0
  • verticalMargin: 0
  • horizontalBasis: left
  • verticalBasis: top
  • hCentered: false
  • vCentered: false
  • textAlign: center
  • verticalAlign: center
  • orientation: horizontal
  • zIndex: 1
  • weight: 50
  • inNewPage: false
  • inLastPages: false
  • width: NULL
  • height: NULL
  • multiPage: false
  • parent: false
  • inFlow: true
  • caption: (empty string)
  • headers: (empty string)
  • allowedRoles: all

12.3. Tutorial

12.3.1. General Principle

The PDF document to generate is described using elementary objects blocks:

  • texts: titles, copyrights, dates...
  • images: maps, logos...
  • tables: queries results,...
  • legend: list of icons+labels for each printed layers

Those blocks are drawn and positioned on the document pages according to properties detailed in each block.

In addition, some data must be specified to describe the general document characteristics such as formats (pages size), orientation, available resolutions, PDF engine and more.

Note 2: parameters containing several values are represented using comma-separated lists of strings/integers. If some values contain special characters such as accentuated letters, quotes or other exclamation marks, it may be wiser to encapsulate the whole parameter value between double quotes (").

Note3: don't forget to activate the plugin by adding it in the loadPlugins from BOTH CartoClient and CartoServer configuration files: client_conf/client.ini and server_conf/<mapId>/<mapId>.ini. For instance:

loadPlugins = hilight, outline, exportPdf

12.3.2. Overall Configuration

Two objects are available for overall configuration: general

This is where you can set the list of available resolutions and formats (made available to the user through dropdown menus). Use commas to separate the available values. defaultResolution and defaultFormat are used to preselect options in the matching dropdowns. If for some reason the system failed to determine what resolution and format the user desires, it will use those default values.

Specify the default orientation to select in user interface as well. You don't need to set a list of available orientations since it is already fixed to "portrait, landscape".

The activatedBlocks parameter lists the blocks that may be drawn in the document. It does not mean that they will. For instance the title block will not appear if no title input has been submitted by the user.

Choose the PDF generator you want to use. For now only FPDF is fully available. PDFLib is only partially implemented and should not be used.

Set the output parameter in order to choose how the generated file will be served: download box, link, inline...

The distUnit parameter is very important since it sets the unit used to measure the length specified in every blocks. However it does not affect font sizes, that are always indicated in points (pt).

horizontalMargin and verticalMargin indicate how much space will be kept blank around each page. No block will be printed below these distances from the sheets borders. Note that these values can be overriden in the formats description.

For instance:

general settings
general.formats = A4, A3
general.defaultFormat = A4
general.resolutions = 96, 150, 300
general.mapServerResolution = 96
general.defaultResolution = 96
general.overviewScaleFactor = 10
general.defaultOrientation = portrait
general.activatedBlocks = mainmap, title, note, scalebar, overview, 
                          copyright, queryResult, page, legend,
                          logo, scaleval, tlcoords, brcoords

general.pdfEngine = CwFpdf
general.pdfVersion = 1.3
general.output = inline
general.filename = "map-[date,dMY-Hi].pdf"
general.distUnit = mm
general.horizontalMargin = 10
general.verticalMargin = 10
general.importRemotePng = false formats

Formats objects describe the PDF pages sizes (bigDimension, smallDimension). One can describe as many formats as desired. Moreover there is no theoritical page size limit except that the bigger the maps, the longer the document generation.

A format is determined by its biggest dimension (bigDimension) and its smallest dimension (smallDimension).

The label parameter will be translated using Cw3 I18n internationalization system (Chapter 14, Internationalization). It is not required to be identical to the format object id. On the other hand, the latter id must be textually listed in general.formats parameter or else it will not be taken into account.

In addition, a couple of format parameters can be specified: horizontalMargin and verticalMargin override the corresponding general parameters if different margins must be applied for the given format. maxResolution indicates the highest allowed resolution for the given format: it enables to limit the applied resolution when, for instance, printing big-dimensioned maps.

For instance:

; formats settings
formats.A4.label = A4
formats.A4.bigDimension = 297
formats.A4.smallDimension = 210

formats.A3.label = A3
formats.A3.bigDimension = 420
formats.A3.smallDimension = 297
formats.A3.horizontalMargin = 30
formats.A3.verticalMargin = 30
formats.A3.maxResolution = 150

12.3.3. Blocks Configuration

Whatever their types (image, text, table, legend), blocks use the same PHP object model and, as a result, the same object properties. Some parameters can be used in several ways depending on the block type. Some others are simply ignored.

Blocks naming is quite free but some names are reserved to system-defined blocks such as title, mainmap, overview, scalebar, note, copyright, queryResult, legend, page, scaleval, tlcoords, brcoords. System blocks should not be renamed.

Note that blocks that are not mentioned in general.activatedBlocks won't be displayed in any case.

general.activatedBlocks = mainmap, title, note, scalebar, overview,
                          copyright, queryResult, page, legend,
                          logo, scaleval, tlcoords, brcoords Block Template and Overriding

Since all blocks descriptions are based on the same PdfBlock object, a template block has been defined to factorize blocks common configuration (for instance font-family, background color, borders, padding, etc.). It is also a way to specify default blocks parameters values. It is then possible to personalize blocks by overriding those properties within the block own description. Blocks configuration overriding can be schemed as follows:

PHP PdfBlock (hard coded) >>> block template (user configured) >>> final block (user configured)

Note that it is not necessary to redefine properties in blocks or in their template if their current values (defined in "parent" structures) are already OK.

For instance:

; blocks default settings
template.type = text
template.fontFamily = times
template.fontSize = 12
template.fontItalic = false
template.fontBold = false
template.color = black
template.backgroundColor = white
template.borderWidth = 0.25
template.borderColor = black
template.borderStyle = solid
template.padding = 3
template.horizontalMargin = 0
template.verticalMargin = 0
template.horizontalBasis = left
template.verticalBasis = top
template.hCentered = false
template.zIndex = 1
template.textAlign = center
template.verticalAlign = center
template.orientation = horizontal Blocks Positioning

CartoWeb uses a CSS-like syntax for blocks description and positioning. Description depends on the block type and is detailed in following sections.

Blocks are positioned one after the other, beginning by the ones with the lowest zIndex (vertical position: the low-zIndex'ed blocks are placed under the high-zIndexed ones - ie. closer to the background). When blocks have equal zIndexes, those with lowest weight are processed first. Eventually, if blocks have identical zIndexes and weights, the system will use general.activatedBlocks order to make its choice.

Blocks with different zIndexes wil not interact except if one is marked has the other's parent: in that situation the child block will be located inside the parent block instead of using the general referencial. All following siblings will share the same parent block except if they have a inFlow = false property. Parent blocks must have lower zIndexes than their children.

For instance:

blocks.mainmap.zIndex = 0
blocks.mainmap.weight = 10


blocks.overview.parent = mainmap
blocks.overview.zIndex = 1

Block margins are used to position a given block. Horizontal positioning is achieved by specifying the horizontalBasis (the side of the document - left|right - used as a reference) and the horizontalMargin (the latter value tells how far in distUnit the block will be spaced from the reference line). For instance to position a block at 10mm from the document right side, use the following configuration :

general.distUnit = mm


blocks.myBlock.horizontalBasis = right
blocks.myBlock.horizontalMargin = 10

If you want to horizontally center a block, it is simply done using

blocks.myBlock.hCentered = true

Block centering overloads any other kind of positioning (margin...).

Vertical positioning is achieved in the same way (substitute the dedicated keywords).

The inFlow parameter defaults to true (except if set differently in the template block). As a result, blocks with the same zIndex will be positioned right below the first block preserving the left-side alignment. To cancel this behavior, set inFlow to false. In that case, the given block will be positioned related to the previous block using margin or centering ways. Text Blocks

Text blocks are boxes with a textual content. The text is set in the content parameter in case of a static block. content has to be left blank for visitor-set blocks such as title or note. Text formatting is achieved using usual CSS-like parameter : fontFamily, fontSize (expressed in points!!), color. Small exception: fontItalic, fontBold, fontUnderline are booleans.

Box properties (background color, border size, color and style, padding) are set in the same way whatever the block type is.

Width is generally detected automatically according to the text length. On the other hand, the system has poor means to evaluate its height, so it is recommended to set it by hand. Note that padding (space between border and content) is taken into account only in the horizontal direction for text blocks. To remove a block border, one can simply set its width (borderWidth) to 0. Note that some border styling parameters are not available with all pdfEngines.

For instance:

blocks.title.zIndex = 2
blocks.title.weight = 10
blocks.title.verticalBasis = top
blocks.title.verticalMargin = 15
blocks.title.hCentered = true
blocks.title.fontSize = 20
blocks.title.fontItalic = true
blocks.title.fontBold = true
blocks.title.fontUnderline = true
blocks.title.backgroundColor = #eeeeee
blocks.title.height = 15 Image Blocks

Image blocks are used to display the maps (main + overview), the scalebar and other user-defined pictures such as logos or diagrams. Except for system image blocks (maps + scalebar), the image file location must be specified in content using either an absolute URL or an absolute path within the server file system. It is also possible to use a relative file path based on the CartoClient root directory (eg. htdocs/gfx/layout/c2c.png).

width and height have to be set by the user.

For instance:

blocks.logo.type = image
blocks.logo.content = http://server/gfx/layout/c2c.png
blocks.logo.width = 40
blocks.logo.height = 7
blocks.logo.padding = 2
blocks.logo.parent = mainmap
blocks.logo.horizontalBasis = right
blocks.logo.inFlow = false
blocks.logo.horizontalMargin = 5
blocks.logo.verticalMargin = 5 Table Blocks

Tables blocks are used to represent tabular data such as query results. A table is composed of a caption row (title), a headers row (columns/fields titles) and one or more data rows. All cells can only contain textual content.

The table block describes how data cells will be rendered (font, text color, background color...) using the same parameters than for text blocks. The table width will be computed according to the cells content with a upper limit materialized by the page or the parent block available extent. If the max extent is reached, line feeds will be added automatically to the cells contents. The height parameter gives the height of a single-lined row (and not the total table height!). Note that if a table is too high to fit a page, page breaks will automatically be added.

Caption and headers are described using separated blocks. They are specified by filling the table block caption and headers fields with the matching blocks ids. Since they are not standalone, there is no need to activate the blocks in the general.activatedBlocks list. That way it is possible to set the caption and headers layouts separately from the general table one (which is their default layout). Note that these subblocks are optional and will not be displayed if no content can be determined for them. The same headers and caption subblocks can be shared amongst several table blocks.

CartoWeb output table content (and its caption and headers subblocks) is automatically determined. But it is also possible to user-define independent tables by filling the table and its caption/headers content: cells content are represented as comma-separated string lists (only one row available for table data).

For instance:

blocks.queryResult.type = table
blocks.queryResult.inNewPage = true
blocks.queryResult.caption = tableCaption
blocks.queryResult.headers = tableHeaders
blocks.queryResult.height = 10
blocks.queryResult.verticalMargin = 10
blocks.queryResult.hCentered = true

blocks.tableCaption.backgroundColor = #ff0000
blocks.tableCaption.color = white
blocks.tableCaption.content = "Table test"
blocks.tableCaption.height = 15

blocks.tableHeaders.backgroundColor = #ffaaaa
blocks.tableHeaders.fontBold = true
blocks.tableHeaders.color = #eeeeff Legend Block

There is usually only one instance of legend block in a CartoWeb PDF document. It gives the list of the {selected layer/class + icon} couples. Content is automatically retrieved according to selected layers. You only need to set the text formatting and row height (as for a table block). Legend blocks does not provide any table-like headers or caption.

You can avoid that a given set of layers be displayed in the legend blocks (no change on the maps) by listing the "forbidden" layers ids in the legend block content parameter, prefixing each layer id with an exclamation point ("!"). For instance:

blocks.legend.content = "!background, !layer3"

Note the double quotes around the content value that contains special characters such as "!".

Two behavior are offered to the visitor: embedding the legend block in the map or printing it in a separated page. First case is OK when there is little legend items to print (block is limited to one column) whereas the second possibility enables to display lots of legend items, using several columns if needed. In the map-embedded case, if the overview map is printed, the legend block width will be automatically set to the overview width value.

For instance:

blocks.legend.type = legendp
blocks.legend.zIndex = 1
blocks.legend.weight = 40
blocks.legend.fontSize = 8
blocks.legend.height = 5
blocks.legend.width = 50
blocks.legend.padding = 1.5
blocks.legend.verticalMargin = 10
blocks.legend.horizontalMargin = 10
blocks.legend.content = "!nix"

12.3.4. Roles Management

CartoWeb enables to perform roles restrictions on most of the PDF document parts: general access, formats, resolutions, blocks. All these elements can be restricted to some authorized users. For a more detailed discussion of the concept of security restriction and roles, see Chapter 13, Security Configuration.

To do so, simply add to considered objects/blocks an allowedRoles property set to the comma-separated list of roles you want to restrict them to.

For instance:

  • to enable PDF printing only for loggedIn users, use:
    general.allowedRoles = loggedIn
  • to reserve A3 format to editors or admins, use:
    formats.A4.allowedRoles = editor, admin
  • to set a resolution limit for anonymous users when printing in A3, you can define 2 similar formats with different maxResolution and allowedRoles properties:
    general.formats = A4, A3, A3full
    formats.A4.label = A4
    formats.A4.bigDimension = 297
    formats.A4.smallDimension = 210
    formats.A3.label = A3
    formats.A3.bigDimension = 420
    formats.A3.smallDimension = 297
    formats.A3.maxResolution = 150
    formats.A3.allowedRoles = anonymous
    formats.A3full.label = A3full 
    formats.A3full.bigDimension = 420
    formats.A3full.smallDimension = 297
    formats.A3full.allowedRoles = loggedIn
    Note that all formats that may be used must any way be specified in general.formats.
  • to hide a block for non-admin users, use:
    blocks.overview.allowedRoles = admin