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.

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

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.

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.

Children switching is useful to define several lists of children for one layer group. The children that will be displayed is choosen by a special parameter : the switch ID.

Switch IDs and labels are listed in file layers.ini. In default test environment, a dropdown is constructed using this list and displayed in the GUI.

switches.switch1.label = Switch 1
switches.switch2.label = Switch 2
switches.switch3.label = Switch 3

Then, each layer group that needs to change its children depending on the switch ID may add this ID as a suffix to the children option.

layers.layerId.className = LayerGroup
layers.layerId.children.switch1 = layer1, layer3
layers.layerId.children.switch2 = layer2, layer3
layers.layerId.children.switch3 =

Special suffix default can be used to define a default children list :

layers.layerId.className = LayerGroup
layers.layerId.children.switch2 = layer2, layer3
layers.layerId.children.default =

The following layer group definitions are equivalent :

layers.layerId.className = LayerGroup
layers.layerId.children.default = layer4

layers.layerId.className = LayerGroup
layers.layerId.children = layer4

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

LAYER
  NAME "my_layer"
  [...]
  METADATA
    "exported_values" "security_view,some_specific_parameter"
    "security_view" "admin" 
    "some_specific_parameter" "value"
    
    "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.

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

Metadata declared in mapfiles or layers.ini can be used in the layers.tpl Smarty templates using the following notation:

{capture name=caption}
{$element.layerLabel} <a
href="/?lang={$element.layerMeta.lang}&client_id={$element.layerMeta.client_id}">
{element.layerMeta.complex_label}</a>
{/capture}

As we can see in the previous example, metadata values can be used through the layerMeta property of the $element Smarty variable. Typical usage of this feature is to render for instance several HTML links for each layers.

First, you have to declare the list of auto layers indexes. Indexes will be used as suffixes for generated layers :

autoLayersIndexes = index1, index2

Then you can use auto layers just as other layers. In this exemple, an auto layer myAutoLayer_ was declared in the mapfile template (see Section 6.6.2, “Mapfile Templates”).

layers.layer1.className = LayerGroup
layers.layer1.children = layer2, myAutoLayer_index1

layers.layer2.className = LayerGroup
layers.layer2.children = myAutoLayer_index2 

Mapfile templates for auto layers are PHP files. The main template must be called mapId.map.php. If this file exists, then CartoWeb assumes that auto layers generation is used. If the file does not exists, CartoWeb looks for a standard mapId.map.

The following functions are predefined and can be used in mapfile templates :

Here is an example :

MAP
  NAME "MyMapfile"
  EXTENT -10 -10 10 10
# ...

<?php

printLayer('myAutoLayer_', 

<<<AUTOLAYER

  # This is my auto layer with index <?php printIndex(); ?>
  LAYER
    NAME <?php printName(); ?>
    TYPE POLYGON
# ...
    CLASS
      NAME "MyClass"
      STYLE
        COLOR <?php if(getIndex() == 'index2') print "200 200 255";
                                          else print "255 153 102"; ?>
      END
    END
  END
AUTOLAYER
);

?>

END 

Script makemaps.php located in directory scripts generates mapfiles out of mapfile templates for all projects. Mapfiles are generated in the same directory. The script must be called once during installation and then each time a change is made to the mapfile templates.

It uses filelayers.ini to find out which auto layers are needed. For instance, with the following layers.ini, myAutoLayer_index3 won't be generated.

autoLayersIndexes = index1, index2, index3
      
layers.layer1.className = LayerGroup
layers.layer1.children = layer2, myAutoLayer_index1

layers.layer2.className = LayerGroup
layers.layer2.children = myAutoLayer_index2 

At least one file is generated. Its name is auto.mapId.all.map and it contains all auto layers used in file layers.ini. When children switching is used (see Section 6.2.4, “Children Switching”), one mapfile is generated per switch. One more is generated for special switch default. This way, only auto layers used with the current switch are actually loaded at runtime. Mapfile auto.mapId.all.map is still generated.

In the following example, 4 mapfiles are generated :

autoLayersIndexes = index1, index2, index3, index4
      
switches.switch1.label = Switch 1
switches.switch2.label = Switch 2

layers.layer1.className = LayerGroup
layers.layer1.children.switch1 = layer2, myAutoLayer_index1
layers.layer1.children.default = layer2, myAutoLayer_index2

layers.layer2.className = LayerGroup
layers.layer2.children = myAutoLayer_index4 

To activate the plugin, add it to loadPlugins from Both CartoClient and CartoServer configuration files: client_conf/client.ini and server_conf/<mapId>/<mapId>.ini. For instance:

loadPlugins = layerReorder

If you want to exclude some layers and then not allow them to be reordered, have a look on client_conf/layerReorder.ini. You will be able to exclude some layers and to choose to keep them on bottom (or on top). To do so, use the following configuration parameters:

You could also add a transparency selector on each layer displayed with this plugin. End user will so be able to choose a different transparency level for each displayed layer.

To activate it, set enableTransparency to true in client_conf/layerReorder.ini.

Default transparency selector values are : 10%, 20%, 50%, 75% and 100%. You could also customize transparency values available in this selector, with a comma separated value in transparencyLevels. A transparency value is a integer between 1 to 100 ; with 100 mean an opaque layer as 1 mean a nearly invisible one.