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

### 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:

    http://path.to/cartoweb/client.php?project=myProject

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

    <?php
      $_ENV['CW3_PROJECT'] = 'myproject';
      require_once('client.php');
    ?>