<  Geostatistics

Search  >

23. ToolTips [plugin]

23.1. Introduction

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

23.2. Basic Usage

23.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.

23.2.2. Pros / Cons


  • 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


  • database (postGIS) required

23.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 23.3.2, “Extending classes”)
  • geomColName : (optional) name of the geometry column. Default is 'the_geom'.
  • srid : (optional) name of the projection system to use. Default is '-1'.
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"
  • timeoutBeforeHide : (optional) The time in millisecond before the tooltips result box disappear (if the user has not put the mouse cursor on it). Set to 3000 by default. This is a general parameter and it has a more common syntax.
    timeoutBeforeHide = 7000

23.3. Custom Tooltips

23.3.1. Templates


Make sure that the custom templates are in the templates folder in the toolTips plugin directory in your project. 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. Layer Specific Template

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

23.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.


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

It should look like :

class DepQueryableLayer extends ByXyQueryableLayer {

    public function __construct() {


     * 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).


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

23.3.3. Styling

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


23.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.

valid xhtml 1.0 valid css