23. ToolTips

23.1. Introduction

The tooltips plugin aim is to show features attributive information on top of the map without refreshing the whole page. This can be achieved using three different methods.

The choice must be done regarding advantages or disadvantages of each method.

23.2. Basic Usage

23.2.1. Mouse Timeout Asynchronous

23.2.1.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.1.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

23.2.1.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”)

timeout_async.region.label = "Régions"
timeout_async.region.dsn = "pgsql://www-data:www-data@localhost:5432/france"
timeout_async.region.dbTableName = region
timeout_async.region.attributes = "nom, code"
timeout_async.region.template = "layerResult_region.tpl"

23.2.2. Area Asynchronous

23.2.2.1. Introduction

For the area_async defined layers, area tags are sent within the HTML source of the page. So, interactive areas are available on the map on top of corresponding features.

When the user moves the mouse over each area, and stopping during several milliseconds, an AJAX request is sent to CartoWeb using the id of the given feature. A response is sent back to the browser within the HTML code, in regard to the selected feature.

23.2.2.2. Pros / Cons

Pros

semi live result,
the layout for the result can be customized

Cons

does not work for line type features,
may be ressource consuming and performances may fail for large amount of features (but less than with the area_direct method),
database (postgresql) required,
only one result at a time, if several features are stacked on each other, only the result of the uppermost feature is displayed.

23.2.2.3. Configuration

Here are defined parameters available for area_async layers

label : (optional) label fo 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
idAttributeString : name of the field in the database matching to the id_attribute_string metadata in mapfile
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”)

area_async.members.label = "Members"
area_async.members.dsn = "pgsql://www-data:www-data@localhost:5432/france"
area_async.members.dbTableName = points
area_async.members.attributes = "name,age,place"

Note

For area_async layers, layer definition in mapfile doesn't have to be a postgis (connectiontype) layer. For example, user is able to draw geographical data coming from a shapefile and show attribute values coming from a non geographical database.

23.2.3. Area Direct

23.2.3.1. Introduction

For the area_direct defined layers, area tags are sent within the HTML source of the page, as well as the relative attributes (names and values). Interactive areas area available on the map on top of corresponding features.

When the user moves the mouse over each area, and stops during several milliseconds, a basic HTML table is built with the attributes using javascript and display with the tooltip.

23.2.3.2. Pros / Cons

Pros

simplest way to use tooltips,
no database needed, can work with shapefiles (or data files)
no server call, live result

Cons

cannot work for line type features,
may be ressource consuming and performances may fail for large amount of features,
only one result at one time, if several features are stacked on each other, only the result of the uppermost feature is displayed,
the layout cannot be customized

23.2.3.3. Configuration

Here are defined parameters available for area_direct layers

label : label fo the layer

area_direct.region.label = "Regions"
area_direct.users.label = "Users"

The list of attributes names and values that are displayed in the tooltip is set with the "query_returned_attributes" metadata in the mapfile as used for the query tool.

23.3. Custom Tooltips

23.3.1. Templates

Tip

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

23.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 timeout_async or area_async layers.

23.3.1.2. Layer Specific Template

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

23.3.2. Extending classes

For the timeout_async layers, if a class extending ByXyQueryableLayer with a name like LayerIdQueryableLayer exists, it will be taken into account.

Similarly, for the area_async, the classes extending ByIdQueryableLayer 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 or ByIdQueryableLayer 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)

23.3.3. Styling

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

TODO