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:
-
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 thecoreplugins/
directory. -
plugins
: "normal" plugins perform more specificactions and are not always activated. Normal plugins activation is done by setting theloadPlugins
parameter inclient_conf/client.ini
for CartoClient plugins and inserver_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 theplugins/
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.
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 fromtemplates/
are only called byclient/
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 instancejava/
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.
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). T