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.

blocks.overview.content = static

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

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

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

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

; 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"

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

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

blocks.queryResult.content = query

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.

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"

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