<?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: locate.xml,v 1.4 2007-06-04 09:11:14 ochriste Exp $ -->
<chapter id="user.locate">
  <title><indexterm><primary>locate</primary></indexterm>Locate Plugin</title>
  <sect1 id="user.locate.intro">
   <title>Introduction</title>
   <para>
    The locate plugin deals with autocompletion of input fields used to recenter on a feature on the map. It is based on AJAX requests.
   </para>
   <para>
    When a few characters have been typed in the dedicated input field, an AJAX request
    is processed on the database defined by its DSN. The first
    results beginning with these characters are displayed in a drop down list.
   </para>
   <para>When a result is clicked, the map is recentered on it.</para>
   <para>
    The JavaScript part of this plugin is based on the 
    <ulink url="http://script.aculo.us/">script.aculo.us</ulink> Autocompleter.
   </para>
  </sect1>
  <sect1 id="user.locate.activation">
    <title>Activation</title>
    <para>
      The plugin needs obviously to be activated using the 
      <filename>client_conf/client.ini</filename>
      <parameter>loadPlugins</parameter> parameter. For instance: 
      <programlisting>loadPlugins = auth, exportPdf, views, locate</programlisting>
    </para>
    <para>To enable the plugin, you also need to add required parts in the
      <filename>cartoclient.tpl</filename> template.
      In the &lt;head&gt; element:
      <screen><![CDATA[{if $locate_active|default:''}<link rel="stylesheet" type="text/css" href="{r type=css plugin=locate}locate.css{/r}" />{/if}
      ...
{if $locate_active|default:''}<script type="text/javascript" src="{r type=js}prototype.js{/r}"></script>{/if}]]></screen>
      And in the &lt;body&gt; of the document (for example in the navigation folder):
      <screen><![CDATA[
      {if $locate_active|default:''}
           {$locate_form}
      {/if}]]></screen>
      <tip><para>Warning: make sure that the recentering in enabled (<parameter>recenterActive = true</parameter> in <filename>client_conf/location.ini</filename>)! The hidden inputs <parameter>id_recenter_layer</parameter> and <parameter>id_recenter_ids</parameter> are needed so the recentering functionnality works correctly.</para></tip>
    </para>
  </sect1>
  <sect1 id="user.locate.configuration">
    <title>Configuration</title>
    <para>
      <itemizedlist>
      <listitem>
        <para> 
          <parameter>locate.#.id</parameter> (# = 0, 1, 2, ...): id of the layer in layers.ini to recenter on.
        </para>
      </listitem>
      <listitem>
        <para> 
          <parameter>locate.#.label</parameter> (# = 0, 1, 2, ...): label of the locate input;
          Note that if you use the same label as in the layers.ini translations
          will operate.
        </para>
      </listitem>
      <listitem>
        <para> 
          <parameter>locate.#.sql</parameter> (# = 0, 1, 2, ...): SQL statement for the AJAX request to the database. It must return two fields:
          <itemizedlist>
            <listitem><para>an identifier : the value of the <parameter>id_attribute_string</parameter> field of the layer, in order to be able to recenter on the feature,</para>
            </listitem>
            <listitem><para>a label : a name for the feature to recenter on.</para>
            </listitem>
          </itemizedlist>
        </para>
      </listitem>
      </itemizedlist>
    </para>
  </sect1>
</chapter>
