It is possible to arrange the table of contents that appears on the client by setting up a TOC model.
This model allows you to categorize and organize the layers that are available from a map engine.
For historical reasons all top level toc models, i.e. those that are directly included in a client config, should start their id with toc., e.g.<toc:model id='toc.main'>
rather than<toc:model id='main.toc'>
Nesting Update
A recent update to the toc model, since release 2.4.10, allows a toc model to be directly included within another toc model.
Previously it was only possible to include another toc model within a group in a toc model.
For example, a previous nested toc model would look like this:
<toc:model id="subtoc"> <mapengine>default</mapengine> <entry id="layer1" label="Layer 1" layer="layer1"/> </toc:model> <toc:model id="toc.main"> <mapengine>default</mapengine> <entry id="group1" label="Group 1" toc="subtoc"/> <entry id="layer2" label="Layer 2" layer="layer2"/> </toc:model>
which would result in a toc like:
+Group 1 Layer 1 Layer 2
The following is now possible:
<toc:model id="subtoc"> <!-- same as previous example --> <mapengine>default</mapengine> <entry id="layer1" label="Layer 1" layer="layer1"/> </toc:model> <toc:model id="toc.main"> <mapengine>default</mapengine> <entry id="subtoc1" toc="subtoc"/> <!-- note no label set --> <entry id="layer2" label="Layer 2" layer="layer2"/> </toc:model>
which would result in a toc like:
Layer 1 Layer 2
The original structure can now also be accomplished like this:
<toc:model id="subtoc">
<mapengine>default</mapengine>
<entry label="Group 1">
<entry id="layer1" label="Layer 1" layer="layer1"/>
</entry>
</toc:model>
<toc:model id="toc.main"> <!-- same as previous example -->
<mapengine>default</mapengine>
<entry id="subtoc1" toc="subtoc"/>
<entry id="layer2" label="Layer 2" layer="layer2"/>
</toc:model>
Virtual Layers
There can be special virtual layers added to a map engine by additional bundles that provide extra functionality (e.g. an acetate layer or selection drawing), and these layers need to be taken into consideration when creating a table of contents for a map. Virtual layers will be covered later in this document.
Lockable layers
You just need to create a duplicate of the layer with the word UNLOCKED at the start. For example, if you have a layer called property in the mxd, arcims or wms you would create another called UNLOCKEDproperty. There is no need to add the unlocked layer to the toc mode. When the user right clicks the layer, Weave checks to see if this layer is available in the mapengine. Iif it is, the Unlock Layer menu item will be enabled.
You can add it to the toc view contextmenu with the following.
<view id='com.cohga.html.client.map.tocView'> <label>Layers</label> <location>west</location> <contextmenu> <item action="weave.toc.lockLayer" text="Lock Layer"/> </contextmenu> </view>
Namespace
urn:com.cohga.server.map.toc#1.0
Tags
model
Properties
Name | Type | Required | Description |
id | string | yes | unique identifier, should start with 'toc.' for top level toc models |
mapengine | ref urn:com.cohga.server.map.toc#1.0:mapengine | no | The default map engine to associate with the entries included in this toc model if they don't set their own map engine. This value is not required if the this toc model only includes other toc models, it is required if the toc model includes layers or groups that don't set their own map engine |
Sub-tags
Name | Type | Cardinality |
entry | urn:com.cohga.server.map.toc#1.0:entry | 1..n |
Content
None
entry
Properties (for a 'layer')
Name | Type | Required | Description |
id | string | no | Not "required" but you should set it. It uniquely identifies an entry when saving a toc model, for example in a bookmark, which make your life a lot easier if you ever want to re-arrange or rename your map layers, otherwise Weave has to guess and it will not always guess correctly. Set it to a unique value for every entry, doesn't matter what the value is, just make it unique across all toc model entries (a combination of map engine id and layer name would work if you have a lot of layers). This value should never be changed once it has been set, or any bookmarks that reference this entry will be invalidated. |
layer | string | yes | The identifier for the layer within the map engine |
label | string | yes | Identifier displayed to the user for the entry |
mapengine | ref urn:com.cohga.server.map.toc#1.0:mapEngine | no | Override the default map engine for this layer |
checked | boolean | no | Determines the entry should be turned on or off by default |
visible | boolean | no | Should the entry be displayed in the TOC at all |
description | string | no | A description to display when the mouse hovers over the layer |
| entity | ref urn:com.cohga.server.entity#1.0:entity | no | The id of an entity that should be associated with this layer, by associating an entity with a layer additional functionality is available. |
| style | string | no | For map engines that support multiple styles for a layer this value can be used to change the default style. Note that adding the |
acl | no | A reference to an ACL to attach to the layer |
Properties (for a 'toc')
Name | Type | Required | Description |
toc | yes | A toc model to include in this one | |
label | string | no | The label for a group to include the toc within, if not set the toc will be included directly within the parent toc model |
acl | no | A reference to an ACL to attach to the toc |
Properties (for a 'group')
Name | Type | Required | Description |
id | string | no | Not "required" but you really should set it, since it uniquely identified an entry when saving a toc model, for example in a bookmark, which make your life a lot easier if you ever want to re-arrange or rename your map layers. Trust me, just set it to a unique value for every entry, doesn't matter what the value is, just make it unique across all toc model entries |
label | string | yes | Identifier displayed to the user for the group |
mapengine | ref urn:com.cohga.server.map.toc#1.0:mapEngine | no | Override the default map engine for this group |
checked | boolean | no | Determines the group should be turned on or off by default |
description | string | no | A description to display when the mouse hovers over the group |
expandable | boolean | no | Will the user be able to expand/collapse the group in the TOC |
expanded | boolean | no | Will the group start out already expanded |
exclusive | boolean | no | Only one item within the group can be checked at a time |
folder | boolean | no | Should the expand/collapse control be hidden for this group |
| entity | ref urn:com.cohga.server.entity#1.0:entity | no | The id of an entity that should be associated with this group, by associating an entity with a group additional functionality is available. |
acl | no | A reference to an ACL to attach to the group |
Sub-tags (for a 'group')
Name | Type | Cardinality |
entry | urn:com.cohga.server.map.toc#1.0:entry | 1..n |
Content
None
Examples
A Simple ToC
<toc:model id="toc.basic">
<mapengine>mapengine.wms</mapengine>
<entry id="g_roads" label="Roads" expandable="false">
<entry id="mainroads" layer="mainroads" label="Main Roads"/>
<entry id="roads" layer="roads" label="Roads"/>
</entry>
<entry id="buildings" layer="buildings" label="Council Buildings" checked="false"/>
<entry id="easements" layer="easement" label="Easements"/>
<entry id="water" label="Water" expandable="true" folder="true">
<entry id="drainage" layer="drainage" label="Drainage" checked="false"/>
<entry id="pipes" label="Pipes" checked="false" expandable="true">
<entry id="waterpipe" layer="water_pipe" label="Water" checked="false"/>
<entry id="sewerpipe" layer="sewer_pipe" label="Sewer" checked="false"/>
</entry>
<entry id="streams" label="Streams" checked="false" expandable="false">
<entry id="hydro" layer="hydro" label="Hydro"/>
<entry id="mainhydro" layer="main_hydo" label="Main Hydro"/>
</entry>
</entry>
<entry id="g_property" label="Property" checked="true" expandable="false">
<entry id="property_dissolve" layer="property_dissolve" label="Property Dissolve"/>
<entry id="property" layer="property" label="Property"/>
</entry>
<entry id="suburb" layer="suburb" label="Suburbs"/>
<entry id="bounds" layer="mccbound" label="Municipal Boundary"/>
</toc:model>
A ToC included in another ToC
<toc:model id="aerial"> <mapengine>raster</mapengine> <entry id="aerial2006" label="2006" layer="aerial2006"/> <entry id="aerial1996" label="1986" layer="aerial1996" checked="false"/> <entry id="aerial1986" label="1966" layer="aerial1986" checked="false"/> </toc:model> <toc:model id="toc.main"> <mapengine>vector</mapengine> <entry id="boundary" label="Boundaries" layer="boundary"/> <entry id="property" label="Properties" layer="property"/> <entry id="aerial_photography" label="Aerial Photography" exclusive="true"> <toc>aerial</toc> <entry> </toc:model>
A selection ToC directly included in another ToC
<toc:model id="selection"> <mapengine>selection</mapengine> <entry id="selections" label="Selection" exclusive="true"> <entry id="selection.active" label="Active" layer="_selection.active"/> <entry id="selection.all" label="All" layer="_selection.all" checked="false"/> <entry id="selection.other" label="Other" checked="false"> <entry id="selection.property" label="Properties" layer="_selection.property"/> <entry id="selection.boundary" label="Boundaries" layer="_selection.boundary"/> <entry> </entry> </toc:model> <toc:model id="toc.main"> <mapengine>vector</mapengine> <entry toc="selection"/> <entry id="boundary" label="Boundaries" layer="boundary" entity="boundary"/> <entry id="property" label="Properties" layer="property" entity="property"/> <entry id="aerial_photography" label="Aerial Photography" exclusive="true" toc="aerial"/> </toc:model>
A ToC with an ACL where one group of users get a 5cm aerial photo layer and everyone else 50cm.
<toc:model id="aerial"> <mapengine>raster</mapengine> <entry id="aerial_5cm" label="Aerial Photo" layer="aerial_5cm" acl="planners"/> <entry id="aerial_50cm" label="Aerial Photo" layer="aerial_50cm" acl="!planners"/> <!-- Note the use of ! to invert the acl --> </toc:model> <toc:model id="toc.main"> <mapengine>vector</mapengine> <entry id="boundary" label="Boundaries" layer="boundary"/> <entry id="property" label="Properties" layer="property"/> <entry id="aerial" toc="aerial"/> </toc:model>
Selection Layers
One group of virtual layers that's almost always available are those representing the users current selections. When selections are enabled in Weave each map engine (unless configured otherwise) gets additional layers added to it, one representing the selection for the active entity, one representing the selection for all entities, and one each representing the current selection for the individual entities.
Because we're looking at a table of contents at the moment I'll assume that you're interested on how to add these layers to a table of contents (as opposed to other ways of having these layers displayed).
And to do this you need to add an entry to your toc model for each of the virtual layers you wish to enable. The virtual layers themselves are given special layer ids and just need to be added like any other layer.
The simplest way to add the selection to the map is to turn on the layer that represents the selection for the active entity, and to do that you would add the following layer definition to your toc model:
<entry id="selection.active" label="Selection" layer="_selection.active"/>
Note that you can also use just "_selection" as an alternative for "_selection.active", and the values used for the labels in these entries is not important and can be set to anything you think appropriate.
The above example will add an entry to the table of contents allowing the user to turn on and off the active selection.
If you wanted to always draw the current selection and not allow the user the option of turning it off the you would use the following:
<entry id="selection.active" label="Selection" layer="_selection.active" checked="true" visible="false"/>
An alternative to displaying just the active selection is to display the selections for every layer (keep in mind this could be slow). And, this is done using the "_selection.all" virtual layer, for example:
<entry id="selection.all" label="Selections" layer="_selection.all"/>
This will draw the selection for the current entity in a more pronounced style and the other entities in a less pronounced style, unless changed in the map engine configuration.
The other virtual selection layers are given a layer id that relates to the entity id that they're associated with, for example to add a selection layer for a 'road' entity you would use:
<entry id="selection.road" label="Road Selection" layer="_selection.road"/>
And this can be applied for as many entities as you wish to appear in the table of contents.
You can use groups in the table of contents to setup a quite complex selection drawing structure, allowing the user to choose between drawing the current selection, drawing all selections or drawing selections for individual entities. This would be done as follows:
<entry label="Selection" exclusive="true"> <entry id="selection.active" layer="_selection.active" label="Active" checked="true"/> <entry id="selection.all" layer="_selection.all" label="All" checked="false"/> <entry id="selection.other" label="Selected" checked="false"> <entry id="selection.property" layer="_selection.properties" label="Properties" checked="false"/> <entry id="selection.road" layer="_selection.roads" label="Roads" checked="false"/> <entry id="selection.suburb" layer="_selection.suburbs" label="Suburbs" checked="false"/> </entry> </entry>
This way the user will have full control over which selections are drawn.