<?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: tooltips.xml,v 1.6 2007-05-25 16:45:28 pgiraud Exp $ -->
<chapter id="user.tooltips">
  <title><indexterm><primary>tooltips</primary></indexterm>ToolTips</title>
  <sect1 id="user.tooltips.intro">
   <title>Introduction</title>
   <para>The tooltips plugin aim is to show features attributive information on
     top of the map without refreshing the whole page.</para>
  </sect1>
  <sect1 id="user.tooltips.basic">
    <title>Basic Usage</title>
    <sect2 id="user.tooltips.basic.intro">
      <title>Introduction</title>
      <para>When user moves the mouse over the map and stops during several
       milliseconds, an <emphasis>AJAX</emphasis> request is sent to the
        &cartoclient; using the geographical coordinates of the cursor.
      </para>
      <para>If the webserver finds features corresponding to the defined
       <emphasis>timeout_async</emphasis> layers, a response is sent back to
       the browser with some generated HTML code showing some attributive
       information.
      </para>
    </sect2>
    <sect2 id="user.tooltips.basic.proscons">
      <title>Pros / Cons</title>
      <para>Pros</para>
      <itemizedlist>
        <listitem>
          <para>fully customizable layout,</para>
        </listitem>
        <listitem>
          <para>several results can be displayed even for stacked features,
          </para>
        </listitem>
        <listitem>
          <para>isn't dependant to the feature counts, performances should
         not fail even for huge quantity of feature</para>
        </listitem>
      </itemizedlist>
      <para>Cons</para>
      <itemizedlist>
        <listitem>
          <para>database (postGIS) required</para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="user.tooltips.basic.configuration">
      <title>Configuration</title>
      <para>Here are defined parameters available for <emphasis>timeout_async
       layers</emphasis></para>
      <itemizedlist>
        <listitem>
          <para><parameter>label</parameter>
          <indexterm><primary>label</primary></indexterm>: (optional) label
           for the layer. If not set, layerId is diplayed</para>
        </listitem>
        <listitem>
          <para><parameter>dsn</parameter>
          <indexterm><primary>dsn</primary></indexterm>: connection string to
           database (Data Source Name)</para>
        </listitem>
        <listitem>
          <para><parameter>dbTableName</parameter>
          <indexterm><primary>dbTableName</primary></indexterm>: name of the
           table in database</para>
        </listitem>
        <listitem>
          <para><parameter>attributes</parameter>
          <indexterm><primary>attributes</primary></indexterm>: comma
           separated list of attributes to be displayed</para>
        </listitem>
        <listitem>
          <para><parameter>template</parameter>
          <indexterm><primary>template</primary></indexterm>: (optional)
           custom template, must be in overriden <literal>toolTips</literal>
           plugin templates directory. If not set, generic 
           <filename>layerResult.tpl</filename> is used.
           The template to use can also be set in 
           <function>renderResult</function>() method in PHP code
           if <classname>QueryableLayer</classname> is extended (See
           <xref linkend="user.tooltips.custom.extendclass" />)</para>
        </listitem>
      </itemizedlist>
      <programlisting><![CDATA[tooltips.region.label = "Régions"
tooltips.region.dsn = "pgsql://www-data:www-data@localhost:5432/france"
tooltips.region.dbTableName = region
tooltips.region.attributes = "nom, code"
tooltips.region.template = "layerResult_region.tpl"]]></programlisting>
    </sect2>
  </sect1>
  <sect1 id="user.tooltips.custom">
    <title>Custom Tooltips</title>
    <sect2 id="user.tooltips.custom.templates">
      <title>Templates</title>
      <tip>
        <para>Make sure that the custom templates are in the
        <filename>templates</filename> folder in the 
        <filename>toolTips</filename> plugin directory in your project.</para>
      </tip>
      <sect3 id="user.tooltips.custom.templates.main">
        <title>Main Template</title>
        <para>As for the other plugins, templates can be overriden in the
        projects. Then, user can define a new 
        <filename>layerResult.tpl</filename> template for all 
        <emphasis>tooltips</emphasis> layers.</para>
      </sect3>
      <sect3 id="user.tooltips.custom.templates.specific">
        <title>Layer Specific Template</title>
        <para>One can also define a specific template for each layer.
         It can be defined using the template parameter (See 
         <xref linkend="user.tooltips.basic.configuration" />) or in
         <function>renderResult</function>() method in PHP code if 
         <classname>QueryableLayer</classname> is extended (see above).</para>
      </sect3>
    </sect2>
    <sect2 id="user.tooltips.custom.extendclass">
      <title>Extending classes</title>
      <para>If a class extending
      <classname>ByXyQueryableLayer</classname> with a name like 
      <classname>LayerIdQueryableLayer</classname> exists, it will be taken
      into account.
      </para>
      <para>To do so, you should extend (replace) the 
      <literal>toolTips</literal> plugin (See 
      <xref linkend="dev.newplugin.adapting.extending" />).
      You can name it <literal>ProjectToolTips</literal> for example.</para>
      <para>So create a <filename>ClientProjectToolTips.php</filename> file
       containing something like :</para>
      <programlisting><![CDATA[require_once 'CustomLayers.php';

/**
 * Client part of ClientToolTips plugin
 * @package Plugins
 */
class ClientProjectToolTips extends ClientToolTips {

    /**
     * @see PluginManager::replacePlugin()
     */
    public function replacePlugin() {
        return 'toolTips';
    }
}]]></programlisting>
      <para>Then create a new PHP file in the same directory named 
      <filename>CustomLayers.php</filename>.
      </para>
      <important>
        <para>The name of the class that extends 
        <classname>ByXyQueryableLayer</classname> should match the layerId.
        </para>
      </important>
      <para>
      It should look like :
      </para>
      <programlisting><![CDATA[class DepQueryableLayer extends ByXyQueryableLayer {

    public function __construct() {
        parent::__construct();

        $this->addReturnedAttribute('nom_chf_l');
    }

    /**
     * Sets the type of ResultLayer returned by ResultLayer::queryLayer()
     * @see QueryableLayer::newLayerResult()
     */
    protected function newLayerResult() {
        return new DepLayerResult();
    }
}

class DepLayerResult extends LayerResult {

    /**
     * @see LayerResult::renderResult()
     */
    public function renderResult($smarty) {
        $smarty->assign('layerId', $this->getId());
        $smarty->assign('layerLabel', Encoder::encode($this->getLabel(), 'config'));
        $smarty->assign('depName', $this->getAttribute('nom_dept'));
        $smarty->assign('depCode', $this->getAttribute('code_dept'));
        $smarty->assign('depChefLieu', ucfirst(strtolower($this->getAttribute('nom_chf_l'))));
        return $smarty->fetch('layerResult_depLayer.tpl');

    }
}]]></programlisting>
      <para>This method allows people to build tooltips with results coming
      from several sources (joined tables for example).</para>
      <tip>
        <para>Don't forget to load the plugin on client-side (
        <filename>client_conf/client.ini</filename>)</para>
      </tip>
    </sect2>
    <sect2 id="user.tooltips.custom.styling">
      <title>Styling</title>
      <para>Here are some considerations on how to customize the tooltip
      appearance.</para>
      <para>TODO</para>
    </sect2>
  </sect1>
  <sect1 id="user.tooltips.incompatibilities">
    <title>Incompatibilities</title>
    <para>Please note that some features were removed from the tooltips
    plugin to enhance its stability. The <emphasis>area_async</emphasis>
    and the <emphasis>area_direct</emphasis> modes are not available anymore
    as they complicated the javascript code a lot and weren't used at all.
    And the <emphasis>timeout_async</emphasis> was replaced by
    <emphasis>tooltips</emphasis> in the configuration files.</para>
  </sect1>
</chapter>
