< Export Plugins

Views >

## 12. PDF Export

## 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.guiMode` (string): type of GUI used. Must be either 'classic' (default) or 'rotate'. 'rotate' mode adds the possibility to rotate the map to be printed directly on screen.
- `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). To have legend icons generated in same resolutions, you must configure resolutions in plugin Layers (see Section 6.4, “Layers Legends”).
- `general.defaultResolution` (integer): default selected/used resolution. Must be one of the above list items.
- `general.scales` (comma-separated list of integers): list of available printing scales (1000 should be read 1:1000). Used only when guiMode is 'rotate'.
- `general.defaultScale` (integer): default printing scale. Must be one of the above list items. Used only when guiMode is 'rotate'.
- `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.overviewColor` (string): sets the inner color of the current map outline in the overview. Default: 'none'.
- `general.overviewOutlineColor` (string): sets the border color of the current map outline in the overview. Default: 'red'.
- `general.showRefMarks` (boolean): if true, reference marks are added to the exported main map. They are never displayed on the overview.
- `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 physically separated CartoClient and CartoServer (See Chapter 4, Configuration Files).
- `general.extraFonts` (comma-separated list of strings): list of additional fonts to import in FPDF (not available for other pdfEngines). Each font contains the font family name, the font style (optional) and the font PHP definition file (optional), separated by "/". PHP definition files must be uploaded in FPDF fonts directory. Parameters are described in FPDF AddFont() documentation. Definition files generation is explained here. Example:

      general.extraFonts = Comic/I/comici.php, MyFont/BI/myfontbi.php, MyOtherFont

PHP built-in default values:

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

### Tip

Should you use the `rotate guiMode`, do not forget to add a general PROJECTION tag in your mapfile. For instance:

    PROJECTION
      "init=epsg:21781"
    END

### 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 16, 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.
- `i18n` (boolean): if true, block content is translated using CartoWeb Gettext system ("i18n" stands for InternationalizatioN). Translated contents may be standard texts or even URLs (useful for instance to display a logo adapted to the used language).

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
- i18n: false

### 12.2.4. Colors definition

Colors definitions in `exportPdf.ini` configuration file are done using hexadecimal color codes or a few textual aliases such as `white`, `black`, `red`, `green`, `blue`. For instance:

    general.overviewOutlineColor = red
    template.backgroundColor     = white
    template.borderColor         = #000000   ; hexadecimal code for black
    blocks.title.color           = #0000ff   ; hexadecimal code for blue

## 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.

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 (").

### Warning

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:

    ; in client_conf/client.ini:
    loadPlugins = hilight, outline, exportPdf

    ; in server_conf/<mapId>/<mapId>.ini:
    mapInfo.loadPlugins = hilight, outline, exportPdf

### 12.3.2. Overall Configuration

Two objects are available for overall configuration:

#### 12.3.2.1. 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.guiMode = classic
    general.formats = A4, A3
    general.defaultFormat = A4
    general.resolutions = 96, 150, 300
    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

Some overview map settings are available as well. The `overviewScaleFactor` indicates how wide the overview will be compared to the mainmap actual extent. `overviewColor` and `overviewOutlineColor` respectively set the inner and border colors of the mainmap outline in the overview map. Note that the `outline` plugin must be activated (ie. added in the `client.ini` `loadPlugins` parameter) for those settings to be taken into account.

### Tip

To use the classical MapServer keymap in place of the overview, set the overview block `content` parameter to `static` (see Section 12.3.4, “Blocks Configuration”) as follows:

    blocks.overview.content = static

In that case parameters `overviewScaleFactor`, `overviewColor`, `overviewOutlineColor` are ignored.

#### 12.3.2.2. 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 16, 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. Form Settings

The HTML interface of the PDF tool is fully customisable by:

- editing the `general` attributes for formats, resolutions and orientation lists (see Section 12.3.2.1, “general” above).
- adding or editing blocks `content` parameters to specify default values for text inputs (such as title or note) and other options (legend, scalebar, overview, query results,...). See Section 12.3.4, “Blocks Configuration”. For instance:

      blocks.title.content = "My default title"
      blocks.scalebar.content = 1  ; scalebar is checked by default
      blocks.legend.content = in   ; legend is checked as included in map by default

### 12.3.4. Blocks Configuration

Whatever their types (image, text, table, legend, north), 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, north. 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, north

#### 12.3.4.1. 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

#### 12.3.4.2. 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.

#### 12.3.4.3. 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

It is possible to specify a text content in the configuration file by using the `content` parameter. Note that `\n` strings in the `content` value will result in line feeds in the final block.

    blocks.myText.content = "This is myText block content!"

    blocks.myText2.content = "myText2 block\nis multilined."

Text blocks content may also be retrieved from external data source such as text files or databases using following syntaxes. "Connection" parts are separated by a "~". First part indicates what medium (`file`|`db`) is used:

- `file`: file source

      blocks.myText.content = "file~my/source/file/path"

  The source file path can either be a absolute URL or a filesystem path. Relative filesystem paths are allowed and are based on the CartoWeb root path. For instance:

      blocks.myText.content = "file~http://myserver/mysourcefile.txt"
      blocks.myText.content = "file~C:\mydir\mysourcefile.txt"
      blocks.myText.content = "file~/home/johndoe/mysourcefile.txt"
      blocks.myText.content = "file~www-data/mysourcefile.txt"

  If your source file contains several lines or `\n` strings, the generated block will also be multilined.
- `db`: database source

      blocks.myText.content = "db~DSN~SQL query"

  The DSN (Data Source Name) gives the database connection parameters. Any DSN format supported by PEAR::DB can be used. See PEAR::DB manual for more info about DSNs at http://pear.php.net/manual/en/package.database.db.intro-dsn.php. Note that you can call any database server type as long as it is supported by PEAR::DB and that your PHP distribution has the matching extension enabled. For security reasons, only SELECT SQL queries are allowed but there is no other limitation. On the other hand, the query results are basically rendered using a new line for each result line and simply separating result elements with blank spaces. For instance:

      blocks.myText.content = "db~pgsql://user:password@localhost/dbname~select name,
                               phone_number from phone_book where area_id = 12"

### Tip

It is possible to make some text blocks have their contents translated by setting their `i18n` parameter to `true`. For instance:

    blocks.myTextBlock.content = "This text will be translated."
    blocks.myTextBlock.i18n = true

Translatable blocks are CartoWeb built-in blocks `copyright` and `date` as well as your own text blocks. Some other CartoWeb built-in blocks such as `legend`, `scaleval`, `page` or query results table blocks are translated anyway.

Note that you will have to explicitly add those entries to your Gettext PO files since there is no way for script `client2pot.php` to automatically detect them!

### Tip

The `date` text block is fully customizable. You may specify the date format using PHP date formatting (http://php.net/date). Both configurations are correct:

    ; use [] to add the date string in complete sentence:
    blocks.date.content = "Generated on [Y/m/d H:i] by CartoWeb3"

    ; or if the date string is alone:
    blocks.date.content = "Y/m/d H:i"

If you want to have the date block translated, set its `i18n` parameter to `true` and add the translated version (including date format) to your PO files.

#### 12.3.4.4. 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

### Tip

If you want to switch the image file depending on the used language, set the block `i18n` parameter to `true` and add languages matching URLs/filepathes to your PO files.

#### 12.3.4.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

### Tip

A special table block exists to specify which TableGroup (see Section 2.4.3.1, “Tables Structures”) you want to display in the PDF.

    blocks.queryResult.content = query

In that case only the TableGroup `query` is visible but you can specify more than one, separate by comma. If this block is not defined in the configuration file, all TableGroup are visible in the PDF file (backward compatibility).

The query results data come from the plugin Table which offers the mechanism of table rules (see Section 2.4.3.2, “Setting Rules”) which describes how tables must be displayed. You can also add table rules specificaly for the PDF output like this example :

    $outputType = $this->cartoclient->getOutputType();

    if ($outputType == Cartoclient::OUTPUT_HTML_VIEWER) {
        /* rules for HTML output */
    }

    if ($outputType == 'pdf') {
        /* rules for PDF output */
    }

`outputType` is generally the export plugin name without the "export" prefix.

#### 12.3.4.6. 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 = legend
    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.7. North Arrow Block

There is usually only one instance of north arrow block in a CartoWeb PDF document. It displays an arrow (or any image) that will automatically show the north direction. Path set in arrow block `content` parameter is relative to CartoWeb root directory.

For instance:

    blocks.north.type = north
    blocks.north.content = "plugins/exportPdf/htdocs/gfx/arrow.png"
    blocks.north.width = 10
    blocks.north.height = 36
    blocks.north.padding = 2
    blocks.north.parent = mainmap
    blocks.north.verticalBasis = bottom
    blocks.north.horizontalBasis = left
    blocks.north.inFlow = false
    blocks.north.horizontalMargin = 15
    blocks.north.verticalMargin = 5

### 12.3.5. 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 15, 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