<?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: annotate.xml,v 1.22 2007-07-26 15:15:12 olivier Exp $ -->
<chapter id="user.annotate">
  <title>Annotation and Redlining</title>
  <subtitle>Plugin Outline</subtitle>
  <para> Imagine you want to draw some features (points, lines, polygons ...) 
    in your map to show specific data and/or print it. The outline plugin is 
    what you need. </para>
  <para> It allows you to draw features and to annotate them with label texts. 
    </para>
  <para> It's also possible to use polygons shapes as a mask layer see "Mask 
    mode". User can choose between mask or draw mode with radio buttons. See 
    <xref linkend="user.annotate.server.ini" /> for more information. </para>
  <para> Shapes colors and styles should be set with specific configuration in 
    the mapfile (See <xref linkend="user.annotate.mapfile" />). </para>
  <para>The total area of the drawn polygons is displayed on the 
    interface.</para>
  <sect1 id="user.annotate.client">
    <title>Client-side Configuration</title>
    <sect2 id="user.annotate.client.ini">
      <title>outline.ini</title>
      <para>Here are the options that can be set on the client: </para>
      <itemizedlist>
        <listitem>
          <para> 
            multipleShapes<indexterm><primary>multipleShapes</primary></indexterm>: 
            boolean, if true, the user is allowed to draw multiple shapes. That 
            means that drawn features remain until browser session is closed. 
            If false, will outline only one shape at a time, new feature simply 
            erases / overrides currently drawn one. When he wants, the user can 
            erase all the drawn feature by clicking on the "outline_clear" form 
            button (default true). </para>
        </listitem>
        <listitem>
          <para> labelMode<indexterm><primary>labelMode</primary></indexterm>: 
            boolean, if true, user is asked to input a label text that is drawn 
            to annotate drawn shape. </para>
        </listitem>
        <listitem>
          <para> 
            weightOutlinePoint<indexterm><primary>weightOutlinePoint</primary></indexterm>: 
            integer defining display order of the outline_point tool icon in 
            toolbar (if not specified, default to 70). A negative weight 
            disables the tool. </para>
        </listitem>
        <listitem>
          <para> 
            weightOutlineLine<indexterm><primary>weightOutlineLine</primary></indexterm>: 
            see weightOutlinePoint (default to 71) </para>
        </listitem>
        <listitem>
          <para> 
            weightOutlineRectangle<indexterm><primary>weightOutlineRectangle</primary></indexterm>: 
            see weightOutlinePoint (default to 72) </para>
        </listitem>
        <listitem>
          <para> 
            weightOutlinePoly<indexterm><primary>weightOutlinePoly</primary></indexterm>: 
            see weightOutlinePoint (default to 73) </para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1 id="user.annotate.server">
    <title>Server-side Configuration</title>
    <sect2 id="user.annotate.server.ini">
      <title>outline.ini</title>
      <para>Here are the options that can be set on the server: </para>
      <itemizedlist>
        <listitem>
          <para> 
            pointLayer<indexterm><primary>pointLayer</primary></indexterm>: 
            defines the name of the mapserver LAYER set in the mapfile to 
            display points.</para>
        </listitem>
        <listitem>
          <para> lineLayer<indexterm><primary>lineLayer</primary></indexterm>: 
            defines the name of the mapserver LAYER set in the mapfile to 
            display lines.</para>
        </listitem>
        <listitem>
          <para> polygonLayer<indexterm><primary>polygonLayer</primary></indexterm>: 
            defines the name of the mapserver LAYER set in the mapfile to 
            display polygons. Note that rectangles are displayed as polygons. 
            </para>
        </listitem>
        <listitem>
          <para> maskColor<indexterm><primary>maskColor</primary></indexterm>: 
            defines the RGB color of the mask. This color is used to fill the 
            polygons outside's area. Drawn polys will appear as holes in a 
            colored sheet, showing the map under. This parameter is optional 
            and set by default to 255 255 255 (white). </para>
        </listitem>
        <listitem>
          <para> 
            areaFactor<indexterm><primary>areaFactor</primary></indexterm>: 
            defines an optional value for ratio by which the area is multiplied 
            before it is returned to the client. For example, people can use it 
            to convert square meters to square kilometers. </para>
        </listitem>
        <listitem>
        <para> symbolPickerHilight = inversed|borderhilight: set the hilight
mode to use in the SymbolPicker interface. See 
<xref linkend="user.annotate.toolpicker.usage.symbol"/>.</para>
      </listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1 id="user.annotate.mapfile">
    <title>Related Elements in Mapfile</title>
    <sect2 id="user.annotate.mapfile.layers">
      <title>Layers</title>
      <para>Specific layers must be set in the mapfile in order to draw the 
        shapes:</para>
      <programlisting><![CDATA[
LAYER
  NAME "cartoweb_point_outline"
  TYPE POINT
  ...
END

LAYER
  NAME "cartoweb_line_outline"
  TYPE LINE
  ...
END

LAYER
  NAME "cartoweb_polygon_outline"
  TYPE POLYGON
  ...
END]]></programlisting>
      <para> Don't forget that layers names must be set in the server-side 
        outline.ini file (See <xref linkend="user.annotate.server.ini" />) 
        </para>
    </sect2>
    <sect2 id="user.annotate.mapfile.label">
      <title>Labels</title>
      <para>In case of using labels (i.e. labelMode set to true, see <xref 
        linkend="user.annotate.client.ini" />), a LABEL object is needed in the 
        layers' class. </para>
      <para>Example:<programlisting><![CDATA[
LAYER
  NAME "cartoweb_point_outline"
  TYPE POINT
  ...
  CLASS
    STYLE
      ...
    END
    LABEL
      FONT Vera
      TYPE truetype
      COLOR 51 51 51
      SIZE 10
    END
  END
END]]></programlisting> You will find more examples looking in the test.map 
        file in server_conf directory. </para>
    </sect2>
  </sect1>

  <sect1 id="user.annotate.getparam">
    <title>GET Parameters</title>
    <para>Creates outline drawing on-the-fly by passing a geometry type and one 
    or more point coordinates via the URL.</para>
    <sect2 id="user.annotate.getparam.paramlist">
      <title>Accepted Parameters</title>
      <para>Parameters list</para>
      <itemizedlist>
        <listitem>
          <para>outline_point
          <screen>http://www.example.com/cartoweb/myproject.php?outline_point=611748,5232242</screen>
          </para>
        </listitem>
        <listitem>
          <para>outline_line
          <screen>http://www.example.com/cartoweb/myproject.php?outline_line=611748,5232242;748204,5232242;748204,5050300;611748,5050300</screen>
          </para>
        </listitem>
        <listitem>
          <para>outline_poly
          <screen>http://www.example.com/cartoweb/myproject.php?outline_poly=611748,5232242;748204,5232242;748204,5050300;611748,5050300;611748,5232242</screen>
          </para>
        </listitem>
      </itemizedlist>
      <note>
        <para>If you do not want to have persistent outline, you can add the 
          <emphasis>prevent_save_session</emphasis> parameter in the URL. For example:
            <screen>http://www.example.com/cartoweb/myproject.php?outline_point=611748,5232242&amp;prevent_save_session</screen>
            This may be useful if you use the <emphasis>mode=image</emphasis> output:
            <screen>http://www.example.com/cartoweb/myproject.php?mode=image&amp;outline_point=611748,5232242&amp;prevent_save_session</screen>
        </para>
      </note>
    </sect2>
  </sect1>

  <sect1 id="user.annotate.toolpicker">
    <title>The ToolPicker</title>
    <sect2 id="user.annotate.toolpicker.what">
      <title>What is the ToolPicker</title>
      <para>The ToolPicker is a mini javascript framework used to display 
dynamically on screen several DHTML tools.</para>
      <para>Some tools come pre-included:</para>
      <itemizedlist>
        <listitem>
          <para>ColorPicker : The ColorPicker allows the user to pick a color. 
He/she can either pick it from a gradient map, use RGB or HSL slider, input 
RGB or HSL values , input an hexadecial value or pick it from a preselected 
list of colors. The color value is then returned to the main page.</para>
        </listitem>
        <listitem>
          <para>SymbolPicker : The SymbolPicker allows the user to pick a 
symbol in a predefined list of symbols. The symbols are generated off the 
.sym file on the serverside of CartoWeb. The symbol is then returned to the 
main page.</para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="user.annotate.toolpicker.install">
      <title>Installation</title>
      <para>To use the ToolPicker in a project, simply enable it in your 
client.ini configuration file, by setting toolPickerOn = true.</para>
      <para>The ToolPicker requires the corresponding script, css and template 
      in the cartoclient.tpl file.</para>
      <para>In the header :
        <programlisting><![CDATA[<link rel="stylesheet" type="text/css" href="css/toolPicker.css" />]]></programlisting>
      In the body, preferably at the end :
        <programlisting><![CDATA[{include file="toolPicker.tpl"}]]></programlisting>
      </para>
    </sect2>
    <sect2 id="user.annotate.toolpicker.usage">
      <title>ToolPicker Usage</title>
      <para>The main ToolPicker function accepts 3 parameters, 2 are mandatory, 
      the last is optional.
        <programlisting><![CDATA[toolPicker( string tool_id_list, string tool_input_list [, string tool_output_list])]]></programlisting>
       </para>
       <para><emphasis role="bold">tool_id_list</emphasis></para>
       <para>You can initialize one or more tools at once. The 
       <emphasis>tool_id_list</emphasis> parameter is composed of one or more 
       numerical values, separated by comma and enclosed by quotes 
       (or simplequotes). Example: '2' or '1,4' or '3,2,1'</para>
       <para>The order of the id influes on the order of the tool panels when 
       displayed on screen.</para>
       <para><emphasis role="bold">tool_input_list</emphasis> and <emphasis role="bold">tool_output_list</emphasis></para>
       <para>The script needs an input value and will return an output value. 
       The input value is retrieved from an html input element. In the same 
       way the output value is returned to an html input element.</para>
       <para>The script needs as many input element id as initialised tools. 
       If two tools are initialised (parameter <emphasis>tool_id_list</emphasis>), <emphasis>tool_input_list</emphasis> must also contain two input id. 
       Ids are separated by comma and enclosed by quotes (or simplequotes). 
       Example: 'return_id_tool_4,return_id_tool_2'</para>
       <para>The first input id corresponds to the first tool id in <emphasis>tool_id_list</emphasis>.</para>
       <para>A different id can be specified if the element storing the output 
       value must be different from the element storing the input value. The 
       same rule applies to <emphasis>tool_input_list</emphasis> and <emphasis>tool_output_list</emphasis>.</para>
       <para>See <xref linkend="user.annotate.toolpicker.exemples" /></para>
      <para>Each tool also have some particularities:</para>
      <sect3 id="user.annotate.toolpicker.usage.color">
        <title>ColorPicker</title>
        <para>When a color is selected, the script will set the css property <emphasis>background-color</emphasis> of a div in the template 
        accordingly to the color picked.</para>
        <para>The id of the div is based on the output element id (if it 
        specified, if not, the input element id is used), to which a 
        <emphasis>_d</emphasis> is added.</para>
        <para>Example, if the input element id is 
        <emphasis>return_color_12</emphasis>, the id of the div used to display 
        the color will be <emphasis>return_color_12_d</emphasis>.</para>
      </sect3>
      <sect3 id="user.annotate.toolpicker.usage.symbol">
        <title>SymbolPicker</title>
        <para>When a symbol is selected, the script will set the css property <emphasis>background-image</emphasis> of a div in the template 
        accordingly to the symbol picked.</para>
        <para>The id of the div is based on the output element id (if it 
        specified, if not, the input element id is used), to which a 
        <emphasis>_d</emphasis> is added.</para>
        <para>Example, if the input element id is 
        <emphasis>return_symbol_12</emphasis>, the id of the div used to display 
        the symbol will be <emphasis>return_symbol_12_d</emphasis>.</para>
        <para>The SymbolPicker is used with &cartoweb; outline plugin usually, 
        but it also can be used without the plugin.</para>
        <sect4 id="user.annotate.toolpicker.usage.symbol.within">
          <title>Within the Outline Plugin</title>
          <para>In &cartoweb; <emphasis>server_conf/yourprojectname/outline.ini</emphasis> 
          file defines a list of symbols to use. For each kind of symbols 
          you want to use:
          <programlisting><![CDATA[pointSymbols = "circle, square, star [, anyothersymbol, ... ]"]]></programlisting>
          </para>
          <para>All these symbol names <emphasis role="bold">MUST BE</emphasis> 
          defined in the .sym file in 
          <emphasis>server_conf/yourprojectname/</emphasis>.</para>
          <para>If you want to add language support for the symbol name, add 
          the following parameter in 
          <emphasis>server_conf/yourprojectname/outline.ini</emphasis>:
          <programlisting><![CDATA[pointSymbols.labels = "symbolname1, symbolname2 [, anyothername, ... ]"]]></programlisting>
          </para>
          <para>These names will be used to translate into the chosen language 
          using the gettext functionnality. Add the corresponding translations 
          in the server .po files.</para>
        </sect4>
        <sect4  id="user.annotate.toolpicker.usage.symbol.without">
          <title>Without the Outline Plugin (Standalone Use)</title>
          <para>If you do not use the outline plugin, you will need to set the 
          following javaScript variable somewhere in your page:
          <programlisting>&lt;script type="text/javascript"&gt;
  /*&lt;![CDATA[*/
    var imgPath = 'path/to/symbol/images/';
    var symbolType = 'type/of/image/files/'; //jpeg, gif, png, whatever

    var symbolNamesArray = new Array("symbolfilename1","symbolfilename2" [,"othersymbolfilename", ...] );

    var symbolLabelArray = new Array("symbollabel1","symbollabel2" [,"othersymbollabel", ...] );
  /*]]&gt;*/
&lt;/script&gt;</programlisting>
           </para>
           <para><emphasis>symbolNamesArray</emphasis> contains the list of 
           filename to use for your images.</para>
           <para><emphasis>symbolLabelArray</emphasis> contains the list of 
           label used on screen for the symbols.</para>
           <para>Create your symbol images and put them in 
           <emphasis>path/to/symbol/images/</emphasis>. You also need to 
           create hilighted versions of your images, give them the same 
           filename but add the suffix '_over'. Exemple: symbol_1.gif -> 
           symbol_1_over.gif</para>
           <para>Put them in the same folder.</para>
        </sect4>
        <sect4 id="user.annotate.toolpicker.usage.symbol.hilight">
          <title>Symbol Hilight Mode</title>
          <para>There are two modes to hilight the selected symbol in the 
          <emphasis>SymbolPicker</emphasis> interface. You can select between 
          <emphasis>border hilight</emphasis> and 
          <emphasis>inverted image</emphasis>. <emphasis>border hilight</emphasis> 
          simply use a css property to hilight the border of the selected symbol. 
          <emphasis>inverted image</emphasis> need the php library GD to create 
          an inverted version of the symbol, which is then used for the selected 
          symbol.</para>
          <para>The hiligh mode is set in the <emphasis>server_conf/outline.ini</emphasis> 
          file:</para>
          <itemizedlist>
            <listitem>
              <para>symbolPickerHilight = inversed|borderhilight</para>
            </listitem>
          </itemizedlist>
        </sect4>
      </sect3>
    </sect2>
    <sect2 id="user.annotate.toolpicker.default">
      <title>ToolPicker Default Values</title>
      <para>If the toolPicker is used with the Outline plugin, the default 
      values for Color, OutlineColor, Transparency and Symbol are set in the 
      mapfile.</para>
      <para>The default layer name are cartoweb_point_outline, 
      cartoweb_line_outline and cartoweb_polygon_outline</para>
      <para>See <xref linkend="user.annotate.server.ini" /></para>
    </sect2>
    <sect2 id="user.annotate.toolpicker.exemples">
      <title>Examples of Usage</title>
      <programlisting>toolPicker('4','outline_point_symbol')</programlisting>
      <para>this will call the symbol picker (id 4), the input id is <emphasis>outline_point_symbol</emphasis>, and the output id will be <emphasis>outline_point_symbol</emphasis> too</para>
      <programlisting>toolPicker('1','outline_point_color', 'color_return')</programlisting>
      <para>this will call the color picker, the input id is 
      <emphasis>outline_point_color</emphasis>, and the output id will be <emphasis>color_return</emphasis></para>
      <programlisting>toolPicker('4,1','symbol_input,color_input', 'return_symbol,return_color')</programlisting>
      <para>this will call the symbol picker and the color picker, the input 
      id is <emphasis>symbol_input</emphasis> for the first tool (here the 
      symbol picker) and <emphasis>color_input</emphasis> for the second tool 
      (color picker), and the output id will be 
      <emphasis>return_symbol</emphasis> for the first tool and 
      <emphasis>return_color</emphasis> for the second.</para>
    </sect2>
    <sect2 id="user.annotate.toolpicker.new">
      <title>Creating New Tools</title>
      <para>You can add new tools.</para>
      <para>Add the new tool name in the <emphasis>toolArrayRef</emphasis> 
      array at the begining of the script.
      <programlisting>var toolArrayRef =  new Array( 'colorPicker', 
                                'hashArray',
                                'pencilArray',
                                'symbolArray',
                                'yourTool');</programlisting>
      </para>
      <para>Create the following four functions, these functions can be empty.
      <programlisting>function yourToolInit(inputValue) { ... }
function yourToolSetup() { ... }
function yourToolReturn() {
    ...
    return someValue;
}
function yourToolDisplay(targetElm) { ... }</programlisting>
      </para>
      <para>The Init function is used to set the incoming values. It is always 
      called when the ToolPicker starts. It receives the input value recovered 
      from the main page.</para>
      <para>The Setup function can be used to do all the actions you want.</para>
      <para>The Return function is used to return a value to the main page.</para>
      <para>The Display function is used to display something in the main page. 
      It receives the id of the target element to use 
      (<emphasis>something_d</emphasis>).</para>
      <para>Add the following four function definitions:
      <programlisting>functionList["yourToolInit"]=yourToolInit;
functionList["yourToolSetup"]=yourToolSetup;
functionList["yourToolReturn"]=yourToolReturn;
functionList["yourToolDisplay"]=yourToolDisplay;</programlisting>
      These are needed because of the dynamic function call inside the 
      framework, which do not use the eval() function to increase performances.
      </para>
      <para>The width of the tool area available on screen is 245 pixel. Height 
      is variable.</para>
    </sect2>
  </sect1>
</chapter>
