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

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

LAYER
  NAME "my_layer"
  TYPE line 
END

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

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.

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

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

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.