< Geostatistics

Search >

## 22. ToolTips

## 22.1. Introduction

The tooltips plugin aim is to show features attributive information on top of the map without refreshing the whole page.

## 22.2. Basic Usage

### 22.2.1. Introduction

When user moves the mouse over the map and stops during several milliseconds, an AJAX request is sent to the CartoClient using the geographical coordinates of the cursor.

If the webserver finds features corresponding to the defined timeout_async layers, a response is sent back to the browser with some generated HTML code showing some attributive information.

### 22.2.2. Pros / Cons

Pros

- fully customizable layout,
- several results can be displayed even for stacked features,
- isn't dependant to the feature counts, performances should not fail even for huge quantity of feature

Cons

- database (postGIS) required

### 22.2.3. Configuration

Here are defined parameters available for timeout_async layers

- `label` : (optional) label for the layer. If not set, layerId is diplayed
- `dsn` : connection string to database (Data Source Name)
- `dbTableName` : name of the table in database
- `attributes` : comma separated list of attributes to be displayed
- `template` : (optional) custom template, must be in overriden `toolTips` plugin templates directory. If not set, generic `layerResult.tpl` is used. The template to use can also be set in `renderResult`() method in PHP code if `QueryableLayer` is extended (See Section 22.3.2, “Extending classes”)

    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"

## 22.3. Custom Tooltips

### 22.3.1. Templates

### Tip

Make sure that the custom templates are in the `templates` folder in the `toolTips` plugin directory in your project.

#### 22.3.1.1. Main Template

As for the other plugins, templates can be overriden in the projects. Then, user can define a new `layerResult.tpl` template for all tooltips layers.

#### 22.3.1.2. Layer Specific Template

One can also define a specific template for each layer. It can be defined using the template parameter (See Section 22.2.3, “Configuration”) or in `renderResult`() method in PHP code if `QueryableLayer` is extended (see above).

### 22.3.2. Extending classes

If a class extending `ByXyQueryableLayer` with a name like `LayerIdQueryableLayer` exists, it will be taken into account.

To do so, you should extend (replace) the `toolTips` plugin (See Section 2.3.3, “Extending a Plugin”). You can name it `ProjectToolTips` for example.

So create a `ClientProjectToolTips.php` file containing something like :

    require_once 'CustomLayers.php';

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

        /**
         * @see PluginManager::replacePlugin()
         */
        public function replacePlugin() {
            return 'toolTips';
        }
    }

Then create a new PHP file in the same directory named `CustomLayers.php`.

### Important

The name of the class that extends `ByXyQueryableLayer` should match the layerId.

It should look like :

    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');

        }
    }

This method allows people to build tooltips with results coming from several sources (joined tables for example).

### Tip

Don't forget to load the plugin on client-side ( `client_conf/client.ini`)

### 22.3.3. Styling

Here are some considerations on how to customize the tooltip appearance.

TODO

## 22.4. Incompatibilities

Please note that some features were removed from the tooltips plugin to enhance its stability. The area_async and the area_direct modes are not available anymore as they complicated the javascript code a lot and weren't used at all. And the timeout_async was replaced by tooltips in the configuration files.