CartoWeb plugins are modular packages of files (PHP classes, HTML templates, images and other resources) that are used to perform a dedicated action: main map formatting, layers browsing interface, map browsing (zooming, paning etc.), queries, user authentication, search interfaces and many more.

There are two kinds of plugins:

The general philosophy is to gather all files of a given plugin in the same dedicated directory, including files from both CartoClient and CartoServer sides of the plugin. Thus it is easy to "plug" a new module in CartoWeb architecture by simply pasting it in the plugins/ or coreplugins/ parent directories. Note however that plugins configuration files (named <pluginName>.ini) are placed in the client_conf/ and/or server_conf/<mapId>/ depending if those plugins have CartoClient/CartoServer components.

Plugins and coreplugins have the following general structure:

<pluginName>/
<pluginName>/client/
<pluginName>/server/
<pluginName>/common/
<pluginName>/templates/
<pluginName>/htdocs/
<pluginName>/htdocs/gfx/
<pluginName>/htdocs/js/
<pluginName>/htdocs/css/

Note that it is not required to actually create the whole structure described above. Only directories that contain files are necessairy. For instance if a plugin only perform CartoServer actions, it is no use to create client/, templates/ and htdocs/ directories. common/ may be usefull if not-CartoServer-specific classes have to be defined.

There are two ways to add a plugin/coreplugin to CartoWeb: writing a brand new one or overriding/extending an existing one.

If no existing plugin or coreplugin fulfils your requirements and if none offers close enough functionalities to justify an adaptation, you can write a new plugin.

Plugins main classes (client and/or server if any) must extend CartoWeb definedClientPlugin and/or ServerPlugin classes which provide base plugin tools. For instance:

class ClientYourPlugin extends ClientPlugin {

    /* here comes your plugin client class definition */

}

First of all you have to determine if you are about to design a simple plugin or a coreplugin. To be a coreplugin, your plugin must be really generic and present a great interest to the CartoWeb users community since it might be included in the upstream distribution. Contact CartoWeb development team for more info. In most cases it is better and sufficient to create a simple plugin.

To activate a coreplugin, update the Cartoclient::getCorePluginNames() method in /client/Cartoclient.php and/or the ServerContext::getCorePluginNames() one in /server/ServerContext.php. For instance:

private function getCorePluginNames() {
return array('images', 'location', 'layers', 'query', 'mapquery',
             'tables', 'yourPluginName');
}

To load a regular plugin, update the loadPlugins parameter from client_conf/client.ini and/or server_conf/<mapId>/<mapId>.ini as in following example:

loadPlugins = auth, outline, exportHtml
      

As explained in Section 2.1, “ What are Plugins”, plugins are independent aggregations of PHP code that are called by the CartoWeb core classes to perform dedicated actions. Plugins are called several times during the program execution (entry points). Thus they can interact at various level of the application.

To determine what plugins must be called at what moment and to perform what action, plugins must implement one or more of the CartoWeb plugin interfaces (according to the object-oriented programing meaning). The interfaces define methods that will be triggered by the main program during its execution. For example, you can take a look at the following simplified Cartoclient::doMain() method ("main program") defined in /client/Cartoclient.php:

private function doMain() {
    $this->callPluginsImplementing('InitUser', 'handleInit',
                                   $this->getMapInfo());

    if ($this->isRequestPost()) {
        $this->cartoForm =
            $this->httpRequestHandler->handleHttpRequest(
                                                $this->clientSession,
                                                $this->cartoForm);

        $request = new FilterRequestModifier($_REQUEST);
        $this->callPluginsImplementing('FilterProvider',
                                       'filterPostRequest', $request);
        $this->callPluginsImplementing('GuiProvider',
                                       'handleHttpPostRequest',
                                       $request->getRequest());
    } else {
        $request = new FilterRequestModifier($_REQUEST);
        $this->callPluginsImplementing('FilterProvider',
                                       'filterGetRequest', $request);
        $this->callPluginsImplementing('GuiProvider',
                                       'handleHttpGetRequest',
                                       $request->getRequest());
    }

    $mapRequest = $this->getMapRequest();
    $this->callPluginsImplementing('ServerCaller', 'buildRequest',
                                   $mapRequest);

    $this->mapResult = $this->getMapResultFromRequest($mapRequest);

    $this->callPluginsImplementing('ServerCaller', 'initializeResult',
                                   $this->mapResult);

    $this->callPluginsImplementing('ServerCaller', 'handleResult',
                                   $this->mapResult);

    $this->formRenderer->showForm($this);

    $this->callPluginsImplementing('Sessionable', 'saveSession');
    $this->saveSession($this->clientSession);
}

callPluginsImplementing($interfaceName, $methodName, $argument) is run at various points of the program and make plugins implementing given <interfaceName> interface execute given <methodName> with given <argument> argument.

Of course interface-defined methods must be implemented in the matching plugins. Plugins can implements one or more CartoWeb interfaces.

Implementing interfaces is not mandatory when writing a plugin but not doing so will keep plugins from being implicitely called by the main program. As a result, methods from plugins with no interface implementation - also called "service plugins" - must be explicitely called by another piece of code (generally an other plugin).

class ClientYourPlugin extends ClientPlugin 
                       implements Sessionable, GuiProvider {

    /* here comes your plugin client class definition */

}

For a comprehensive list of available client and server interfaces, see /client/ClientPlugin.php and /server/ServerPlugin.php files or take a look at the CartoWeb PHP API documentation.

(Get a high quality version of this diagram here.)

Main plugin PHP files (eg. ClientYourPlugin.php, ServerYourPlugin.php, YourPlugin.php) are automatically included and their contained classes and objects are directly accessible. Other files in client/, server/ or common/ are not and must be included explicitely in the main plugin PHP files.

Templates stored in the plugin templates/ directory are also accessible directly by using PHP code similar to the followin one:

$smarty = new Smarty_Plugin($this->getCartoclient(), $this);
$smarty->assign('foo', 'bar');
return $smarty->fetch('yourPlugin.tpl');

If an already available plugin or coreplugin offers close functionalities to the ones you need, if you wish to slightly modify its behavior or simply want to adapt its output to your website layout, it is far easier to adapt it then to build a new one from scratch.

There are two levels of plugin adaptation. You can:

Both approaches are not incompatible and may be combined to obtain desired result. See Section 2.3.4, “Combining Both Approaches” for more explanations.

Overriding a plugin is the simplest way to adapt it to your needs. It is done by duplicating the plugin files (at least the ones you want to adapt) in your project frame. For more information about projects handling, see Section 2.4, “Projects”.

This approach is recommended when you want to use your own versions of the plugin templates or resources. Moreover you can add any new resources files that will be called in your customized templates. However you will not be able to replace or add PHP files (except PHP pages in the plugin htdocs/. To adapt a plugin server-side behavior (PHP classes), you have to extend the plugin, which is explained in Section 2.3.3, “Extending a Plugin”.

Say for instance, you want customize the layers coreplugin by modifying its template layers.tpl and rewriting some of its JS tools (stored in layers.js). Than your project-adapted coreplugin will look like:

/projects/<yourProjectName>/coreplugins/layers/
/projects/<yourProjectName>/coreplugins/layers/templates/
/projects/<yourProjectName>/coreplugins/layers/templates/layers.tpl
/projects/<yourProjectName>/coreplugins/layers/htdocs/
/projects/<yourProjectName>/coreplugins/layers/htdocs/js/
/projects/<yourProjectName>/coreplugins/layers/htdocs/js/layers.js
      

If you don't need to override the CSS file, it is no use to create a css/ directory containing a copy of the upstream layers.css.

If you want to neutralize a file, you can simply override it with a blank version. For instance to have a void output, create a template file with no content.

It is also possible to override the plugin configuration files by adding <pluginName>.ini files in the project configuration directories client_conf/ and/or server_conf/<mapId>/. When the plugin is launched, upstream and project configuration files are merged so you don't need to duplicate the configuration parameters that stay unchanged with your adapted plugin.

Extending a plugin is required when your adaptations involve deep changes such as additions or overloadings of methods in the plugin PHP classes.

To do so you will have to extend the plugin PHP classes in the object-oriented programing definition. Since plugin main classes are named using a plugin-name based convention (eg. ClientLayers and ServerLayers for the CartoClient and CartoServer main classes of the layers coreplugin) and since extended classes cannot have the same name than their parent class, you will have to rename your plugin. Any plugin name is OK (as long as it is not already used!) but it is recommended to use a <projectName><initialPluginName> separating words with caps.

Extended coreplugins directories and files must be saved in /projects/<projectName>/coreplugins/<extendedPluginName>/ whereas extended simple plugins ones will be located in /projects/<projectName>/plugins/<extendedPluginName>/.

When writing your extended class, the first thing to do is to specify what plugin is replaced by the new one. This is done by overloading the replacePlugin() method. It should return the replaced plugin name. For instance, to extend the layers coreplugin CartoClient part in your myProject project, create a ClientMyProjectLayers.php as follows:

<?php
/**
 * @package CorePlugins
 * @version $Id: ClientMyProjectLayers.php,v 1.8 2005/02/23 11:52:43 johndoe Exp $
 */

class ClientMyProjectLayers extends ClientLayers {

    public function replacePlugin() {
        return 'layers';
    }

    /* Add or overload methods here */
    
}
?>

To be activated, extended plugins AND coreplugins must be explicitely be declared in the loadPlugins parameter of your project general configuration files:

loadPlugins = exportPdf, auth, myProjectLayers
      

With no surprise, extended classes can take advantage of the tools provided by the interfaces their parent classes implement. By implementing additional interfaces, they will have access to complementary interactions as well. In that case, don't forget to overload the matching interface-defined methods in your extended class. For instance:

ClientMyProjectLayers extends ClientLayers
                      implements ToolProvider {

/* ... */

}

If you need to modify/add templates or resources (overrriding) AND PHP classes (extension), you can combine both approaches by following the instructions of the two last sections.

Say you would like to customize the images coreplugin (mainmap size and formats management) to:

First point is achieved by creating a images/ directory in /projects/yourProject/coreplugins/ and filling it with an overriden template mapsizes.tpl, a new images.css and some pictos:

/projects/yourProject/coreplugins/images/
/projects/yourProject/coreplugins/images/templates/mapsizes.tpl
/projects/yourProject/coreplugins/images/htdocs/css/images.css
/projects/yourProject/coreplugins/images/htdocs/gfx/button.png
      

<!-- mapsizes.tpl -->
<p>{t}Mapsize:{/t}
<select name="mapsize" id="mapsize" onchange="javascript:checkMapsize();">
{html_options options=$mapsizes_options selected=$mapsize_selected}
</select>
<input type="image" src="{r type=gfx plugin=images}button.png{/r}"
alt="{t}Ok button{/t}" id="imagesButton" /></p>

For details about template {r} (resource) and {t} (translation) tags, see Section 17.2, “Internationalization” and Section 17.3, “Resources”.

checkMapsize() JavaScript function is not defined in the upstream coreplugin. So we have to add a JS file in our overriden plugin:

/projects/yourProject/coreplugins/images/htdocs/js/
/projects/yourProject/coreplugins/images/htdocs/js/images.js
      

/* images.js */

function checkMapsize() {
  alert('foobar');
}

To add a new form field in a separated area and consequently in a separated template, there is no other way than to modify the ClientImages PHP class in order to call the additional template in a special method. The extension approach is thus required. Then create a yourProjectImages/ directory in /projects/yourProject/coreplugins/ as follows:

/projects/yourProject/coreplugins/yourProjectImages/
/projects/yourProject/coreplugins/yourProjectImages/client/
/projects/yourProject/coreplugins/yourProjectImages/client/ClientYourProjectImages.php
      

It can seem a little tricky but the new template file (say yourImages.tpl) will not be stored in /projects/yourProject/coreplugins/yourProjectImages/templates/ as one can expect it but in /projects/yourProject/coreplugins/images/templates/ with the templates of the "overriden part" of the coreplugin. Remember: templates are stored in the overriden part and PHP classes in the extended part.

<!-- yourImages.tpl -->

<input type="text" name="testField" value="{$imagesTest}" />
      

<?php
/**
 * @version $Id: ClientYourProjectImages.php,v 1.8 2005/02/23 11:52:43 johndoe Exp $
 */

class ClientYourProjectImages extends ClientImages {

    // indicates that we want to use current plugin instead of 
    // regular images plugin
    public replacePlugin() {
        return 'images';
    }

    // overloaded method
    public function renderForm(Smarty $template) {
        // a {$image2} Smarty var must have been added in cartoclient.tpl
        $template->assign('image2', $this->drawNewImagesField());
        parent::renderForm($template);
    }

    // additional method
    private function drawNewImagesField() {
        $smarty = new Smarty_Plugin($this->getCartoclient(), $this);
        $smarty->assign('imagesTest', 'Foobar');
        return $smarty->fetch('yourImages.tpl');
    }
}
?>

Don't forget to activate the extended plugin in /projects/yourProject/client_conf/client.ini:

loadPlugins = yourProjectImages
      

Export plugins allow to export maps and data. Concepts described below provide tools to help writing such plugins.

In brief, export plugins follow these steps in order to generate an output:

protected function getConfiguration() {
    $config = new ExportConfiguration();
    $config->setRenderMap(false);
    $config->setRenderKeymap(false);
    $config->setRenderScalebar(false);
}

protected function getExport() {
    $this->getExportResult($this->getConfiguration());
    
    // ...
    
    $output = new ExportOutput();
    $output->setContents($contents);
    return $output;
}

public function output() {
    header('Content-Type: text/html');
    print $this->getExport()->getContents();
    return '';
}

Filter plugins can be used to modify parameters transfered from browser to CartoWeb client. These parameters can be part of a POST request (HTML forms) or a GET request (URL query string).

Once a new filter plugin has been developed, it can be activated by adding it to the loadPlugins variable in file client_conf/client.ini.

http://example.com/cartoweb3/client.php?mode=image&mapsize=2

class ClientFilterIdrecenter extends ClientPlugin
                             implements FilterProvider {
                       
    public function filterPostRequest(FilterRequestModifier $request) {}
    
    public function filterGetRequest(FilterRequestModifier $request) {
        
        $id = $request->getValue('id');
        if (!is_null($id)) {
            $layer = 'grid_classhilight';
            $request->setValue('query_layer', $layer);
            $request->setValue('query_maskmode', '1');
            $request->setValue('query_select', $id);

            $request->setValue('id_recenter_layer', $layer);        
            $request->setValue('id_recenter_ids', $id);
        }
    }
}

Tables plugin is responsible for table formatting and display.

public function initialize() {

    $tablesPlugin = $this->cartoclient->getPluginManager()->tables; 
    $registry = $tablesPlugin->getTableRulesRegistry();
    
    // Add rules here
}

    // ...
    $tablesPlugin = $this->serverContext->getPluginManager()->tables;        
    // ...

public function addColumnSelector($groupId, $tableId, $columnIds) 
          

public function addColumnUnselector($groupId, $tableId, $columnIds) 
          

public function addGroupFilter($groupId, $callback)

static function myCallbackMethod('group_id', 'group_title')
    return 'group_new_title' 

public function addTableFilter($groupId, $tableId, $callback) 
          

static function myCallbackMethod('table_id', 'table_title')
    return 'table_new_title' 

public function addColumnFilter($groupId, $tableId,
                                $columnId, $callback)

static function myCallbackMethod('table_id', 'column_id', 'column_title')
    return 'column_new_title'

public function addCellFilter($groupId, $tableId, $columnId,
                              $inputColumnIds, $callback)

static function myCallbackMethod('table_id', 'column_id',
                                 array ('column_1' => 'value_1',
                                        'column_2' => 'value_2'))
    return 'cell_value'

        $registry->addCellFilter('query', 'table_name', '*', NULL,
                   array('TableRulesClassName', 'callbackFunctionName'));        
        

public function addCellFilterBatch($groupId, $tableId, $columnId,
                                   $inputColumnIds, $callback) 
          

static function myCallbackMethod('table_id', 'column_id',
                                 array (
                                 '0' => array (
                                        'column_1' => 'value_1_row_1',
                                        'column_2' => 'value_2_row_1'),
                                 '1' => array (
                                        'column_1' => 'value_1_row_2',
                                        'column_2' => 'value_2_row_2')))
    return array ('0' => 'cell_value_row_1', '1' => 'cell_value_row_2') 
          

public function addRowUnselector($groupId, $tableId,
                                 $columnId, $rowIds)

public function addRowSelector($groupId, $tableId,
                                 $columnId, $rowIds)

public function addColumnAdder($groupId, $tableId,
                               $columnPosition, $newColumnIds,
                               $inputColumnIds, $callback)

static function myCallbackMethod('table_id',
                                 array ('column_1' => 'value_1',
                                        'column_2' => 'value_2'))
    return array ('new_column_1' => 'cell_value_1',
                  'new_column_2' => 'cell_value_2')

public function addColumnAdderBatch($groupId, $tableId,
                                    $columnPosition, $newColumnIds,
                                    $inputColumnIds, $callback) 
          

static function myCallbackMethod('table_id',
                                 array (
                                 '0' => array (
                                        'column_1' => 'value_1_row_1',
                                        'column_2' => 'value_2_row_1'),
                                 '1' => array (
                                        'column_1' => 'value_1_row_2',
                                        'column_2' => 'value_2_row_2')))
    return array (
           '0' => array (
                  'new_column_1' => 'cell_value_1_row_1',
                  'new_column_2' => 'cell_value_2_row_1'),
           '1' => array ( 
                  'new_column_1' => 'cell_value_1_row_2',
                  'new_column_2' => 'cell_value_2_row_2')))

public function addColumnReorder($groupId, $tableId, $columnIds)
        

$registry->addColumnFilter('myGr*', 'myTable', '*',
                                     array($this, 'myCallbackMethod)); 
        

 
$registry->addColumnSelector('*', '*', array('column_1', 'column_2'));
$registry->addColumnSelector('myGr*', '*', array('column_1'));
$registry->addColumnSelector('myGr*', 'myTable', array('column_2'));
$registry->addColumnSelector('myGroup', 'toto', array('column_3')); 
        

$tablesPlugin = $this->cartoclient->getPluginManager()->tables;
$tablesPlugin->addTableGroups($newTableGroup);

$tablesPlugin = $this->serverContext->getPluginManager()->tables;
readyForClientTableGroups = $tablesPlugin->applyRules($newTableGroup);