Projects are used to customize a CartoWeb application to your needs. By creating a new project you can override templates, resources files (pictures, style sheets, JavaScript files, etc.), configuration files and even add new plugins or modify existing ones.
It is strongly recommended to use projects when deploying a CartoWeb application with non-standard layout or plugins. The main reason is the necessity to keep upstream files unchanged in order to easily apply the application upgrades.
Projects are in fact a mirrored collection of directories and files from the original architecture. Files placed in a project are in most cases used preferentially to the original files. There is an exception with plugins PHP classes: the latter must be extended and not simply overridden. In projects you can also add brand new files (for instance new plugins) that have no original version in the upstream structure. Fore more details about how to write or customize plugins in projects, see Chapter 2, New Plugins in Part III, “Developer Manual”.
Note that you don't need to duplicate the whole CartoWeb structure in your projects. Only directories that contain overriding files have to be created. In .ini files, only variables set in projects are overridden. Other variables keep the values set in upstream .ini files.
Following files can be "overridden":
-
client_conf/*.ini(client.ini and plugins configuration files) -
[core]plugins/*/client/*.php -
[core]plugins/*/common/*.php -
[core]plugins/*/server/*.php -
[core]plugins/*/htdocs/*.php -
[core]plugins/*/templates/*.tpl -
htdocs/css/*.css -
htdocs/js/*.js -
htdocs/gfx/layout/*.gif -
server_conf/server.ini -
server_conf/<mapId>/*.ini(<mapId>.ini and plugins configuration files) -
templates/*.tpl
You can add project-specific mapfiles in directory
/projects/my_project/server_conf/my_mapfile. To
point to the new mapfile, change the mapId value in
/projects/my_project/client_conf/client.ini.
You can add project-specific plugins in directory
/projects/my_project/plugins. To load the new
plugin, add its name in client.ini and/or
my_mapfile.ini (loadPlugins variable).
There are several ways to tell CartoWeb what project to use:
Set environment variable CW3_PROJECT in Apache configuration.
<Directory /your/cartoclient/path/> Options FollowSymLinks Action php-script /cgi-bin/php5 AddHandler php-script .php # [...] SetEnv CW3_PROJECT your_project_name </Directory>
Warning: You will need Apache's Env module to use SetEnv command. To load this module, add the following line to your Apache configuration:
LoadModule env_module /usr/lib/apache/1.3/mod_env.so
Add a file named current_project.txt in
CartoWeb root directory. This file must contain a single line with
project name.
You can pass a GET parameter
project=YOUR_PROJECT to the
client.php script, for instance:
http://path.to/cartoweb/client.php?project=myProject
Have a look at the configuration of
client.ini described in Section 4.2, “
client.ini
”, in particular directives
showProjectChooser and
availableProjects, to display the project
selection drop-down menu.
If showProjectChooser is true, a dropdown
menu will appear in your CartoClient interface, giving the list of
all projects available in your /projects/
directory. Selecting one will make it the active one. Your choice is
propagated from page to page. Note that if the selected project has
showProjectChooser set to false, the project
selection dropdown will no more appear, keeping you from activating
another project. To go back to the initial project, call the initial
client.php page without posting the HTML
form.
This should be avoided in production, but may be useful in
development if you have to frequently switch the working project: add
a new file client_myproject.php in the root htdocs
directory. This file only sets the environment variable and then calls
the normal client.php. Each project has so its own
URL.
<?php
$_ENV['CW3_PROJECT'] = 'myproject';
require_once('client.php');
?>
