6. Layers

6.1. Introduction

Geographical data are most often apprehended as thematic layers: you may have a layer "Rivers", a layer "Aerial view", a layer "Average income", just to cite a few examples. Now the basic purpose of any viewer is to make these data available to users by allowing navigation within a layer as well as comparison between layers. A way to organize the layers is thus mandatory if an user-friendly application is to be developed. In CartoWeb, the files that contain the configuration instructions for the layers are on the server-side, in the directory server_conf/<myMap>. Usually this directory is part of a project.

CartoWeb is based on the geographical engine Mapserver. The Mapserver documentation http://mapserver.gis.umn.edu/doc.html is an integral part of the CartoWeb doc. To be concise, you have to know how to write a mapfile if you want to use CartoWeb. So it doesn't come as a surprise that a mapfile, myMap.map, is included in the <myMap> directory, together with its annexes (typically a symbol file myMap.sym, a directory etc for the required fonts, the graphic file used as keymap background, maybe also data files).

We'll see that some functionalities of CartoWeb require small changes of the mapfile content. But most of the configuration is done in the file layers.ini.

The file myMap.ini sets the required plugins and the initial state of the map. Its content is described in Chapter 4, Configuration Files

6.2. Hierarchy of Layers and Rendering

Contrary to Mapserver itself, CartoWeb supports an arbitrarily complex hierarchy of layers and different rendering options. The notion of LayerGroup makes it possible.

6.2.1. Layers and LayerGroups

There are two types of "layers-like objects" in layers.ini : Layers and LayerGroups. They play fairly different roles and consequently have different possible attributes. Layers have a 1-to-1 correspondance to Mapserver layers (as defined in the layers.map), while LayerGroups group together atomic Layers or other LayerGroups.

6.2.2. Layers Options

As seen before, the Layer object maps directly to a layer in the mapfile. By default, all layers in the mapfile are made available as a Layer in the layers.ini, with an identifier having the same name as the name of the mapserver layer. Thus, if you have the following option in your mapfile:

LAYER
  NAME "my_layer"
  TYPE line 
END

This is equivalent as writing the following configuration in the layers.ini:

layers.my_layer.class = Layer 
layers.my_layer.label = my_layer
layers.my_layer.msLayer = my_layer

Tip

If you don't need special parameters (see below) for your layer then you can avoid adding it in the layers.ini

However, if you want these layers to appear in the layer list, you still have the responsibility to affect them a parent layer, using the children property of the LayerGroup layer declarations.

Here is the syntax for the various configuration parameters of a Layer.

  • layers.layerId.className = Layer : defines the object as a Layer; layerId is a string that uniquely identifies the object. The general rules of syntax for a .ini file must be respected in the choice of the layerId (e.g. no '-' are allowed).
  • layers.layerId.msLayer = string : name of the corresponding Mapserver layer in the mapfile
  • layers.layerId.label = string : caption of the layer in the layer tree on the client; this is a 'raw' label, before any internationalization. The i18n scripts automatically include this label in the strings that can be translated.
  • layers.layerId.icon = filename : filename of the static picto that illustrates this Layer in the layer tree. The path is relative to layers.ini. See also Section 6.4, “Layers Legends” for a description of the automatic legending process.
  • layers.layerId.link = url : provides a link for the layer (e.g. to some metadata); makes the caption in the tree clickable.

6.2.3. LayerGroups Options

Here is the syntax for the various configuration parameters of LayerGroups. Note that a special LayerGroup with layerId=root must be present. Unsurprisingly, it is the root (top level) of the hierarchy. It doesn't appear in the visible tree.

  • layers.layerId.className = LayerGroup : defines the object as a LayerGroup; layerId is a string that uniquely identifies the object. The general rules of syntax for a .ini file must be respected in the choice of the layerId (e.g. no '-' are allowed).
  • layers.layerId.children = list of layerIds : comma-separated list of layerIds; these children may be Layers or other LayerGroups.
  • layers.layerId.aggregate = true|false : if true, the children objects are not listed in the tree and not individually selectable. Default is false.
  • layers.layerId.label = string : caption of the layer in the layer tree on the client; this is a 'raw' label, before any internationalization. The i18n scripts automatically include this label in the strings that can be translated.
  • layers.layerId.icon = filename : filename of the static picto that illustrates this Layer in the layer tree. The path is relative to myMap.ini.See also Section 6.4, “Layers Legends” for a description of the automatic legending process.
  • layers.layerId.link = url : provides a link for the layer (e.g. to some metadata); makes the caption in the tree clickable.
  • layers.layerId.rendering = tree|block|radio|dropdown : indicates how to display the LayerGroup children.
    • tree (default value): children layers are rendered below the LayerGroup with an indentation. If children are not declared as "frozen" or "hidden" they will be preceded by a checkbox input. A node folding/unfolding link is displayed before the LayerGroup.
    • radio: quite similar to the "tree" rendering with "radio" buttons replacing checkboxes. Only one child layer can be selected at a time.
    • block: children layers are separated as blocks (separation medium depends on the template layout). Note that the rendering will be applied to the children, not to the LayerGroup itself, which is not displayed at all.
    • dropdown: as for block rendering, the LayerGroup is not displayed. Its children are simply rendered as an HTML "simple select" options list. If the selected child layer cannot be determined using posted or session-saved data, first child (according to the layers.layerId.children list order) is selected. If any, only the selected child layer's own children are displayed under the dropdown list.

6.3. Metadata in Mapfile and layers.ini

Metadata are (keyword, value) pairs which can be associated to a MapServer layer in the mapfile, or to a Layer or LayerGroup in the layers.ini configuration file. These metadata are used in several different contextes, such as layer specific configuration, security handling, ... The metadata related to the functionalities of CartoWeb are described in the documentation of the corresponding plugins.

6.3.1. Metadata in Mapfiles

Specifying metadata in mapfiles is based on the standard MapServer syntax. For instance:

LAYER
  NAME "my_layer"
  [...]
  METADATA
    "exported_values" "security_view,security_edit"
    "security_view" "admin" 
    "security_edit" "admin,editors"
    
    "id_attribute_string" "FID|string" 
    "mask_transparency" "50"
    "mask_color" "255, 255, 0"
    "area_fixed_value" "10"
  END
  [...]
END

The metadata key exported_values is a bit special: It gives the list of metadata keys (coma separated), which will be transmitted to the client. This is required for the metadata keys describing layer security for instance, as they are used on the CartoClient.

6.3.2. Metadata in layers.ini

The configuration file layers.ini may also contain metadata (key, value) pairs. This is needed for LayerGroup objects, as these have no counterparts in the mapfile. For simple layers, the metadata specified in the layers.ini take precedence over the values from the mapfile.

For each layer object in the layers.ini file, the following syntax is used to set metadata:

  • layers.layerId.metadata.METADATA = value

For instance:

layers.group_admin.className = LayerGroup 
layers.group_admin.children = grid_defaulthilight 
layers.group_admin.metadata.security_view = admin

6.4. Layers Legends

CartoWeb includes a mechanism for the automatic generation of legends. If desired, an icon is drawn for each class of the layers. There are two conditions that must be fulfilled to make it work :

1. The mechanism must be enabled by setting

autoClassLegend = true

in layers.ini.

2. Each class (or more precisely each class that should appear in the legend) must have a name. Here an example :

LAYER
  NAME "spur_spurweite"
  METADATA
  ...
  END
  TYPE line
  ...

  CLASS
    NAME "Normalspur (1435 mm)"
    EXPRESSION ([MM] = 1435)
    STYLE
      COLOR 0 0 255 # blue
    END
  END

  CLASS
#   NAME "Meterspur (1000 mm)"
    EXPRESSION ([MM] = 1000)
    STYLE
      COLOR 255 0 0 # red
    END
  END

  CLASS
    NAME "Schmalspur (< 900 mm)"
    EXPRESSION ([MM] < 900)
    STYLE
      COLOR 128 0 128 # lila
    END
  END

END

In this case, the second class would not appear in the legend, because the NAME is commented out.

Provided that no static icon is defined for a layer in layers.ini, the icon of the first visible class is used for the layer.