<?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;
  <!ENTITY % user SYSTEM "user.ent" >
  %user;
  ]>
<!-- $Id: config.xml,v 1.41 2007-07-26 15:15:13 olivier Exp $ -->
<chapter id="user.config">
  <title>Configuration Files</title>
  <para>When installing &cartoweb;, the administrator of the application
   may want to adapt it to the environnement use. This can be easily done
   using configuration parameters.</para>
  <para>Some are required and &cartoweb; won't correctly work if they're
   not set. Others are optional but could hardly change the application
   behavior.</para>
  <para>You will also find specific config parameters in the plugins
   related chapters of this documentation.</para>
  <sect1 id="user.config.common">
    <title>Common <filename>client.ini</filename> and 
      <filename>server.ini</filename> Options</title>
    <para> Common options for both client and server. These parameters are 
      available in <filename>client_conf/client.ini</filename> for client and 
      <filename>server_conf/server.ini</filename> for server.</para>
    <itemizedlist>
      <listitem>
        <para> profile = development|production|custom: current settings profile. 
          The <parameter>development</parameter> profile has no cache activated 
          and makes SOAP work in WSDL mode. 
          The <parameter>production</parameter> profile has all caches activated 
          for best performances.
          Setting this parameter to development or production will override
          some parameters in the configuration. The custom profile means
          the parameters about caching and other are not overrided.</para>
      </listitem>   
      <listitem>
        <para> useWsdl = true|false: if true, WSDL will be used for sending 
          SOAP requests. This will add some processing time but ensures 
          that SOAP requests are well-structured. In addition, WSDL is necessary when 
          interfacing the Web Service with a strong-typed language built application.</para>
      </listitem>
    </itemizedlist>
    <para> Cache options. See <xref linkend="user.caches.config"/>. </para>
    <para> Developer options. See <xref linkend="user.config.developer"/>. 
      </para>
  </sect1>
  <sect1 id="user.config.client">
    <title>
      <filename>client.ini</filename>
    </title>
    <para> CartoServer access configuration:</para>
    <itemizedlist>
      <listitem>
        <para> cartoserverDirectAccess = true|false: toggles between SOAP and 
          direct modes. Direct access gives enhanced performances, but is only 
          available if CartoServer runs on the same server as CartoClient. 
          </para>
      </listitem>
      <listitem>
        <para> cartoclientBaseUrl: base URL of the &cartoclient;</para>
      </listitem>
      <listitem>
        <para> cartoserverBaseUrl: base URL of the &cartoserver; (i.e. path 
          containing the <filename>cartoserver.wsdl.php</filename> file)</para>
      </listitem>
    </itemizedlist>
    <para> Mapfile configuration:</para>
    <itemizedlist>
      <listitem>
        <para> mapId = string </para>
      </listitem>
      <listitem>
        <para> initialMapStateId = string. Tells what <parameter>initialMapState</parameter> 
        to use when creating a new &cartoweb; session (see also 
        <xref linkend="user.config.server.maps_config.initial"/>).</para>
        <tip>
         <para>
          <parameter>initialMapStateId</parameter> may be determined using several 
          means. By order of priority: 
          <orderedlist>
           <listitem><para>URLs (using GET parameter <parameter>initialState</parameter>)</para></listitem>
           <listitem><para>PHP environment variables. Place 
           <programlisting>$_ENV['CW3_INITIAL_MAP_STATE_ID'] = 'foobar';</programlisting> 
           in your PHP code before calling &cartoweb;.</para></listitem>
           <listitem><para>client.ini</para></listitem>
           <listitem><para>If no <parameter>initialMapStateId</parameter> can be determined, 
           &cartoweb; use first <parameter>initialMapState</parameter> available.</para></listitem>
          </orderedlist>
         </para>
        </tip>
      </listitem>
    </itemizedlist>
    <para> Session handling:</para>
    <itemizedlist>
      <listitem>
        <para> sessionNameSuffix = string. Optional suffix used to distinguish &cartoclient; 
        sessions parts for a given user. In most cases it is not necessary but may be needed 
        when using, for instance, "sub-projects". This string is an ulimited comma-separated list of
        <parameter>type</parameter>:<parameter>value</parameter> couples. Three types are available:
          <itemizedlist>
            <listitem>
              <para><parameter>str</parameter>: a constant string</para>
            </listitem>
            <listitem>
              <para><parameter>conf</parameter>: uses value of one of the current 
              <filename>client.ini</filename> configuration parameters</para>
            </listitem>
            <listitem>
              <para><parameter>env</parameter>: uses value of given PHP environment 
              variable, if set.</para>
            </listitem>
          </itemizedlist>
          For instance: 
          <programlisting>sessionNameSuffix = "str:toto, conf:profile, env:myEnvVar"
sessionNameSuffix = "str:foo, str:bar"
sessionNameSuffix = "env:CW3_APP_ID"</programlisting>
        </para>
      </listitem>
    </itemizedlist>
    <para> Tools configuration:</para>
    <itemizedlist>
      <listitem>
        <para> initialTool: indicates which tool is activated when in initial 
          state. If not specified, the first tool in the toolbar is activated. 
          Possible values are: zoomin, zoomout, pan, query, distance, 
          surface. </para>
      </listitem>
      <listitem>
        <para> toolbarRendering: indicates how to render tools selectors icons within 
        toolbar. Possible values are 'radio' (default), 'outline', 'swap'. If 'radio': 
        an HTML radio button appear nexts to each tool icon. If 'outline': active tool 
        icon is outlined with a colored border. If 'swap': an alternate icon ("over") 
        is displayed to mark the active tool.</para> 
      </listitem>
    </itemizedlist>
    <para> Project handling configuration:</para>
    <itemizedlist>
      <listitem>
        <para> showProjectChooser = true|false: Shows a drop-down list for 
          selecting the active project. </para>
      </listitem>
      <listitem>
        <para> availableProjects = list: List of the project to show in the 
          drop down list. If not set, all projects found will be used. </para>
      </listitem>
    </itemizedlist>
    <para> Plugins configuration:</para>
    <itemizedlist>
      <listitem>
        <para> loadPlugins = list: list of client plugins to load in addition 
          to the core plugins. Note that most client plugins also have a 
          corresponding server plugin that must be loaded on the server side. 
          See <xref linkend="user.config.server.maps_config.mymap_ini" />. 
          </para>
      </listitem>
    </itemizedlist>
    <para> Internationalization:</para>
    <itemizedlist>
      <listitem>
        <para> I18nClass is now <keycap>deprecated</keycap> See <xref 
          linkend="user.i18n"/> for a description of the internationalization 
          options and the corresponding configurations.</para>
      </listitem>
      <listitem>
        <para> defaultLang = string: default language, possible values are the 
          usual ISO locale codes (en, fr, de ...) </para>
      </listitem>
      <listitem>
        <para> langList = list: list of usable languages. Used to order 
and restrict the available languages. In case you have many languages in 
directory &lt;cartoweb_home&gt;/locale/ and do
         not want to use them all in your project, you may use this 
parameter to specify a list of languages to use. The order in which you 
input the languages codes will be used to display the languages links in 
the interface.</para>
         <example id="user.config.client.example">
         <title>langList usage</title>
         <programlisting>langList = it,de,fr</programlisting>
         </example>
         <para>The exemple above restricts the availablelanguages to it, 
de and fr. They will be displayed in that order in the interface 
languages list.</para>
      </listitem>
    </itemizedlist>
    <para> ToolPicker:</para>
    <itemizedlist>
      <listitem>
        <para> toolPickerOn = true|false: enable the ToolPicker dhtml. See 
        <xref linkend="user.annotate.toolpicker"/>.</para>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="user.config.server">
    <title>Server Configuration Files</title>
    <sect2 id="user.config.server.intro">
      <title>Introduction</title>
      <para> This page describes the configuration options of the CartoServer. 
        There is a global configuration file (<filename>server.ini</filename>) 
        directly in the <filename>server_conf</filename> folder. Then all 
        specific configurations are stored in individual folders. Each 
        configuration contains:</para>
      <itemizedlist>
        <listitem>
          <para> a Mapserver mapfile (<filename>myMap.map</filename>), </para>
        </listitem>
        <listitem>
          <para> its annexes (symbols, fonts, images, data...), </para>
        </listitem>
        <listitem>
          <para> a main configuration file (<filename>myMap.ini</filename>) 
            that must have the same name as the <filename>.map</filename> 
            </para>
        </listitem>
        <listitem>
          <para> smaller configuration files for the plugins. </para>
        </listitem>
      </itemizedlist>
      <para> By default, &cartoweb; comes with a fully functional 
        <filename>test</filename> folder, that includes the necessary 
        geometrical datas and allows one to run an out of the box demo. </para>
      <!--
 <para> 
  On the &cartoserver; configuration, there are the global server configuration
  <filename>server.ini</filename> and configuration for each maps. These two
  types of configuration are described in the following sections.
 </para>
-->
    </sect2>
    <sect2 id="user.config.server.main_config">
      <title>Main Server Configuration File 
        (<filename>server.ini</filename>)</title>
      <itemizedlist>
        <listitem>
          <para> imageUrl = string: Path where cartoserver generated images can 
            be accessed.</para>
        </listitem>
        <listitem>
          <para> reverseProxyUrl = string: The url of the reverse proxy, if 
            used. </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="user.config.server.maps_config">
      <title>Map Configuration Files</title>
      <sect3 id="user.config.server.maps_config.intro">
        <title>Introduction</title>
        <para> The &cartoserver; has the ability to contains several different 
          maps. These maps are represented by the mapserver mapfile, the 
          &cartoweb; configuration file for the map and each plugins 
          configuration. </para>
        <para> The file that contain the configuration information related to a 
          map, is located in the same directory as the mapfile, but has a 
          <filename>.ini</filename> extension. These files are in the directory 
          <filename>server_conf/&lt;myMap&gt;</filename>. </para>
      </sect3>
      <sect3 id="user.config.server.maps_config.mymap_ini">
        <title>
          <filename>&lt;myMap&gt;.ini</filename>
        </title>
        <itemizedlist>
          <listitem>
            <para> mapInfo.loadPlugins = list: list of server plugins to load 
              in addition to the core plugins. Note that most server plugins 
              also have a corresponding client plugin that must be loaded on 
              the client side. See <xref linkend="user.config.client" />. 
              </para>
          </listitem>
          <listitem>
            <para> mapInfo.initialMapStates.[...]: See <xref 
              linkend="user.config.server.maps_config.initial"/>. </para>
          </listitem>
        </itemizedlist>
      </sect3>
      <sect3 id="user.config.server.maps_config.initial">
        <title>Initial Mapstates</title>
        <para> <indexterm><primary>initial mapstate</primary></indexterm> 
          Initial map states set the initial aspects of the layers selection 
          interface when starting using CartoClient: (un)folded nodes, selected 
          layers... Some of these properties are not modifiable in the layers 
          selection interface (hidden layers for instance) and thus stay 
          unchanged throughout the session. </para>
        <para> Several initial map states can be created in <filename>myMap.ini 
          </filename>, but at least one must be present. Each one is identified 
          by a unique initialMapStateId. The choice to activate one or another 
          is done client-side in <filename>client_conf/client.ini</filename>. 
          </para>
        <para> Available properties and syntax for layers in "initial map 
          states" are:</para>
        <itemizedlist>
          <listitem>
            <para> mapInfo.initialMapStates.initialMapStateId.layers.layerId. 
              selected = true|false: if true, layer is initially selected. 
              </para>
          </listitem>
          <listitem>
            <para> mapInfo.initialMapStates.initialMapStateId.layers.layerId. 
              unfolded = true|false: if true, the layerGroup is represented as 
              an unfolded node (children layers are visible). </para>
          </listitem>
          <listitem>
            <para> mapInfo.initialMapStates.initialMapStateId.layers.layerId. 
              hidden = true|false: if true, this layer and its children are not 
              shown in the layers list (but are still displayed on the map if 
              they're activated). </para>
          </listitem>
          <listitem>
            <para> mapInfo.initialMapStates.initialMapStateId.layers.layerId. 
              frozen = true|false: if true, this layer (and its children as 
              well) is listed in tree but without checkbox. Its selection 
              status (defined by "selected" property) thus cannot be changed. 
              </para>
          </listitem>
        </itemizedlist>
        <para> Example of Initial MapState: </para>
        <programlisting><![CDATA[mapInfo.initialMapStates.default.layers.polygon.selected = true
mapInfo.initialMapStates.default.layers.point.hidden = true
...

mapInfo.initialMapStates.map25.layers.polygon.selected = true
mapInfo.initialMapStates.map25.layers.polygon.unfolded = true]]></programlisting>
      </sect3>
    </sect2>
  </sect1>
  <sect1 id="user.config.plugins">
    <title>Ini Files for Plugins</title>
    <para> Each plugin may have a configuration file associated with it. It may be found in 
        <filename>client_conf/</filename> or <filename>server_conf/your_project_name/</filename> 
        directory depending which side needs to access the parameters. They have the same name 
        as the plugin and ends with <filename>.ini</filename> extension. For instance, the 
        <literal>layers</literal> plugin has a configuration file named 
        <filename>layers.ini</filename>.</para>
    <para> All plugins configuration files are described in the next sections 
      of this chapter. </para>
    <para>
     Every plugin that provides tools icons can be configured for:
    </para>
    <sect2 id="user.config.plugins.order">
     <title>Ordering Tools Icons</title>
     <para>
      To modify the toolbar icons sequence, update the tools weight values. Icons with the 
      lowest weights are placed first in the toolbar. Parameters naming convention is to 
      concatenate the 'weight' prefix to the capitalized-first-lettered tool name as in 
      <parameter>weightDistance</parameter>. For two-word tool names (eg. 'exemple_tool'), 
      each word has its first letter capitalized and the '_' (underscore) is removed. 
      For instance: 
     </para>
     <programlisting>exempleTool = something</programlisting>
     <para>
      Default weights value are :
      <itemizedlist>
       <listitem>
        <para>
         weightZoomin: 10
        </para>
       </listitem>
       <listitem>
        <para>
         weightZoomout: 11
        </para>
       </listitem>
       <listitem>
        <para>
         weightPan: 12
        </para>
       </listitem>
       <listitem>
        <para>
         weightFullextent: 14
        </para>
       </listitem>
       <listitem>
        <para>
         weightQueryByPoint: 40
        </para>
       </listitem>
       <listitem>
        <para>
         weightQueryByBbox: 41
        </para>
       </listitem>
       <listitem>
        <para>
         weightQueryByPolygon: 42
        </para>
       </listitem>
       <listitem>
        <para>
         weightQueryByCircle: 43
        </para>
       </listitem>
       <listitem>
        <para>
         weightOutlinePoint: 70
        </para>
       </listitem>
       <listitem>
        <para>
         weightOutlineLine: 71
        </para>
       </listitem>
       <listitem>
        <para>
         weightOutlineRectangle: 72
        </para>
       </listitem>
       <listitem>
        <para>
         weightOutlinePoly: 73
        </para>
       </listitem>
       <listitem>
        <para>
         weightDistance: 80
        </para>
       </listitem>
       <listitem>
        <para>
         weightSurface: 81
        </para>
       </listitem>
      </itemizedlist>
     </para>
     <para>
        Use a negative value to deactivate a tool.
     </para>
     <programlisting>weightFullextent = -1</programlisting>
    </sect2>
    <sect2 id="user.config.plugins.group">
     <title>Grouping Tools Icons</title>
     <para>
      &cartoweb; offers the possibility to display tools icons in separated locations 
      of its interface. For instance browsing icons may be displayed in the general 
      toolbar whereas outline pictos may only appear in a dedicated folder. To do so, 
      simply add an integer group index for each tool in matching plugin configuration 
      file. For instance:
      <programlisting>groupDistance = 2</programlisting>
      By default, all tools icons are affected to group 1. Note that the parameters 
      naming convention is the same than for weight parameters (see <xref linkend="user.config.plugins.order"/>), 
      only substituting the 'group' prefix to the 'weight' one.
     </para>
     <para>
      It is also possible to specify a global plugin group index that will be applied to 
      all the given plugin tools if no individual group index has been set. To do so, 
      use the <parameter>groupPlugin</parameter> in the matching plugin configuration 
      file as follows:
      <programlisting>groupPlugin = 3</programlisting>
     </para>
     <para>
      To take benefit of the tools groups, update the main &cartoweb; template file 
      <filename>templates/cartoclient.tpl</filename> by including the <filename>toolbar.tpl</filename> 
      template at the correct places with the correct group indexes as follows:
      <programlisting>{include file="toolbar.tpl" group=2}</programlisting>
      For more information about templates writing, see <xref linkend="user.template"/>.
     </para>
    </sect2>
  </sect1>
  <sect1 id="user.config.developer">
    <title>Developer Specific Configuration</title>
    <para>Some configuration parameters can be activated to retrieve more 
      display information targetted to the developers, like special timing 
      messages, or setting the Php configuration to display notices on the page.
      These configuration options are described below.
      <!--
      <note>
        <para>It is recommended that you set these parameters accordingly
          if you are doing development.</para>
      </note>
      -->
      <warning>
        <para>
          &profile_overriden_plural_nowarning;
        </para>
      </warning>    </para>
    <para>These parameters are available in 
        <filename>client_conf/client.ini</filename> for client and 
        <filename>server_conf/server.ini</filename> for server. </para>
    <itemizedlist>
      <listitem>
        <para> showDevelMessages = true|false: Shows developer messages </para>
      </listitem>
      <listitem>
        <para> developerIniConfig = true|false: Sets ini parameters useful 
          during development </para>
      </listitem>
    </itemizedlist>
  </sect1>
  
</chapter>
