<?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: layers.xml,v 1.28 2007-07-26 15:15:13 olivier Exp $ -->
<chapter id="user.layers">
  <title>Layers</title>
  <sect1 id="user.layers.intro">
    <title>Introduction</title>
    <para> Geographical data are most often apprehended as thematic layers: you 
      may have a layer "Rivers", a layer "Aerial view", a layer "Average 
      income", just to cite a few examples. Now the basic purpose of any viewer 
      is to make these data available to users by allowing navigation within a 
      layer as well as comparison between layers. A way to organize the layers 
      is thus mandatory if an user-friendly application is to be developed. In 
      &cartoweb;, the files that contain the configuration instructions for the 
      layers are on the server-side, in the directory 
      <filename>server_conf/&lt;myMap&gt;</filename>. Usually this directory is 
      part of a project. </para>
    <para> &cartoweb; is based on the geographical engine Mapserver. The 
      Mapserver documentation <ulink 
      url="http://mapserver.gis.umn.edu/doc.html"> 
      http://mapserver.gis.umn.edu/doc.html</ulink> is an integral part of the 
      &cartoweb; doc. To be concise, you have to know how to write a mapfile if 
      you want to use &cartoweb;. So it doesn't come as a surprise that a 
      mapfile, <filename>myMap.map</filename>, is included in the 
      <filename>&lt;myMap&gt;</filename> directory, together with its annexes 
      (typically a symbol file <filename>myMap.sym</filename>, a directory 
      <filename>etc</filename> for the required fonts, the graphic file used as 
      keymap background, maybe also data files). </para>
    <para> We'll see that some functionalities of &cartoweb; require small 
      changes of the mapfile content. But most of the configuration is done in 
      the file <filename>layers.ini</filename>. </para>
    <para> The file <filename>myMap.ini</filename> sets the required plugins 
      and the initial state of the map. Its content is described in <xref 
      linkend="user.config"/> </para>
  </sect1>
  <sect1 id="user.layers.tree">
    <title>Hierarchy of Layers and Rendering</title>
    <para> Contrary to Mapserver itself, &cartoweb; supports an arbitrarily 
      complex hierarchy of layers and different rendering options. The notion 
      of LayerGroup makes it possible. </para>
    <sect2 id="user.layers.tree.types">
      <title>Layers and LayerGroups</title>
      <para> There are two types of "layers-like objects" in 
        <filename>layers.ini</filename> : Layers and LayerGroups. They play 
        fairly different roles and consequently have different possible 
        attributes. Layers have a 1-to-1 correspondance to Mapserver layers (as 
        defined in the <filename>layers.map</filename>), while LayerGroups 
        group together atomic Layers or other LayerGroups. </para>
    </sect2>
    <sect2 id="user.layers.tree.layers">
      <title>Layers Options</title>
      <para> As seen before, the Layer object maps directly to a layer in the 
        mapfile. By default, all layers in the mapfile are made available as a 
        Layer in the layers.ini, with an identifier having the same name as the 
        name of the mapserver layer. Thus, if you have the following option in 
        your mapfile:</para>
      <programlisting><![CDATA[LAYER
  NAME "my_layer"
  TYPE line 
END]]></programlisting>
      <para> This is equivalent as writing the following configuration in the 
        <filename>layers.ini</filename>: </para>
      <programlisting><![CDATA[layers.my_layer.class = Layer 
layers.my_layer.label = my_layer
layers.my_layer.msLayer = my_layer]]></programlisting>
      <tip>
        <para>If you don't need special parameters (see below) for your layer 
          then you can avoid adding it in the 
          <filename>layers.ini</filename></para>
      </tip>
      <para>However, if you want these layers to appear in the layer list, you 
        still have the responsibility to affect them a parent layer, using the 
        <literal>children</literal> property of the 
        <literal>LayerGroup</literal> layer declarations. </para>
      <para> <indexterm><primary>layers</primary></indexterm> Here is the 
        syntax for the various configuration parameters of a Layer.</para>
      <itemizedlist>
        <listitem>
          <para> layers.layerId.className = Layer : defines the object as a 
            Layer; layerId is a string that uniquely identifies the object. The 
            general rules of syntax for a .ini file must be respected in the 
            choice of the layerId (e.g. no '-' are allowed). </para>
        </listitem>
        <listitem>
          <para> layers.layerId.msLayer = string : name of the corresponding 
            Mapserver layer in the mapfile </para>
        </listitem>
        <listitem>
          <para> layers.layerId.label = string : caption of the layer in the 
            layer tree on the client; this is a 'raw' label, before any 
            internationalization. The i18n scripts automatically include this 
            label in the strings that can be translated. </para>
        </listitem>
        <listitem>
          <para> layers.layerId.icon = filename : filename of the static picto 
            that illustrates this Layer in the layer tree. The file is expected
            to be in <filename>server_conf/&lt;mapId&gt;/icons</filename> and
            a setup script launch is in most cases required.
            See also <xref linkend="user.layers.legend"/> for a description of
            the automatic legending process. </para>
        </listitem>
        <listitem>
          <para> layers.layerId.link = url : provides a link for the layer 
            (e.g. to some metadata); makes the caption in the tree clickable. 
            </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="user.layers.tree.layergroups">
      <title>LayerGroups Options</title>
      <para> <indexterm><primary>layergroups</primary></indexterm> Here is the 
        syntax for the various configuration parameters of LayerGroups. Note 
        that a special LayerGroup with layerId=root must be 
        <indexterm><primary>root layergroup</primary></indexterm> present. 
        Unsurprisingly, it is the root (top level) of the hierarchy. It doesn't 
        appear in the visible tree.</para>
      <itemizedlist>
        <listitem>
          <para> layers.layerId.className = LayerGroup : defines the object as 
            a LayerGroup; layerId is a string that uniquely identifies the 
            object. The general rules of syntax for a .ini file must be 
            respected in the choice of the layerId (e.g. no '-' are allowed). 
            </para>
        </listitem>
        <listitem>
          <para> layers.layerId.children = list of layerIds : comma-separated 
            list of layerIds; these children may be Layers or other 
            LayerGroups. </para>
        </listitem>
        <listitem>
          <para> layers.layerId.children.switchId = list of layerIds : 
            comma-separated list of layerIds, when using switching (see <xref 
            linkend="user.layers.tree.children"/>). This option cannot be used 
            together with simple children option.</para>
        </listitem>
        <listitem>
          <para> layers.layerId.aggregate = true|false : if true, the children 
            objects are not listed in the tree and not individually selectable. 
            Default is false. </para>
        </listitem>
        <listitem>
          <para> layers.layerId.label = string : caption of the layer in the 
            layer tree on the client; this is a 'raw' label, before any 
            internationalization. The i18n scripts automatically include this 
            label in the strings that can be translated. </para>
        </listitem>
        <listitem>
          <para> layers.layerId.icon = filename : filename of the static picto 
            that illustrates this Layer in the layer tree. The path is relative 
            to <filename>myMap.ini</filename>. See also <xref 
            linkend="user.layers.legend"/> for a description of the automatic 
            legending process. </para>
        </listitem>
        <listitem>
          <para> layers.layerId.link = url : provides a link for the layer 
            (e.g. to some metadata); makes the caption in the tree clickable. 
            </para>
        </listitem>
        <listitem>
          <para> layers.layerId.rendering = tree|block|radio|dropdown : 
            indicates how to display the LayerGroup children.</para>
          <itemizedlist>
            <listitem>
              <para> tree (default value): children layers are rendered below 
                the LayerGroup with an indentation. If children are not 
                declared as "frozen" or "hidden" they will be preceded by a 
                checkbox input. A node folding/unfolding link is displayed 
                before the LayerGroup. </para>
            </listitem>
            <listitem>
              <para> radio: quite similar to the "tree" rendering with "radio" 
                buttons replacing checkboxes. Only one child layer can be 
                selected at a time. </para>
            </listitem>
            <listitem>
              <para> block: children layers are separated as blocks (separation 
                medium depends on the template layout). Note that the rendering 
                will be applied to the children, not to the LayerGroup itself, 
                which is not displayed at all. </para>
            </listitem>
            <listitem>
              <para> dropdown: as for block rendering, the LayerGroup is not 
                displayed. Its children are simply rendered as an HTML "simple 
                select" options list. If the selected child layer cannot be 
                determined using posted or session-saved data, first child 
                (according to the layers.layerId.children list order) is 
                selected. If any, only the selected child layer's own children 
                are displayed under the dropdown list. </para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
         <para>layers.layerId.metadata.minScale (resp. maxScale): one may specify a numerical minimal (resp. maximal) scale for the given LayerGroup. This parameter has absolutely no effect on Mapserver behavior and is only used to display out-of-scale icons and links in the layers tree. For more info about <filename>layers.ini</filename> metadata parameters, see <xref linkend="user.layers.metadata.inifile"/>.</para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="user.layers.tree.children">
      <title>Children Switching</title>
      <para> Children switching is useful to define several lists of children 
        for one layer group. The children that will be displayed is choosen by 
        a special parameter : the switch ID. </para>
      <para>Switch IDs and labels are listed in file 
        <filename>layers.ini</filename>. In default test environment, a 
        dropdown is constructed using this list and displayed in the GUI.</para>
      <programlisting><![CDATA[switches.switch1.label = Switch 1
switches.switch2.label = Switch 2
switches.switch3.label = Switch 3]]></programlisting>
      <para> Then, each layer group that needs to change its children depending 
        on the switch ID may add this ID as a suffix to the children option. 
        </para>
      <programlisting><![CDATA[layers.layerId.className = LayerGroup
layers.layerId.children.switch1 = layer1, layer3
layers.layerId.children.switch2 = layer2, layer3
layers.layerId.children.switch3 =]]></programlisting>
      <para>Special suffix <parameter>default</parameter> can be used to define 
        a default children list : </para>
      <programlisting><![CDATA[layers.layerId.className = LayerGroup
layers.layerId.children.switch2 = layer2, layer3
layers.layerId.children.default =]]></programlisting>
      <para>The following layer group definitions are equivalent :</para>
      <programlisting><![CDATA[layers.layerId.className = LayerGroup
layers.layerId.children.default = layer4]]></programlisting>
      <programlisting><![CDATA[layers.layerId.className = LayerGroup
layers.layerId.children = layer4]]></programlisting>
    </sect2>
  </sect1>
  <sect1 id="user.layers.metadata">
    <title>Metadata in Mapfile and <filename>layers.ini</filename></title>
    <para> Metadata are (keyword, value) pairs which can be associated to a 
      MapServer layer in the mapfile, or to a Layer or LayerGroup in the 
      layers.ini configuration file. These metadata are used in several 
      different contextes, such as layer specific configuration, security 
      handling, ... The metadata related to the functionalities of &cartoweb; 
      are described in the documentation of the corresponding plugins. </para>
    <sect2 id="user.layers.metadata.mapfile">
      <title>Metadata in Mapfiles</title>
      <para> Specifying metadata in mapfiles is based on the standard MapServer 
        syntax. For instance: </para>
      <programlisting><![CDATA[LAYER
  NAME "my_layer"
  [...]
  METADATA
    "exported_values" "security_view,some_specific_parameter"
    "security_view" "admin" 
    "some_specific_parameter" "value"
    
    "id_attribute_string" "FID|string" 
    "mask_transparency" "50"
    "mask_color" "255, 255, 0"
    "area_fixed_value" "10"
  END
  [...]
END]]></programlisting>
      <para>The metadata key <constant>exported_values</constant> is a bit 
        special: It gives the list of metadata keys (coma separated), which 
        will be transmitted to the client. This is required for the metadata 
        keys describing layer security for instance, as they are used on the 
        &cartoclient;. </para>
    </sect2>
    <sect2 id="user.layers.metadata.inifile">
      <title>Metadata in <filename>layers.ini</filename></title>
      <para> The configuration file <filename>layers.ini</filename> may also 
        contain metadata (key, value) pairs. This is needed for LayerGroup 
        objects, as these have no counterparts in the mapfile. For simple 
        layers, the metadata specified in the <filename>layers.ini</filename> 
        take precedence over the values from the mapfile. </para>
      <para> For each layer object in the <filename>layers.ini</filename> file, 
        the following syntax is used to set metadata:</para>
      <programlisting>layers.layerId.metadata.METADATA = value</programlisting>
      <para>For instance:</para>
      <programlisting><![CDATA[layers.group_admin.className = LayerGroup 
layers.group_admin.children = grid_defaulthilight 
layers.group_admin.metadata.security_view = admin]]></programlisting>
       <note>
        <para>It is possible to specify <parameter>minScale</parameter> and 
         <parameter>maxScale</parameter> attributes as <filename>layers.ini</filename> 
         <parameter>metadata</parameter> for layerGroups items. The equivalent mapfile metadata 
         is not available for layers. In that case, simply use mapfile MINSCALE and MAXSCALE
         attributes.
        </para>
       </note>
      
    </sect2>
    <sect2 id="user.layers.metadata.template">
      <title>Using the metadata fields in templates (<filename>layers.tpl</filename>)</title>
      <para>Metadata declared in mapfiles or <filename>layers.ini</filename>
        can be used in the <filename>layers.tpl</filename> Smarty templates 
        using the following notation:
        </para>
        <programlisting><![CDATA[
{capture name=caption}
{$element.layerLabel} <a
href="/?lang={$element.layerMeta.lang}&client_id={$element.layerMeta.client_id}">
{element.layerMeta.complex_label}</a>
{/capture}]]></programlisting>
        <para>
        As we can see in the previous example, metadata values can be used through the 
        <literal>layerMeta</literal> property of the <literal>$element</literal> Smarty 
        variable. Typical usage of this feature is to render for instance several 
        HTML links for each layers.
        </para>
    </sect2>
  </sect1>
  <sect1 id="user.layers.legend">
    <title>Layers Legends</title>
    <para> <indexterm><primary>Legend</primary></indexterm> &cartoweb; includes 
      a mechanism for the automatic generation of legends. If desired, an icon 
      is drawn for each class of the layers. There are two conditions that must 
      be fulfilled to make it work : </para>
    <para> 1. The mechanism must be enabled by setting</para>
    <programlisting><![CDATA[autoClassLegend = true]]></programlisting>
    <para><indexterm><primary>autoClassLegend</primary></indexterm> in 
      <filename>layers.ini</filename>. </para>
    <para> 2. Each class (or more precisely each class that should appear in 
      the legend) must have a name. Here an example : </para>
    <para>
      <screen><![CDATA[LAYER
  NAME "spur_spurweite"
  METADATA
  ...
  END
  TYPE line
  ...

  CLASS
    NAME "Normalspur (1435 mm)"
    EXPRESSION ([MM] = 1435)
    STYLE
      COLOR 0 0 255 # blue
    END
  END

  CLASS
#   NAME "Meterspur (1000 mm)"
    EXPRESSION ([MM] = 1000)
    STYLE
      COLOR 255 0 0 # red
    END
  END

  CLASS
    NAME "Schmalspur (< 900 mm)"
    EXPRESSION ([MM] < 900)
    STYLE
      COLOR 128 0 128 # lila
    END
  END

END
]]></screen>
    </para>
    <para> In this case, the second class would not appear in the legend, 
      because the NAME is commented out. </para>
    <para> Provided that no static icon is defined for a layer in 
      <filename>layers.ini</filename>, the icon of the first visible class is 
      used for the layer. </para>
    <para>Legend icons are also used when exporting maps in PDF (see
    <xref linkend="user.pdf"/>). Standard legend icons are used by default,
    which means that they may seem pixelized when printing a 300 dpi map.
    To resolve this issue, the following parameter can be set in 
    <filename>layers.ini</filename>:</para>
    <screen><![CDATA[
legendResolutions = 96, 150, 300]]></screen>
    <para>Each resolution must correspond to one of those set in PDF Export
    configuration file. This file is described in
    <xref linkend="user.pdf.reference.general"/>.</para>
  </sect1>
  <sect1 id="user.layers.wms_legend">
    <title>WMS Layers Legends</title>
    <para>
      <indexterm><primary>WMS Legend</primary></indexterm> Mapserver could
      act like a <acronym>WMS</acronym> client and retrieved layer from 
      distant <acronym>WMS</acronym> server. In this specific case, layers
      legends could be retrieved directly from a distant server with 
      <acronym>SLD</acronym> support (<literal>getLegendGraphic</literal>
      method).
    </para>
    <para> 
      <indexterm><primary>wms_legend_graphic</primary></indexterm> You must 
      also add a metadata on each WMS layer to retrieve its legend icon:
      <parameter>wms_legend_graphic</parameter>
    </para>
    <para>
      Here is an example:
      <programlisting><![CDATA[
LAYER
  NAME 'prov_boundary'
  TYPE RASTER 

  CONNECTION 'http://www2.dmsolutions.ca/cgi-bin/mswms_gmap?'
  CONNECTIONTYPE WMS
  METADATA
    'wms_srs'             'EPSG:4326'
    'wms_name'            'prov_bound'
    'wms_server_version'  '1.1.1'
    'wms_format'          'image/png'
    'wms_legend_graphic'  'true'
  END
END]]></programlisting>
    </para>
  </sect1>
  <sect1 id="user.layers.autolayer">
    <title>Auto Layers</title>
    <para>In some cases, it may be useful to generate several layers out of a 
      single "template" layer. An example would be floors : each floor must be 
      displayed with the same color, etc. but the data source is different 
      (different shapefile or different where clause for a database layer). In 
      &cartoweb;, it is possible to add PHP code into mapfiles. True mapfiles 
      are then generated by a batch script. The generated layers are called 
      "Auto Layers".</para>
    <sect2 id="user.layers.autolayer.layersini">
      <title>Auto Layers in <filename>layers.ini</filename></title>
      <para>First, you have to declare the list of auto layers indexes. Indexes 
        will be used as suffixes for generated layers :</para>
      <programlisting><![CDATA[autoLayersIndexes = index1, index2]]></programlisting>
      <para>Then you can use auto layers just as other layers. In this exemple, 
        an auto layer <parameter>myAutoLayer_</parameter> was declared in the 
        mapfile template (see <xref linkend="user.layers.autolayer.mapfile" 
        />). </para>
      <programlisting><![CDATA[layers.layer1.className = LayerGroup
layers.layer1.children = layer2, myAutoLayer_index1

layers.layer2.className = LayerGroup
layers.layer2.children = myAutoLayer_index2]]> </programlisting>
    </sect2>
    <sect2 id="user.layers.autolayer.mapfile">
      <title>Mapfile Templates</title>
      <para>Mapfile templates for auto layers are PHP files. The main template 
        must be called <filename>mapId.map.php</filename>. If this file exists, 
        then &cartoweb; assumes that auto layers generation is used. If the 
        file does not exists, &cartoweb; looks for a standard 
        <filename>mapId.map</filename>. </para>
      <para>The following functions are predefined and can be used in mapfile 
        templates :</para>
      <itemizedlist>
        <listitem>
          <para> <function>printLayer($name, $contents)</function> : adds a new 
            auto layer. The name is the final name of the layer without the 
            index suffix. Contents include Mapserver layer definition with PHP 
            code for parts that will be different for each instance of auto 
            layer </para>
        </listitem>
        <listitem>
          <para><function>printIndex()</function> : adds the current auto layer 
            index. Must be used in auto layer contents </para>
        </listitem>
        <listitem>
          <para><function>printName()</function> : adds the current auto layer 
            full name. Must be used in auto layer contents </para>
        </listitem>
        <listitem>
          <para><function>getIndex()</function> : returns the current auto 
            layer index. It can be useful for instance in conditional 
            statements. Must be used in auto layer contents</para>
        </listitem>
        <listitem>
          <para><function>includeFile($path)</function> : adds the content of 
            another PHP mapfile template</para>
        </listitem>
      </itemizedlist>
      <para> Here is an example : </para>
      <programlisting><![CDATA[MAP
  NAME "MyMapfile"
  EXTENT -10 -10 10 10
# ...

<?php

printLayer('myAutoLayer_', 

<<<AUTOLAYER

  # This is my auto layer with index <?php printIndex(); ?>
  LAYER
    NAME <?php printName(); ?>
    TYPE POLYGON
# ...
    CLASS
      NAME "MyClass"
      STYLE
        COLOR <?php if(getIndex() == 'index2') print "200 200 255";
                                          else print "255 153 102"; ?>
      END
    END
  END
AUTOLAYER
);

?>

END]]> </programlisting>
    </sect2>
    <sect2 id="user.layers.autolayer.makemaps">
      <title>Batch Script</title>
      <para>Script <filename>makemaps.php</filename> located in directory 
        <filename>scripts</filename> generates mapfiles out of mapfile 
        templates for all projects. Mapfiles are generated in the same 
        directory. The script must be called once during installation and then 
        each time a change is made to the mapfile templates. </para>
      <para>It uses file<filename>layers.ini</filename> to find out which auto 
        layers are needed. For instance, with the following 
        <filename>layers.ini</filename>, myAutoLayer_index3 won't be 
        generated.</para>
      <programlisting><![CDATA[autoLayersIndexes = index1, index2, index3
      
layers.layer1.className = LayerGroup
layers.layer1.children = layer2, myAutoLayer_index1

layers.layer2.className = LayerGroup
layers.layer2.children = myAutoLayer_index2]]> </programlisting>
      <para>At least one file is generated. Its name is 
        <filename>auto.mapId.all.map</filename> and it contains all auto layers 
        used in file <filename>layers.ini</filename>. When children switching 
        is used (see <xref linkend="user.layers.tree.children" />), one mapfile 
        is generated per switch. One more is generated for special switch 
        <parameter>default</parameter>. This way, only auto layers used with 
        the current switch are actually loaded at runtime. Mapfile 
        <filename>auto.mapId.all.map</filename> is still generated.</para>
      <para>In the following example, 4 mapfiles are generated : </para>
      <programlisting><![CDATA[autoLayersIndexes = index1, index2, index3, index4
      
switches.switch1.label = Switch 1
switches.switch2.label = Switch 2

layers.layer1.className = LayerGroup
layers.layer1.children.switch1 = layer2, myAutoLayer_index1
layers.layer1.children.default = layer2, myAutoLayer_index2

layers.layer2.className = LayerGroup
layers.layer2.children = myAutoLayer_index4]]> </programlisting>
      <itemizedlist>
        <listitem>
          <para> <filename>auto.mapId.all.map</filename> : contains all layers 
            used in <filename>layers.ini</filename>, ie. layers 
            myAutoLayer_index1, myAutoLayer_index2 and myAutoLayer_index4</para>
        </listitem>
        <listitem>
          <para> <filename>auto.mapId.switch1.map</filename> : contains layers 
            used when Switch 1 is selected, ie. layers myAutoLayer_index1 and 
            myAutoLayer_index4</para>
        </listitem>
        <listitem>
          <para> <filename>auto.mapId.switch2.map</filename> : contains layers 
            used when Switch 2 is selected, ie. layers myAutoLayer_index2 and 
            myAutoLayer_index4</para>
        </listitem>
        <listitem>
          <para> <filename>auto.mapId.default.map</filename> : contains layers 
            used when no switch is selected, ie. layers myAutoLayer_index2 and 
            myAutoLayer_index4</para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="user.layers.layer_reorder">
    <title>Layer Reorder Plugin</title>
    <para>
      Ability to reorder displayed layers could be appreciated by end user.
      And so, even if your map is well designed
      with largest features layers on bottom and smallest on top, and/or
      even with well used transparent properties.
      The plugin layerReorder <indexterm><primary>layerReorder</primary>
      </indexterm>, is designed to do so. Layers could be
      reorder on the displayed stack to improve visibility of one layer.
    </para>
    <para>
      Each layer defined in the mapfile and currently selected in legend menu
      (and only them) will be displayed in the reorder menu list.
    </para>
    <sect2 id="user.layers.layer_reorder.activation">
      <title>Plugin activation</title>
      <para>
        To activate the plugin, add it to 
        <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>loadPlugins = layerReorder</programlisting>
      </para>
    </sect2>
    <sect2 id="user.layers.layer_reorder.exclusion">
      <title>Layer exclusion</title>
      <para>
        If you want to exclude some layers and then not allow them to be
        reordered, have a look on 
        <filename>client_conf/layerReorder.ini</filename>. You will be able to
        exclude some layers and to choose to keep them on bottom (or on top). 
        To do so, use the following configuration parameters:
        <itemizedlist>
          <listitem>
            <para>
              <indexterm><primary>topLayers</primary></indexterm>
              <parameter>topLayers</parameter>: list of all layerIds to keep
          on top of the genererated map (LayerIds must be comma separated).
            </para>
          </listitem>
          <listitem>
            <para>
              <indexterm><primary>bottomLayers</primary></indexterm>
              <parameter>bottomLayers</parameter>: same as previous one, but
              obviously keep these layerIds on bottom. Useful for example 
              with a raster background layer.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </sect2>
    <sect2 id="user.layers.layer_reorder.transparency">
      <title>Transparency selector</title>
      <para>
        <indexterm><primary>enableTransparency</primary></indexterm>
        You could also add a transparency selector on each layer displayed with
        this plugin. End user will so be able to choose a different transparency
        level for each displayed layer.
      </para>
      <para>
        To activate it, set <parameter>enableTransparency</parameter> to 
        <literal>true</literal> in <filename>client_conf/layerReorder.ini</filename>.
      </para>
      <para>
        <indexterm><primary>transparencyLevels</primary></indexterm>
        Default transparency selector values are : 10%, 20%, 50%, 75% and 100%.
        You could also customize transparency values available in this 
        selector, with a comma separated value in 
        <parameter>transparencyLevels</parameter>. A transparency value is a 
        integer between 1 to 100 ; with 100 mean an opaque layer as 1 mean a 
        nearly invisible one.
      </para>
    </sect2>
  </sect1>

</chapter>
