2. New Plugins

2.1. What are Plugins

2.1.1. Definition

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.

2.1.2. Plugins and Coreplugins

There are two kinds of plugins:

coreplugins: fundamental plugins that perform "low-level" actions such as map size handling, browsing tools, layers selection. Plugins that are frequently used in many CartoWeb applications may be included in this category as well. They are always available and activated. As a result, other plugins may interact with them. Coreplugins files are grouped in the coreplugins/ directory.
plugins: "normal" plugins perform more specificactions and are not always activated. Normal plugins activation is done by setting the loadPlugins parameter in client_conf/client.ini for CartoClient plugins and in server_conf/<mapId>/<mapId>.ini for CartoServer ones. For instance:
```
loadPlugins = auth, outline, exportHtml
       
```
Since they are not always available, simple plugins usually do not rely on each other. On the other hand, it is not a problem for them to call some coreplugins functionalities if the latter are publicly accessible. Simple plugins files are grouped in the plugins/ directory.

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.

2.1.3. Plugins Structure

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/

client/ contains all specific CartoClient-side PHP files.
server/ contains all specific CartoServer-side PHP files.
common/ contains PHP files shared by both CartoClient and CartoServer sides, or at least files that are not specific to one side or the other.
templates/ contains all the plugin-specific Smarty templates. Since HTML templates are only used in CartoClient, files from templates/ are only called by client/ code.
htdocs/ contains all files (PHP pages, images, JavaScript or CSS files, etc.) that may be web-accessed when running the plugin. Those files are dispatched in various directories depending on their nature. If necessary, you can create additional subdirectories. For instance java/ if your plugin uses a Java applet. To preserve the plugin independence, it is strongly recommended not to add your CSS styles in the general CartoClient style sheet but to create a specific file here that will be called separately.

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.

2.2. Writing a Plugin

2.2.1. Introduction

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 */
}

2.2.2. Plugin or Coreplugin?

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

2.2.3. How Plugins Are Called

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