• HowToCreateALayerTree

Create a layer tree

Some definition

LayerGroup: virtual node used to create a hierarchy of layers. They are visible as a junction in the tree (by default).

Layer: a layer element. All layer element in the layers tree must have a counterpart in the mapfile.

The layer tree

The layer tree is defined in the layers.ini configuration file.

Root element

First, create a layer root, this will be the start point of your layer hierarchy. The layer root is a LayerGroup (see definition on top).

layers.root.className = LayerGroup
layers.root.children =  background, human, categ
layers.root.rendering = block

Here we have a layer named root, which is a LayerGroup. It has three children: background, human, categ. the children can be Layer or LayerGroup. Its rendering style is block, hence all its children will be displayed in a block (as this is the root layer, the block is not really noticeable).

Children

Since we assigned three children layer to the root layer, we need to define them.

layers.background.className = LayerGroup
layers.background.label = Background
layers.background.rendering = radio
layers.background.children =  nonelayer_, vector, raster

layers.human.className = LayerGroup
layers.human.children =  towns, transport
layers.human.label = Human activities

layers.categ.className = LayerGroup
layers.categ.children =  hydro, relief
layers.categ.rendering = dropdown
layers.categ.label = Category

Here we defined three LayerGroup: background, human and categ, all children of root. All are LayerGroup, which mean their children will be displayed in a separate block.

Radio type

The background layer is of type radio. It means its children will be displayed with a radio option button in front of them.

There are three children nonelayer_, vector and raster.

layers.vector.className = LayerGroup
layers.vector.children = sea, district
layers.vector.label = Vector
layers.vector.aggregate = true

layers.raster.className = Layer
layers.raster.label = Raster

layers.nonelayer_.className = LayerGroup
layers.nonelayer_.label = msgNone
layers.nonelayer_.children =

Here we have two LayerGroup and one Layer.

The raster layer here will point to the raster layer in the mapfile:

  LAYER
    NAME "raster"
    TYPE RASTER
    DATA "gtopo30_shade.tif"
    METADATA
       "force_imagetype" "jpeg"
    END
  END

In this case, the name of the layer in the layers.ini file is the same as in the .map file. You can use different name, but then you MUST add the parameter msLayer = name_of_the_layer_in_the_mapfile. Ex: layers.raster.msLayer = another_layer_defined_in_the_mapfile (where another_layer_defined_in_the_mapfile is a layer in the mapfile)

Children of Children

Now let see in detail the vector layer. It has two children: sea and district. It has a label, which is its name as it appear in the layer tree on screen. Its children are aggregate, meaning they are all displayed as one element in the tree.

You can aggregate as many Layer and LayerGroup as you want. It is usefull when you want to display several layers at once and all together.

The nonelayer_ here is a bit special. It is a LayerGroup but it has no children. In fact we have here a fake layer. We know that the vector, raster and nonelayer_ are displayed as radiobutton options. Since you cant unselect a radiobutton, the nonelayer_ option will be used to allow the user to select none of the layers.

As vector had children, we must define them:

layers.district.className = Layer
layers.district.msLayer = district
layers.district.label = district

layers.sea.className = Layer
layers.sea.msLayer = sea
layers.sea.label = sea

Notice here the references to layers in the mapfile: district and sea. In this case, since the name are identical, the msLayer parameter is optional.

Now lets see the human layer.

layers.human.className = LayerGroup
layers.human.children =  towns, transport
layers.human.label = Human activities

layers.towns.className = LayerGroup
layers.towns.label = Towns
layers.towns.children = town, agglo
layers.towns.aggregate = true
layers.towns.metadata.maxScale = 1450000

layers.town.className = Layer
layers.town.msLayer = town
layers.town.label = Towns

layers.agglo.className = Layer
layers.agglo.msLayer = agglo
layers.agglo.label = Agglomerations

[ ... here the definition of the layers ''transport'' and all its children ]

Scale limitation

We notice here something new, in the towns layer: .metadata.maxScale = 1450000. This is used to specify that this LayerGroup has a scale limitation (it is only displayed above or below a certain scale) hence we must use a special icone in the layer tree to notify the user he cant see the layers element at his current scale.

Scale limitation for Layer (defined in the mapfile) are automatic and do NOT require a metadata attribute. Scale limitation for LayerGroup require a metadata attribute.

Metadata

The .metadata parameter can also be used to pass other information to the layer tree generation, ex:

layers.exemplelayer.metadata.fileIdentifier = someSpecialValue

Here we have a metadata parameter fileIdentifier which we will be able to use in the layers.tpl:

{$smarty.capture.inputElt}{$smarty.capture.icon}{$smarty.capture.metalink}{$smarty.capture.caption}

which call for a capture function metalink:

{capture name=metalink}
{ if $element.layerMeta.fileIdentifier}
<a href="http://someURL/someFile.php?fileIdentifier={$element.layerMeta.fileIdentifier}" target="_blank"
title="{t}metadata{/t} {$element.layerLabel}">
<img src="{r type=gfx plugin=layers}someSpecialImage.png{/r}" alt="info" class="pic"></a>
{/if}
{/capture}

Here we access the meta with the keyword layerMeta followed by the meta name: fileIdentifier. This will allow us to add a special link (with an image) to a layer. All layer with the fileIdentifier meta will have this link displayed in the layer tree. You can specify several meta for a layer.

DropDown type

The third main layer groupe is categ. THis layer rendering is set to dropdown, its children will be rendered as options in a dropdown menu.

layers.hydro.className = LayerGroup
layers.hydro.children =  iceland, river, lake_
layers.hydro.label = Hydrology

layers.relief.className = LayerGroup
layers.relief.children =  mountain, iceland, contour
layers.relief.label = Relief

[ ... here the definition of the layers ''iceland'', ''river'', ''lake_'', ''mountain'', ''iceland'', ''contour'' and all their children ]

For more details about the layers parameters, see http://www.cartoweb.org/doc_head/docbook/xhtml/user.layers.html