<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % cartoweb SYSTEM "../cartoweb.ent" >
  %cartoweb;
]>

<!-- $Id: pdf.xml,v 1.33 2007-07-16 12:55:47 yves Exp $ -->

<chapter id="user.pdf">
 <title><indexterm><primary>PDF</primary></indexterm>PDF Export</title>
 <subtitle>Plugin exportPdf</subtitle>

 <sect1 id="user.pdf.intro"> 
  <title>Introduction</title>
  <para>
   This chapter describes how to configure PDF export,
   using <filename>client_conf/exportPdf.ini</filename> parameters.
  </para>
  <para>
   First part (<xref linkend="user.pdf.reference"/>) is a comprehensive reference of user-available configuration parameters. Second part (<xref linkend="user.pdf.tutorial"/>) is intended to be a small tutorial giving explanations and examples about how to configure the PDF exportation tool.
  </para>
 </sect1>

 <sect1 id="user.pdf.reference">
  <title>Configuration Reference</title>
  <sect2 id="user.pdf.reference.general"> 
   <title><indexterm><primary>General configuration, PDF</primary></indexterm>General Configuration</title>
   <para>
    Parameters are named using a &lt;object&gt;.&lt;property&gt; convention.
    These parameters are grouped within dedicated objects 
    that deal with separated aspects of the export. For instance:
   </para>
   <programlisting><![CDATA[general.horizontalMargin = 10
general.verticalMargin = 10

formats.A4.label = A4
formats.A4.bigDimension = 297]]></programlisting>
   <para>
    Some objects handle the general description of the PDF document
    as well as user form generation: "general" and "formats".
   </para>
   <para>
    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.
   </para>
   <para>
    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.
   </para>
   <para>
    <itemizedlist>
     <listitem>
        <para> <parameter>general.guiMode</parameter> (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. </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.formats</parameter> (comma-separated list of strings): ids of available 
       sheet sizes. Must match format objects names 
       (see <link linkend="user.pdf.reference.format">Formats configuration</link> below).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.defaultFormat</parameter> (string): default selected/used format. 
       Must be one of the above list items.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.resolutions</parameter> (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 <xref linkend="user.layers.legend"/>).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.defaultResolution</parameter> (integer): default selected/used
       resolution. Must be one of the above list items.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.scales</parameter> (comma-separated list of integers): 
       list of available printing scales (1000 should be read 1:1000). Used only when guiMode is 'rotate'.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.defaultScale</parameter> (integer): default printing
       scale. Must be one of the above list items. Used only when guiMode is 'rotate'.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.defaultOrientation</parameter> (portrait|landscape): sheet 
       orientation. The same orientation is used for every pages 
       of the PDF document.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.activatedBlocks</parameter> (comma-separated list of strings): names
       of blocks that will be used in the document. Names must match
       block objects names. See <link linkend="user.pdf.reference.block">Blocks configuration</link> section.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.overviewScaleFactor</parameter> (float): sets the extension of the overview map. The bigger this parameter, the wider the extension. 
       Default: 10.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.overviewColor</parameter> (string): sets the inner color of the current map outline in the overview. 
       Default: 'none'.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.overviewOutlineColor</parameter> (string): sets the border color of the current map outline in the overview. 
       Default: 'red'.
      </para>
     </listitem>
        <listitem>
            <para> <parameter>general.showRefMarks</parameter> (boolean): if true,
                reference marks are added to the exported main map. They are never displayed
                on the overview.</para>
        </listitem>
     <listitem>
      <para>
       <parameter>general.pdfEngine</parameter> (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").
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.pdfVersion</parameter> (string): PDF version that must be 
       used (only available with "PdfLibLite" pdfEngine).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.output</parameter> (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.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.filename</parameter> (string): indicates how generated PDF files 
       must be named. It is possible to specify a date-formatting 
       using PHP date format (see <ulink 
       url="http://php.net/date">http://php.net/date</ulink>). Default is 
       <filename>map-[date,dMY-His].pdf</filename> which gives for instance 
       <filename>map-03Jan2005-193256.pdf</filename>.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.distUnit</parameter> (mm|cm|pt|in): unit used to measure blocks 
       distance properties. Only one unit can be used in the 
       whole configuration.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.horizontalMargin</parameter> (float): horizontal distance between
       the sheet border and the useful area (in distUnit).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.verticalMargin</parameter> (float): vertical distance between the
       sheet border and the useful area (in distUnit).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.allowedRoles</parameter> (comma-separated list of strings): list of roles allowed to print PDF documents.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.importRemotePng</parameter> (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 <xref linkend="user.config"/>).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>general.extraFonts</parameter> (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 <ulink url="http://fpdf.org/en/doc/addfont.htm">FPDF AddFont() documentation</ulink>. Definition files generation is explained <ulink url="http://fpdf.org/en/tutorial/tuto7.htm">here</ulink>. Example:
       <programlisting>general.extraFonts = Comic/I/comici.php, MyFont/BI/myfontbi.php, MyOtherFont</programlisting>
      </para>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    PHP built-in default values:
    <itemizedlist>
     <listitem>
      <para>
       pdfEngine: CwFpdf
      </para>
     </listitem>
     <listitem>
      <para>
       pdfVersion: 1.3
      </para>
     </listitem>
     <listitem>
      <para>
       guiMode: classic
      </para>
     </listitem>
     <listitem>
      <para>
       distUnit:        mm
      </para>
     </listitem>
     <listitem>
      <para>
       horizontalMargin: 10
      </para>
     </listitem>
     <listitem>
      <para>
       verticalMargin: 10
      </para>
     </listitem>
     <listitem>
      <para>
       formats: NULL
      </para>
     </listitem>
     <listitem>
      <para>
       defaultFormat: NULL
      </para>
     </listitem>
     <listitem>
      <para>
       resolutions: 96      
      </para>
     </listitem>
     <listitem>
      <para>
       defaultResolution: 96
      </para>
     </listitem>
     <listitem>
      <para>
       activatedBlocks: NULL
      </para>
     </listitem>
     <listitem>
      <para>
       filename: map-[date,dMY-His].pdf
      </para>
     </listitem>
     <listitem>
      <para>
       overviewScaleFactor: 10
      </para>
     </listitem>
     <listitem>
      <para>
       overviewColor: NULL
      </para>
     </listitem>
     <listitem>
      <para>
       overviewOutlineColor: red
      </para>
     </listitem>
     <listitem>
      <para>
       output: redirection
      </para>
     </listitem>
     <listitem>
      <para>
       allowedRoles: (empty ie. nobody)
      </para>
     </listitem>
     <listitem>
      <para>
       importRemotePng: false
      </para>
     </listitem>
     <listitem>
      <para>
       extraFonts: NULL
      </para>
     </listitem>
    </itemizedlist>
   </para>
   <tip>
    <para>
     Should you use the <parameter>rotate guiMode</parameter>, do not forget to add a general PROJECTION tag in your mapfile. For instance:
<programlisting>PROJECTION
  "init=epsg:21781"
END</programlisting>
    </para>
   </tip>
  </sect2>
 
  <sect2 id="user.pdf.reference.format"> 
   <title><indexterm><primary>Formats configuration, PDF</primary></indexterm>Formats Configuration</title>
   <para>
    Formats are described as a set of "formats" sub-objects. For instance:
   </para>
   <programlisting><![CDATA[formats.A4.bigDimension = 297
formats.A4.smallDimension = 210

formats.A3.label = A3
formats.A3.bigDimension = 420]]></programlisting>
   <para>
    Format ids (A3, A4, etc.) must match those listed in general.formats.
    <itemizedlist>
     <listitem>
      <para>
       <parameter>formats.</parameter>&lt;format_name&gt;<parameter>.label</parameter> (string): user-friendly name. Is 
       translated using Cw3I18n device <xref linkend="user.i18n"/>.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>formats.</parameter>&lt;format_name&gt;<parameter>.bigDimension</parameter> (float): 
       largest sheet side (in distUnit).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>formats.</parameter>&lt;format_name&gt;<parameter>.smallDimension</parameter> (float): 
       smallest sheet side (in distUnit).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>formats.</parameter>&lt;format_name&gt;<parameter>.horizontalMargin</parameter> (float):
       optional, if set, overrides general.horizontalMargin for 
       the given format.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>formats.</parameter>&lt;format_name&gt;<parameter>.verticalMargin</parameter> (float): 
       optional, if set, overrides general.verticalMargin 
       for the given format.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>formats.</parameter>&lt;format_name&gt;<parameter>.maxResolution</parameter> (integer): 
       optional, maximum allowed resolution for the given format.
       If selected resolution is above maxResolution, it will 
       be set to maxResolution value.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>formats.</parameter>&lt;format_name&gt;<parameter>.allowedRoles</parameter> (comma-separated list of strings): list of roles allowed to use the format.
      </para>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    PHP built-in default values: all format parameters have 
    NULL default values except <parameter>allowedRoles</parameter> ("all").
   </para>
  </sect2>
 
  <sect2 id="user.pdf.reference.block"> 
   <title><indexterm><primary>Blocks configuration, PDF</primary></indexterm>Blocks Configuration</title>
   <para>
    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:
   </para> 
   <programlisting><![CDATA[template.type = text
template.fontFamily = times
template.fontSize = 12
template.fontItalic = false]]></programlisting>
   <para>
    whereas real blocks are described this way:
   </para>
   <programlisting><![CDATA[blocks.title.weight = 10
blocks.title.verticalBasis = top
blocks.title.verticalMargin = 15]]></programlisting>
   <para>
    "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.&lt;block_name&gt;." prefixes.
    <itemizedlist>
     <listitem>
      <para>
       <parameter>type</parameter> (text|image|table|legend): block type, indicates what kind 
       of processing must be applied.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>content</parameter> (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).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>fontFamily</parameter> (string): name of font family to use. Naming
       depends on used pdfEngine.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>fontSize</parameter> (float) : font size in points (pt)
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>fontItalic</parameter> (boolean): if true, text will be emphasized.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>fontBold</parameter> (boolean): if true, text will be bold-weighted.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>fontUnderline</parameter> (boolean): if true, text will be underlined.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>color</parameter> (string): color of text in hexadecimal code #rrggbb.
       A few color aliases ("white", "black") are available as well.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>backgroundColor</parameter> (string): background color in hexadecimal
       code or color aliases.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>borderWidth</parameter> (float): border line width in distUnit.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>borderColor</parameter> (string): border line color in hexadecimal
       code or color aliases.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>borderStyle</parameter> (solid|dashed|dotted): border line style. 
       Only available with "PdfLibLite" pdfEngine. "solid" value
       is used for other pdfEngines.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>padding</parameter> (float): vertical and horizontal distance between
       block content and its borders in distUnit.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>horizontalMargin</parameter> (float): horizontal margin in distUnit
       around the block (outside borders).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>verticalMargin</parameter> (float): vertical margin in distUnit around 
       the block (outside borders).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>horizontalBasis</parameter> (left|right): indicates what document side 
       must be used for horizontal positioning.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>verticalBasis</parameter> (top|bottom): indicates what document side must
       be used for vertical positioning.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>hCentered</parameter> (boolean): if true, block is horizontally centered
       (overloads horizontalBasis property).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>vCentered</parameter> (boolean): if true, block is vertically centered
       (overloads verticalBasis property).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>textAlign</parameter> (center|left|right): indicates how content must be 
       horizontally aligned within the block extent.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>verticalAlign</parameter> (center|top|bottom): indicates how content must
       be vertically aligned within the block extent.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>orientation</parameter> (horizontal|vertical): indicates if content will be 
       displayed form left to right or from bottom to top (only for 
       text blocks).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>zIndex</parameter> (integer): indicates how overlapping blocks must be stacked.
       The higher the zIndex, the higher the block in the stack (foreground).
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>weight</parameter> (integer): indicates in what order, blocks with the same
       zIndex must be processed. Low-weighted blocks are handled first.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>inNewPage</parameter> (boolean): indicates if a new page must be added before
       printing the block.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>inLastPages</parameter> (boolean): indicates if block must be added in a new
       page at the end of the document.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>width</parameter> (float): block width in distUnit.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>height</parameter> (float): block height in distUnit.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>multiPage</parameter> (boolean): if true, given block will be displayed on 
       every document page.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>parent</parameter> (string): if specified, current block will be printed inside 
       given parent block.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>inFlow</parameter> (boolean): if true, block will be printed right after previous
       block, preserving the vertical alignment.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>caption</parameter> (string): for "table" blocks only: name of separated block 
       used to describe table caption formatting.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>headers</parameter> (string): for "table" blocks only: name of separated block
       used to describe table headers (colunms titles) formatting.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>allowedRoles</parameter> (comma-separated list of strings): list of roles allowed to draw the current block.
      </para>
     </listitem>
     <listitem>
      <para>
       <parameter>i18n</parameter> (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).
      </para>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Some additional block-properties are available but are automatically set 
    depending on other parameter values and thus are not listed 
    above ("private" access).
   </para>
   <para>
    PHP built-in default values:
    <itemizedlist>
     <listitem>
      <para>
       type: NULL
      </para>
     </listitem>
     <listitem>
      <para>
       content: (empty string)
      </para>
     </listitem>
     <listitem>
      <para>
       fontFamily: times
      </para>
     </listitem>
     <listitem>
      <para>
       fontSize: 12
      </para>
     </listitem>
     <listitem>
      <para>
       fontItalic: false
      </para>
     </listitem>
     <listitem>
      <para>
       fontBold: false
      </para>
     </listitem>
     <listitem>
      <para>
       fontUnderline: false 
      </para>
     </listitem>
     <listitem>
      <para>
       color: black
      </para>
     </listitem>
     <listitem>
      <para>
       backgroundColor: white
      </para>
     </listitem>
     <listitem>
      <para>
       borderWidth: 1
      </para>
     </listitem>
     <listitem>
      <para>
       borderColor: black
      </para>
     </listitem>
     <listitem>
      <para>
       borderStyle: solid
      </para>
     </listitem>
     <listitem>
      <para>
       padding: 0
      </para>
     </listitem>
     <listitem>
      <para>
       horizontalMargin: 0
      </para>
     </listitem>
     <listitem>
      <para>
       verticalMargin: 0
      </para>
     </listitem>
     <listitem>
      <para>
       horizontalBasis: left
      </para>
     </listitem>
     <listitem>
      <para>
       verticalBasis: top
      </para>
     </listitem>
     <listitem>
      <para>
       hCentered: false
      </para>
     </listitem>
     <listitem>
      <para>
       vCentered: false
      </para>
     </listitem>
     <listitem>
      <para>
       textAlign: center
      </para>
     </listitem>
     <listitem>
      <para>
       verticalAlign: center
      </para>
     </listitem>
     <listitem>
      <para>
       orientation: horizontal
      </para>
     </listitem>
     <listitem>
      <para>
       zIndex: 1
      </para>
     </listitem>
     <listitem>
      <para>
       weight: 50
      </para>
     </listitem>
     <listitem>
      <para>
       inNewPage: false
      </para>
     </listitem>
     <listitem>
      <para>
       inLastPages: false
      </para>
     </listitem>
     <listitem>
      <para>
       width: NULL
      </para>
     </listitem>
     <listitem>
      <para>
       height: NULL
      </para>
     </listitem>
     <listitem>
      <para>
       multiPage: false
      </para>
     </listitem>
     <listitem>
      <para>
       parent: false
      </para>
     </listitem>
     <listitem>
      <para>
       inFlow: true
      </para>
     </listitem>
     <listitem>
      <para>
       caption: (empty string)
      </para>
     </listitem>
     <listitem>
      <para>
       headers: (empty string)
      </para>
     </listitem>
     <listitem>
      <para>
       allowedRoles: all
      </para>
     </listitem>
     <listitem>
      <para>
       i18n: false
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect2>
  <sect2 id="user.pdf.reference.colors">
   <title><indexterm><primary>Colors, PDF</primary></indexterm>Colors definition</title>
   <para>
    Colors definitions in <filename>exportPdf.ini</filename> configuration file are done using hexadecimal color codes or a few textual aliases such as <parameter>white</parameter>, <parameter>black</parameter>, <parameter>red</parameter>, <parameter>green</parameter>, <parameter>blue</parameter>. For instance:
    <programlisting>
general.overviewOutlineColor = red
template.backgroundColor     = white
template.borderColor         = #000000   ; hexadecimal code for black
blocks.title.color           = #0000ff   ; hexadecimal code for blue</programlisting>
   </para>
  </sect2>
 </sect1>

 <sect1 id="user.pdf.tutorial">
  <title>Tutorial</title>
  
  <sect2 id="user.pdf.tutorial.principle">
   <title>General Principle</title>
   <para>
    The PDF document to generate is described using elementary objects blocks:
   </para>
   <para>
    <itemizedlist>
     <listitem>
      <para>
       texts: titles, copyrights, dates...
      </para>
     </listitem>
     <listitem>
      <para>
       images: maps, logos...
      </para>
     </listitem>
     <listitem>
      <para>
       tables: queries results...
      </para>
     </listitem>
     <listitem>
      <para>
       legend: list of icons+labels for each printed layers
      </para>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Those blocks are drawn and positioned on the document pages according to properties detailed in each block.
   </para>
   <para>
    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.
   
   </para>
   <para>
    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 ("). 
   </para>
   <warning>
   <para>
    Note3: don't forget to activate the plugin by adding it in the <parameter>loadPlugins</parameter> from BOTH &cartoclient; and &cartoserver; configuration files: <filename>client_conf/client.ini</filename> and <filename>server_conf/&lt;mapId&gt;/&lt;mapId&gt;.ini</filename>. For instance:
    <programlisting><![CDATA[; in client_conf/client.ini:
loadPlugins = hilight, outline, exportPdf

; in server_conf/<mapId>/<mapId>.ini:
mapInfo.loadPlugins = hilight, outline, exportPdf]]></programlisting>
   </para>
   </warning>
  </sect2>

  <sect2 id="user.pdf.tutorial.overall">
   <title><indexterm><primary>Overall configuration, PDF</primary></indexterm>Overall Configuration</title>
   <para>Two objects are available for overall configuration:</para>
   <sect3 id="user.pdf.tutorial.overall.general">
    <title><indexterm><primary>general object, PDF</primary></indexterm>general</title>
    <para>
     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. <parameter>defaultResolution</parameter> and <parameter>defaultFormat</parameter> 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.
    </para>
    <para>
     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".
    </para>
    <para>
     The <parameter>activatedBlocks</parameter> 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.
    </para>
    <para>
     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.
    </para>
    <para>
     Set the <parameter>output</parameter> parameter in order to choose how the generated file will be served: download box, link, inline...
    </para>
    <para>
     The <parameter>distUnit</parameter> 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).
    </para>
    <para>
     <parameter>horizontalMargin</parameter> and <parameter>verticalMargin</parameter> 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. 
    </para>
    <para>For instance:</para>
    <programlisting><![CDATA[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]]></programlisting>
    <para>
     Some overview map settings are available as well. The <parameter>overviewScaleFactor</parameter> indicates how wide the overview will be compared to the mainmap actual extent. <parameter>overviewColor</parameter> and <parameter>overviewOutlineColor</parameter> respectively set the inner and border colors of the mainmap outline in the overview map. Note that the <parameter>outline</parameter> plugin must be activated (ie. added in the <filename>client.ini</filename> <parameter>loadPlugins</parameter> parameter) for those settings to be taken into account.
    </para>
    <tip>
     <para>
      To use the classical MapServer keymap in place of the overview, set the overview block <parameter>content</parameter> parameter to <parameter>static</parameter> (see <xref linkend="user.pdf.tutorial.block" />) as follows:
     </para>
     <programlisting>blocks.overview.content = static</programlisting>
     <para>
      In that case parameters <parameter>overviewScaleFactor</parameter>, <parameter>overviewColor</parameter>, <parameter>overviewOutlineColor</parameter> are ignored.
     </para>
    </tip>
   </sect3>
   <sect3 id="user.pdf.tutorial.overall.formats">
    <title><indexterm><primary>formats object, PDF</primary></indexterm>formats</title>
    <para>
     Formats objects describe the PDF pages sizes (<parameter>bigDimension</parameter>, <parameter>smallDimension</parameter>). 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.
    </para>
    <para>
     A format is determined by its biggest dimension (<parameter>bigDimension</parameter>) and its smallest dimension (<parameter>smallDimension</parameter>).
    </para>
    <para>
     The <parameter>label</parameter> parameter will be translated using Cw3 I18n internationalization system (<xref linkend="user.i18n"/>). It is not required to be identical to the format object id. On the other hand, the latter id must be textually listed in <parameter>general.formats</parameter> parameter or else it will not be taken into account.
    </para>
    <para>
     In addition, a couple of format parameters can be specified: <parameter>horizontalMargin</parameter> and <parameter>verticalMargin</parameter> override the corresponding general parameters if different margins must be applied for the given format. <parameter>maxResolution</parameter> indicates the highest allowed resolution for the given format: it enables to limit the applied resolution when, for instance, printing big-dimensioned maps.
    </para>
    <para>
     For instance: 
    </para>
    <programlisting><![CDATA[; 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]]></programlisting>
   </sect3>
  </sect2>
  <sect2 id="user.pdf.tutorial.form">
    <title>Form Settings</title>
    <para>
     The HTML interface of the PDF tool is fully customisable by:
     <itemizedlist>
      <listitem>
       <para>
        editing the <parameter>general</parameter> attributes for formats, resolutions and orientation lists (see <xref linkend="user.pdf.tutorial.overall.general"/> above).
       </para>
      </listitem>
      <listitem>
       <para>
        adding or editing blocks <parameter>content</parameter> parameters to specify default values for text inputs (such as title or note) and other options (legend, scalebar, overview, query results,...). See <xref linkend="user.pdf.tutorial.block"/>. For instance:
        <programlisting>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</programlisting>
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </sect2>

  <sect2 id="user.pdf.tutorial.block">
   <title><indexterm><primary>Blocks configuration, PDF</primary></indexterm>Blocks Configuration</title>
   <para>
    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.
   </para>
   <para>
    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.
   </para>
   <para>
    Note that blocks that are not mentioned in <parameter>general.activatedBlocks</parameter> won't be displayed in any case.
   </para>
   <programlisting><![CDATA[general.activatedBlocks = mainmap, title, note, scalebar, overview,
                          copyright, queryResult, page, legend,
                          logo, scaleval, tlcoords, brcoords, north]]></programlisting>

   <sect3 id="user.pdf.tutorial.block.template">
    <title><indexterm><primary>template object, PDF</primary></indexterm>Block Template and Overriding</title>
    <para>
     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:
    </para>
    <para>
     PHP PdfBlock (hard coded) >>> block template (user configured) >>> final block (user configured)
    </para>
    <para>
     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.
    </para>
    <para>
     For instance: 
    </para>
    <programlisting><![CDATA[; 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]]></programlisting>
   </sect3>
   <sect3 id="user.pdf.tutorial.block.positioning">
    <title><indexterm><primary>block positioning, PDF</primary></indexterm>Blocks Positioning</title>
    <para>
     &cartoweb; uses a CSS-like syntax for blocks description and positioning. Description depends on the block type and is detailed in following sections.
    </para>
    <para>
     Blocks are positioned one after the other, beginning by the ones with the lowest <parameter>zIndex</parameter> (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 <parameter>weight</parameter> are processed first. Eventually, if blocks have identical zIndexes and weights, the system will use <parameter>general.activatedBlocks</parameter> order to make its choice.
    </para>
    <para>
     Blocks with different zIndexes wil not interact except if one is marked has the other's <parameter>parent</parameter>: 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 <parameter>inFlow = false</parameter> property. Parent blocks must have lower zIndexes than their children.
    </para>
    <para>
     For instance: 
    </para>
    <programlisting><![CDATA[blocks.mainmap.zIndex = 0
blocks.mainmap.weight = 10

[...]

blocks.overview.parent = mainmap
blocks.overview.zIndex = 1]]></programlisting>
    <para>
     Block margins are used to position a given block. Horizontal positioning is achieved by specifying the <parameter>horizontalBasis</parameter> (the side of the document - left|right - used as a reference) and the <parameter>horizontalMargin</parameter> (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 :
    </para>
    <programlisting><![CDATA[general.distUnit = mm

[...]

blocks.myBlock.horizontalBasis = right
blocks.myBlock.horizontalMargin = 10]]></programlisting>
    <para>
     If you want to horizontally center a block, it is simply done using
    </para>
    <programlisting><![CDATA[blocks.myBlock.hCentered = true]]></programlisting>
    <para>
     Block centering overloads any other kind of positioning (margin...).
    </para>
    <para>
     Vertical positioning is achieved in the same way (substitute the dedicated keywords).
    </para>
    <para>
     The <parameter>inFlow</parameter> parameter defaults to true (except if set differently in the template block). As a result, blocks with the same <parameter>zIndex</parameter> will be positioned right below the first block preserving the left-side alignment. To cancel this behavior, set <parameter>inFlow</parameter> to false. In that case, the given block will be positioned related to the previous block using margin or centering ways. 
    </para>
   </sect3>
   <sect3 id="user.pdf.tutorial.block.text">
    <title><indexterm><primary>Text blocks, PDF</primary></indexterm>Text Blocks</title>
    <para>
     Text blocks are boxes with a textual content. The text is set in the <parameter>content</parameter> parameter in case of a static block. <parameter>content</parameter> has to be left blank for visitor-set blocks such as title or note. Text formatting is achieved using usual CSS-like parameter : <parameter>fontFamily</parameter>, <parameter>fontSize</parameter> (expressed in points!!), <parameter>color</parameter>. Small exception: <parameter>fontItalic</parameter>, <parameter>fontBold</parameter>, <parameter>fontUnderline</parameter> are booleans.
    </para>
    <para>
     Box properties (background color, border size, color and style, padding) are set in the same way whatever the block type is.
    </para>
    <para>
     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 (<parameter>borderWidth</parameter>) to 0. Note that some border styling parameters are not available with all pdfEngines.
    </para>
    <para>
     For instance: 
    </para>
    <programlisting>
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</programlisting>
    <para>
     It is possible to specify a text content in the configuration file by using the <parameter>content</parameter> parameter. Note that <parameter>\n</parameter> strings in the <parameter>content</parameter> value will result in line feeds in the final block.
     <programlisting>
blocks.myText.content = "This is myText block content!"

blocks.myText2.content = "myText2 block\nis multilined."</programlisting>
    </para>
    <para>
     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 (<parameter>file</parameter>|<parameter>db</parameter>) is used:
     <itemizedlist>
      <listitem>
       <para><parameter>file</parameter>: file source</para>
       <programlisting>
blocks.myText.content = "file~my/source/file/path"</programlisting>
       <para>
        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:
       </para>
       <programlisting>
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"</programlisting>
       <para>
        If your source file contains several lines or <parameter>\n</parameter> strings, the generated block will also be multilined.
       </para>
      </listitem>
      <listitem>
       <para><parameter>db</parameter>: database source</para>
       <programlisting>
blocks.myText.content = "db~DSN~SQL query"</programlisting>
       <para>
        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 <ulink url="http://pear.php.net/manual/en/package.database.db.intro-dsn.php">http://pear.php.net/manual/en/package.database.db.intro-dsn.php</ulink>. 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.
       </para>
       <para>
        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. 
       </para>
       <para>For instance:</para>
       <programlisting>
blocks.myText.content = "db~pgsql://user:password@localhost/dbname~select name,
                         phone_number from phone_book where area_id = 12"</programlisting>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     <tip>
      <para>It is possible to make some text blocks have their contents translated by setting their <parameter>i18n</parameter> parameter to <parameter>true</parameter>. For instance:</para>
      <programlisting>blocks.myTextBlock.content = "This text will be translated."
blocks.myTextBlock.i18n = true</programlisting>
      <para>Translatable blocks are &cartoweb; built-in blocks <parameter>copyright</parameter> and <parameter>date</parameter> as well as your own text blocks. Some other &cartoweb; built-in blocks such as <parameter>legend</parameter>, <parameter>scaleval</parameter>, <parameter>page</parameter> or query results table blocks are translated anyway.</para>
      <para>Note that you will have to explicitly add those entries to your Gettext PO files since there is no way for script <filename>client2pot.php</filename> to automatically detect them!</para>
     </tip>
     <tip>
      <para>The <parameter>date</parameter> text block is fully customizable. You may specify the date format using PHP date formatting (<ulink url="http://php.net/date">http://php.net/date</ulink>). Both configurations are correct:</para>
      <programlisting>; 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"</programlisting>
      <para>If you want to have the date block translated, set its <parameter>i18n</parameter> parameter to <parameter>true</parameter> and add the translated version (including date format) to your PO files.</para>
     </tip>
    </para>
   </sect3>
   <sect3 id="user.pdf.tutorial.block.image">
    <title><indexterm><primary>Image blocks, PDF</primary></indexterm>Image Blocks</title>
    <para>
     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. <filename>htdocs/gfx/layout/c2c.png</filename>).
    </para>
    <para>
     <parameter>width</parameter> and <parameter>height</parameter> have to be set by the user.
    </para>
    <para>
     For instance: 
    </para>
    <programlisting><![CDATA[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]]></programlisting>
    <para>
     <tip>
      <para>If you want to switch the image file depending on the used language, set the block <parameter>i18n</parameter> parameter to <parameter>true</parameter> and add languages matching URLs/filepathes to your PO files.</para>
     </tip>
    </para>
   </sect3>
   <sect3 id="user.pdf.tutorial.block.table">
    <title><indexterm><primary>Table blocks, PDF</primary></indexterm>Table Blocks</title>
    <para>
     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.
    </para>
    <para>
     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 <parameter>height</parameter> 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.
    </para>
    <para>
     Caption and headers are described using separated blocks. They are specified by filling the table block <parameter>caption</parameter> and <parameter>headers</parameter> fields with the matching blocks ids. Since they are not standalone, there is no need to activate the blocks in the <parameter>general.activatedBlocks</parameter> 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.
    </para>
    <para>
     &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 <parameter>content</parameter>: cells content are represented as comma-separated string lists (only one row available for table data).
    </para>
    <para>
     For instance: 
    </para>
    <programlisting><![CDATA[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]]></programlisting>

     <tip>
     <para>
      A special table block exists to specify which TableGroup (see
      <xref linkend="dev.newplugin.special.tables.structures" />) you want to display in the PDF.
     </para>
     <programlisting>blocks.queryResult.content = query</programlisting>
     <para>
      In that case only the TableGroup <parameter>query</parameter> 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). 
     </para>
     </tip>

    <para>
     The query results data come from the plugin Table which offers
     the mechanism of table rules (see <xref
     linkend="dev.newplugin.special.tables.setrules" />) 
     which describes how tables must be displayed. You can also add
     table rules specificaly for the PDF output like this example : 
    </para>
    <programlisting>$outputType = $this->cartoclient->getOutputType();

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

if ($outputType == 'pdf') {
    /* rules for PDF output */
}</programlisting>   
    <para><parameter>outputType</parameter> is generally the export plugin name without the "export" prefix.</para>
   </sect3>
   <sect3 id="user.pdf.tutorial.block.legend">
    <title><indexterm><primary>Legend blocks, PDF</primary></indexterm>Legend Block</title>
    <para>
     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.
    </para>
    <para>
     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 <parameter>content</parameter> parameter, prefixing each layer id with an exclamation point ("!"). For instance: 
    </para>
    <programlisting><![CDATA[blocks.legend.content = "!background, !layer3"]]></programlisting>
    <para>
      Note the double quotes around the content value that contains special characters such as "!".
     </para>
     <para>
      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 <parameter>width</parameter> will be automatically set to the overview <parameter>width</parameter> value.
     </para>
     <para>
      For instance: 
    </para>
    <programlisting><![CDATA[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"]]></programlisting>
   </sect3>
   <sect3 id="user.pdf.tutorial.block.north">
    <title><indexterm><primary>North Arrow blocks, PDF</primary></indexterm>North Arrow Block</title>
    <para> 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 <parameter>content</parameter> parameter is relative to
        &cartoweb; root directory. </para>
     <para>
      For instance: 
    </para>
    <programlisting><![CDATA[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]]></programlisting>
   </sect3>
  </sect2>
  
  <sect2 id="user.pdf.tutorial.roles">
   <title><indexterm><primary>Roles management, PDF</primary></indexterm>Roles Management</title>
   <para>
    &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 <xref linkend="user.security"/>.
   </para>
   <para>
    To do so, simply add to considered objects/blocks an <parameter>allowedRoles</parameter> property set to the comma-separated list of roles you want to restrict them to.
   </para>
   <para>
    For instance: 
   </para>
   <itemizedlist>                                                                       <listitem>
     <para>
      to enable PDF printing only for <parameter>loggedIn</parameter> users, use:
     </para>
     <programlisting><![CDATA[general.allowedRoles = loggedIn]]></programlisting>
    </listitem>
    <listitem>
     <para>
      to reserve A3 format to editors or admins, use:
     </para>
     <programlisting><![CDATA[formats.A4.allowedRoles = editor, admin]]></programlisting>
    </listitem>
    <listitem>
     <para>
      to set a resolution limit for <parameter>anonymous</parameter> users when printing in A3, you can define 2 similar formats with different <parameter>maxResolution</parameter> and <parameter>allowedRoles</parameter> properties:
     </para>
     <programlisting><![CDATA[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]]></programlisting>
     <para>
      Note that all formats that may be used must any way be specified in <parameter>general.formats</parameter>.
     </para>
    </listitem>
    <listitem>
     <para>
      to hide a block for non-admin users, use:
     </para>
     <programlisting><![CDATA[blocks.overview.allowedRoles = admin]]></programlisting>
    </listitem>
   </itemizedlist>
  </sect2>
 </sect1>

</chapter>
