< Structure

Configuration Files >

3. Projects Handling

3.1. Introduction

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

3.2. Using Projects

There are several ways to tell CartoWeb what project to use:

3.2.1. Apache Environment Variable

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

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

3.2.2. Using current_project.txt

Add a file named current_project.txt in CartoWeb root directory. This file must contain a single line with project name.

3.2.3. Using a GET Parameter

You can pass a GET parameter project=YOUR_PROJECT to the client.php script, for instance:


3.2.4. Using the Projects Drop-down List

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.

3.2.5. Using a Modified client.php

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.

  $_ENV['CW3_PROJECT'] = 'myproject';

valid xhtml 1.0 valid css