Contents
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