< Projects Handling

Caches Configuration >

4. Configuration Files

When installing CartoWeb, the administrator of the application may want to adapt it to the environnement use. This can be easily done using configuration parameters.

Some are required and CartoWeb won't correctly work if they're not set. Others are optional but could hardly change the application behavior.

You will also find specific config parameters in the plugins related chapters of this documentation.

4.1. Common client.ini and server.ini Options

Common options for both client and server. These parameters are available in client_conf/client.ini for client and server_conf/server.ini for server.

  • profile = development|production|custom: current settings profile. The development profile has no cache activated and makes SOAP work in WSDL mode. The production profile has all caches activated for best performances. Setting this parameter to development or production will override some parameters in the configuration. The custom profile means the parameters about caching and other are not overrided.
  • useWsdl = true|false: if true, WSDL will be used for sending SOAP requests. This will add some processing time but ensures that SOAP requests are well-structured. In addition, WSDL is necessary when interfacing the Web Service with a strong-typed language built application.

Cache options. See Section 5.6, “Caches Configuration”.

Developer options. See Section 4.5, “Developer Specific Configuration”.

4.2.  client.ini

CartoServer access configuration:

  • cartoserverDirectAccess = true|false: toggles between SOAP and direct modes. Direct access gives enhanced performances, but is only available if CartoServer runs on the same server as CartoClient.
  • cartoclientBaseUrl: base URL of the CartoClient
  • cartoserverBaseUrl: base URL of the CartoServer (i.e. path containing the cartoserver.wsdl.php file)

Mapfile configuration:

  • mapId = string
  • initialMapStateId = string. Tells what initialMapState to use when creating a new CartoWeb session (see also Section, “Initial Mapstates”).


    initialMapStateId may be determined using several means. By order of priority:

    1. URLs (using GET parameter initialState)
    2. PHP environment variables. Place
      $_ENV['CW3_INITIAL_MAP_STATE_ID'] = 'foobar';
      in your PHP code before calling CartoWeb.
    3. client.ini
    4. If no initialMapStateId can be determined, CartoWeb use first initialMapState available.

Session handling:

  • sessionNameSuffix = string. Optional suffix used to distinguish CartoClient sessions parts for a given user. In most cases it is not necessary but may be needed when using, for instance, "sub-projects". This string is an ulimited comma-separated list of type:value couples. Three types are available:
    • str: a constant string
    • conf: uses value of one of the current client.ini configuration parameters
    • env: uses value of given PHP environment variable, if set.
    For instance:
    sessionNameSuffix = "str:toto, conf:profile, env:myEnvVar"
    sessionNameSuffix = "str:foo, str:bar"
    sessionNameSuffix = "env:CW3_APP_ID"

Tools configuration:

  • initialTool: indicates which tool is activated when in initial state. If not specified, the first tool in the toolbar is activated. Possible values are: zoomin, zoomout, pan, query, distance, surface.
  • toolbarRendering: indicates how to render tools selectors icons within toolbar. Possible values are 'radio' (default), 'outline', 'swap'. If 'radio': an HTML radio button appear nexts to each tool icon. If 'outline': active tool icon is outlined with a colored border. If 'swap': an alternate icon ("over") is displayed to mark the active tool.

Project handling configuration:

  • showProjectChooser = true|false: Shows a drop-down list for selecting the active project.
  • availableProjects = list: List of the project to show in the drop down list. If not set, all projects found will be used.

Plugins configuration:

  • loadPlugins = list: list of client plugins to load in addition to the core plugins. Note that most client plugins also have a corresponding server plugin that must be loaded on the server side. See Section, “ <myMap>.ini.


  • I18nClass is now deprecated See Chapter 17, Internationalization for a description of the internationalization options and the corresponding configurations.
  • defaultLang = string: default language, possible values are the usual ISO locale codes (en, fr, de ...)
  • langList = list: list of usable languages. Used to order and restrict the available languages. In case you have many languages in directory <cartoweb_home>/locale/ and do not want to use them all in your project, you may use this parameter to specify a list of languages to use. The order in which you input the languages codes will be used to display the languages links in the interface.

    Example 4.1. langList usage

    langList = it,de,fr

    The exemple above restricts the availablelanguages to it, de and fr. They will be displayed in that order in the interface languages list.


Interface (GUI):

  • initialFolder = folder# : Set the default "folder" (menu tab) to by active by default. folder# is the id of the element in the template containing the corresponding plugin's specific interface. For example:
    initialFolder = folder2
    By default, folder1 is active.

4.3. Server Configuration Files

4.3.1. Introduction

This page describes the configuration options of the CartoServer. There is a global configuration file (server.ini) directly in the server_conf folder. Then all specific configurations are stored in individual folders. Each configuration contains:

  • a Mapserver mapfile (myMap.map),
  • its annexes (symbols, fonts, images, data...),
  • a main configuration file (myMap.ini) that must have the same name as the .map
  • smaller configuration files for the plugins.

By default, CartoWeb comes with a fully functional test folder, that includes the necessary geometrical datas and allows one to run an out of the box demo.

4.3.2. Main Server Configuration File (server.ini)

  • imageUrl = string: Path where cartoserver generated images can be accessed.
  • reverseProxyUrl = string: The url of the reverse proxy, if used.

4.3.3. Map Configuration Files Introduction

The CartoServer has the ability to contains several different maps. These maps are represented by the mapserver mapfile, the CartoWeb configuration file for the map and each plugins configuration.

The file that contain the configuration information related to a map, is located in the same directory as the mapfile, but has a .ini extension. These files are in the directory server_conf/<myMap>.  <myMap>.ini Initial Mapstates

Initial map states set the initial aspects of the layers selection interface when starting using CartoClient: (un)folded nodes, selected layers... Some of these properties are not modifiable in the layers selection interface (hidden layers for instance) and thus stay unchanged throughout the session.

Several initial map states can be created in myMap.ini , but at least one must be present. Each one is identified by a unique initialMapStateId. The choice to activate one or another is done client-side in client_conf/client.ini.

Available properties and syntax for layers in "initial map states" are:

  • mapInfo.initialMapStates.initialMapStateId.layers.layerId. selected = true|false: if true, layer is initially selected.
  • mapInfo.initialMapStates.initialMapStateId.layers.layerId. unfolded = true|false: if true, the layerGroup is represented as an unfolded node (children layers are visible).
  • mapInfo.initialMapStates.initialMapStateId.layers.layerId. hidden = true|false: if true, this layer and its children are not shown in the layers list (but are still displayed on the map if they're activated).
  • mapInfo.initialMapStates.initialMapStateId.layers.layerId. frozen = true|false: if true, this layer (and its children as well) is listed in tree but without checkbox. Its selection status (defined by "selected" property) thus cannot be changed.

Example of Initial MapState:

mapInfo.initialMapStates.default.layers.polygon.selected = true
mapInfo.initialMapStates.default.layers.point.hidden = true

mapInfo.initialMapStates.map25.layers.polygon.selected = true
mapInfo.initialMapStates.map25.layers.polygon.unfolded = true

4.4. Ini Files for Plugins

Each plugin may have a configuration file associated with it. It may be found in client_conf/ or server_conf/your_project_name/ directory depending which side needs to access the parameters. They have the same name as the plugin and ends with .ini extension. For instance, the layers plugin has a configuration file named layers.ini.

All plugins configuration files are described in the next sections of this chapter.

Every plugin that provides tools icons can be configured for:

4.4.1. Ordering Tools Icons

To modify the toolbar icons sequence, update the tools weight values. Icons with the lowest weights are placed first in the toolbar. Parameters naming convention is to concatenate the 'weight' prefix to the capitalized-first-lettered tool name as in weightDistance. For two-word tool names (eg. 'exemple_tool'), each word has its first letter capitalized and the '_' (underscore) is removed. For instance:

exempleTool = something

Default weights value are :

  • weightZoomin: 10
  • weightZoomout: 11
  • weightPan: 12
  • weightFullextent: 14
  • weightQueryByPoint: 40
  • weightQueryByBbox: 41
  • weightQueryByPolygon: 42
  • weightQueryByCircle: 43
  • weightOutlinePoint: 70
  • weightOutlineLine: 71
  • weightOutlineRectangle: 72
  • weightOutlinePoly: 73
  • weightOutlineCircle: 74
  • weightDistance: 80
  • weightSurface: 81

Use a negative value to deactivate a tool.

weightFullextent = -1

4.4.2. Grouping Tools Icons

CartoWeb offers the possibility to display tools icons in separated locations of its interface. For instance browsing icons may be displayed in the general toolbar whereas outline pictos may only appear in a dedicated folder. To do so, simply add an integer group index for each tool in matching plugin configuration file. For instance:

groupDistance = 2

By default, all tools icons are affected to group 1. Note that the parameters naming convention is the same than for weight parameters (see Section 4.4.1, “Ordering Tools Icons”), only substituting the 'group' prefix to the 'weight' one.

It is also possible to specify a global plugin group index that will be applied to all the given plugin tools if no individual group index has been set. To do so, use the groupPlugin in the matching plugin configuration file as follows:

groupPlugin = 3

To take benefit of the tools groups, update the main CartoWeb template file templates/cartoclient.tpl by including the toolbar.tpl template at the correct places with the correct group indexes as follows:

{include file="toolbar.tpl" group=2}

For more information about templates writing, see Chapter 18, Templating.

4.4.3. Plugins Template "folder" Target Id

When using CartoWeb with ajax mode enabled, all plugins which need to update some page content require an id to target the correct element in the template. The following plugins are known to have this behaviour:

  • layers
    default target id: folder2

  • outline
    default target id: folder6

  • geostat
    default target id: folder8

The targeted element are usualy the menu "tabs" containing each plugin specific interface. If you want to modify the default target id, you can simply add the following parameter in the corresponding plugin's .ini file on CLIENT SIDE!

For example :

folderId = layerTree

See actual usage in the demoCW3 project.

4.5. Developer Specific Configuration

Some configuration parameters can be activated to retrieve more display information targetted to the developers, like special timing messages, or setting the Php configuration to display notices on the page. These configuration options are described below.


These parameters will be overrided by the profile parameter (See Section 4.1, “Common client.ini and server.ini Options”).

These parameters are available in client_conf/client.ini for client and server_conf/server.ini for server.

  • showDevelMessages = true|false: Shows developer messages
  • developerIniConfig = true|false: Sets ini parameters useful during development
valid xhtml 1.0 valid css