<?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: edit.xml,v 1.12 2007-06-15 06:11:19 ochriste Exp $ -->
<chapter id="user.edit">
  <title>Editing</title>
  <subtitle>Edit Plugin</subtitle>
  <para> The <parameter>edit</parameter> plugin allows users to edit geographical data from their web browser.
    </para>
  <sect1 id="user.edit.client">
    <title>Client-side Configuration</title>
    <sect2 id="user.edit.client.ini">
      <title>edit.ini</title>
      <para>Here are the options that can be set on the client: </para>
      <itemizedlist>
        <listitem>
          <para> 
            general.allowedRoles: comma separated list of the roles that are
             allowed to use the edit plugin
            </para>
        </listitem>
        <listitem>
          <para> insertedFeaturesMaxNumber<indexterm><primary>insertedFeaturesMaxNumber</primary></indexterm>: 
            integer, number of new features that user is allowed to draw for
             insertion in the database</para>
          <para> Set it to 0 if user is only allowed to update or delete features.</para>
        </listitem>
        <listitem>
          <para> 
            editLayers<indexterm><primary>editLayers</primary></indexterm>: 
            comma separated list of layers that are editable</para>
        </listitem>
        <listitem>
          <para> 
            editResultNbCol<indexterm><primary>editResultNbCol</primary></indexterm>: 
            number of columns to use to display the attributes table</para>
        </listitem>
        <listitem>
          <para> 
            editDisplayAction<indexterm><primary>editDisplayAction</primary></indexterm>: 
            this string parameter is used to tell if the "validate" and "cancel" buttons
            have to be displayed also under the attributes table. If empty or <parameter>both</parameter>, buttons will be displayed both in the folder and under the attributes table. If <parameter>folder</parameter>, buttons will be displayed only in the folder.</para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1 id="user.edit.mapfile">
    <title>Related Elements in Mapfile</title>
    <sect2 id="user.edit.mapfile.layers">
      <title>Metadatas</title>
      <para>Specific metadatas must be set in the mapfile for the editable layers
        </para>
      <programlisting><![CDATA[
METADATA
    ...
    'edit_table' 'edit_poly' # PostGIS table
    'edit_geometry_column' 'the_geom' # PostGIS geometry column
    'edit_geometry_type' 'polygon' # PostGIS geometry type
    'edit_srid' '-1'
    'edit_attributes' 'parc_id,name|string,culture|string,surf,parc_type|integer' # list of the editable fields
END]]></programlisting>
      <itemizedlist>
        <listitem>
          <para> 
            edit_table<indexterm><primary>edit_table</primary></indexterm>: 
            string, name of the postGIS table to edit</para>
        </listitem>
        <listitem>
          <para> 
            edit_geometry_column<indexterm><primary>edit_geometry_column</primary></indexterm>: 
            string, name of the geometry field in the table</para>
        </listitem>
        <listitem>
          <para> 
            edit_geometry_type<indexterm><primary>edit_geometry_type</primary></indexterm>: 
            string, type of the geometry of the features for the layer</para>
           <para>possible values are point, line, polygon</para>
           <para>May differ from the msLayer type (rendering)</para>
        </listitem>
        <listitem>
          <para> 
            edit_srid<indexterm><primary>edit_srid</primary></indexterm>: 
            integer (optional), id of the SRID </para>
        </listitem>
        <listitem>
          <para> 
            edit_attributes<indexterm><primary>edit_attributes</primary></indexterm>: 
            string, comma separated list of attributes used for edition.</para>
          <para>Each value represents the attribute name and type separated by a
            pipe symbol. Only attributes with type set are editable.</para>
          <para><warning><para>Attribute types available values are <emphasis>'string'</emphasis> and <emphasis>'integer'</emphasis>.</para></warning></para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1 id="user.edit.howto">
    <title>How To</title>
    <para>In this section are described the steps to get the edit plugin working
    on a cartoweb project.
    </para>
    <itemizedlist>
      <listitem>
        <formalpara>
          <title>First, you need a PostgreSQL database with postGIS enabled.</title>
          <para>Let's say, it is named "edit_db" for the following explanations.</para>
        </formalpara>
      </listitem>
      <listitem>
        <formalpara>
          <title>At that point, you may launch <emphasis>demoEdit_schema.sql</emphasis>
          and <emphasis>demoEdit_data.sql</emphasis></title>
          <para>
          located in the
          </para>
        </formalpara>
        <para>
          <filename>&lt;CARTOWEB_HOME&gt;/projects/demoEdit/</filename> directory.
        </para>
        <para>This will create 3 sample geometry tables, one for each type of geometry.
        </para>
      </listitem>
      <listitem>
        <formalpara>
          <title>In &cartoweb;, you'll have to load the edit plugin in your
           project on both client and server sides.</title>
          <para>
            <programlisting><![CDATA[
loadPlugins = [...], edit
]]></programlisting>
          </para>
        </formalpara>
      </listitem>
      <listitem>
        <formalpara>
          <title>Then, you'll need to configure the plugin by setting the
           layer_ids in the editLayers parameter in the edit.ini file.</title>
          <para>
            <programlisting><![CDATA[
editLayers = edit_poly, edit_line, edit_point
]]></programlisting>
          </para>
        </formalpara>
      </listitem>
      <listitem>
        <formalpara>
          <title>In your mapfile, in the corresponding LAYER, you'll have to
           set the specific metadatas as following :</title>
          <para>
            <programlisting><![CDATA[
LAYER
  NAME "edit_poly"
  STATUS ON
  TYPE POLYGON
  CONNECTIONTYPE POSTGIS
  CONNECTION 'dbname=edit_db user=www-data password=www-data host=localhost'
  DATA 'the_geom from (select the_geom, oid, parc_id, name, culture, surf, parc_type  from edit_poly) as foo'
  TEMPLATE 'ttt'
[...]
  LABELITEM "name"
  CLASS
    NAME "class"
    STYLE
      COLOR 50 50 255
      OUTLINECOLOR 255 50 50
    END
    LABEL
[...]
    END
  END
  METADATA
    'id_attribute_string' 'parc_id' # query
    'query_returned_attributes' 'parc_id name culture surf parc_type'
    'edit_table' 'edit_poly' # PostGIS table
    'edit_geometry_column' 'the_geom' # PostGIS geometry column
    'edit_geometry_type' 'polygon' # PostGIS geometry type
    'edit_srid' '-1'
    'edit_attributes' 'parc_id,name|string,culture|string,surf,parc_type|integer' # list of the editable fields
    'edit_filter' '' # mapserver filter
  END
END
]]></programlisting>
          </para>
        </formalpara>
        <warning>
          <para>Make sure that your <parameter>edit_attributes</parameter> list does not include spaces between attributes.</para>
        </warning>
      </listitem>
    </itemizedlist>
  </sect1>
</chapter>
