2.3 Add a Table of Contents (ToC)

1 The ToC Model
2 The Map Engine MetaData (memd) command.
3 ToC Model Variations

A table of contents (ToC) is an interactive list of layers that are displayed on an accompanying Weave map, as displayed below .

Figure 2.3.1 Weave client with highlighted Table of Contents (ToC)

All layers displayed on a map do not have to be included in the ToC. Rather, the Weave administrator selectively ‘curates’ the content of the ToC, via the relevant ToC configuration items. That is, the configuration specifies the layers that are to be included on the ToC, and this does not have to include all the layers that the utilised map engines display.

Most commonly the ToC is used to control the visibility of layers on a map; Additionally, though, other configuration operations are available to a layer through the layer's context menu, which is accessed by right clicking a layer name in the ToC.

Figure 2.3.2 Example ToC Context menu

Creation of a ToC requires that a ToC Model configuration item be configured; A ToC Client View (tocView) is then used to reference the Toc Model, and display the configured ToC on the client user interface (UI),

The ToC Model

Generate a ToC Model

Most Weave client applications will use multiple map engines to access required data layers. The previous section, Section 2.2, walked through the process of defining a map engine and specifying the layers that were to be rendered in the map engine’s sourced map image; A total of two map engines were defined as part Section 2.2. A ToC Model is created by using map engines such as these, and the Weave Map Engine MetaData command: memd. This command is run from the Console tool of the Weave Administration Tool, and is explained in detail below .

The memd command is used to generate a “first pass“ ToC Model for a specified map engine. A separate “first pass“ ToC Model is created for each utilised map engine, and a text editor is then used to refine the content of each toc model. Finally, the text editor is then used to combine the ToC Models into a single ToC Model XML element.
An example ToC Model, generated from memd is shown below, for the “vector“ map engine. The id value of the toc::model is an arbitrary string, however it is convention that the ToC model id value start with "toc.".

<toc:model id='toc.main'>
	<mapengine>vector</mapengine>
	<entry id='l_vector_properties' layer='properties' label='Properties'/>
	<entry id='l_vector_drainpipes' layer='drainpipes' label='Drain Pipes'/>
</toc:model>

The above ToC model example will create a ToC that appears as shown below:

The ToC model configuration item (<toc:model id='toc.main'/>) is added to the config.xml, as a top level config element, as shown below (note the addition of the toc namespace).

<config xmlns="urn:com.cohga.server.config#1.0" 
	xmlns:toc="urn:com.cohga.server.map.toc#1.0"  
    ....>
	<spatial:spatialEngine id="opendata"> ... </spatial:spatialEngine>
	<weave:mapengine id="vector"> ...</weave:mapengine>
	<tiled:mapengine id="mapengine.osm"> ... </tiled:mapengine>

	<toc:model id='toc.main'>
		<mapengine>vector</mapengine>
		<entry id='l_vector_properties' layer='properties' label='Properties'/>
		<entry id='l_vector_drainpipes' layer='drainpipes' label='Drain Pipes'/>
    </toc:model>

	<client:config id="WeaveClient">
		<title>Build a Weave Client</title>
		<toolbar> 	... </toolbar>
		<perspective> ... </perspective>
		<statusbar>  ...</statusbar> 
	</client:config>
</config>

Attribute values specified in XML may be enclosed within either single or double quotes. -The above code example, plus numerous others throughout these course notes, use both single and double quotes for specified attribute values. This difference has no effect on the constructed Weave client.

Reference the ToC Model in the mapView.

Once the ToC model is defined, a reference to it must be made within the corresponding map view.
i.e., <toc ref="toc.main" />)
This reference creates a link between the map view’s map and and toc model. The placement of this reference is shown below

<client:config id="WeaveClient">
	<title>Build a Weave Client</title>
	<toolbar> 	... </toolbar>
    <perspective> ... </perspective>
        <layout>  ... </layout>
        <view id="com.cohga.html.client.map.mapView">	
			<location>center</location>
			<label>Melbourne</label>
			....
			....
			<mapEngine id="mapengine.osm"/>
			<mapEngine id="vector"/>
			<toc ref="toc.main" />
			<extents>	...	</extents>
		</view>
	</perspective>
</client:config>

Use the ToC Client View (tocView) to embed the ToC Model on the client UI.

The tocView is a type of Weave view that is used to embed the ToC model on the client user interface (UI), It is used to specify the UI characteristics of the ToC, such as:

Whether the ToC will have a title.
Specified with the <label> element. In Figure 2.3.1, above, “Layers“ is used as the ToC title
Where the ToC will be positioned within the <perspective> element of the <client:config>.
Specified with the <location> element
Whether the ToC view will include a toolbar, status bar or context menu.
Specified with the <toolbar>, <statusbar> and <contextmenu> elements.

An example tocView is included below:

Based on the tocView needing to be embedded in one of the perspective regions, the tocView is included as a child element of the <perspective> element, within the <client:config> element:

tocView has its own namespace:

The Map Engine MetaData (memd) command.

Packaged with Weave is the Weave Administration Tool. This tool is a browser based application that contains tools for interrogating the various components of Weave. The Console Tool is one such available tool. The Console Tool is used to execute the memd command, as illustrated below in Figure 2.3.3.

The ToC Model generated via memd may be copy/pasted from the Console tool into a text editor. Once there, it may then be combined with other Toc models and refined. The tutorial to follow provides a workflow of this approach.

ToC Model Variations

Handling layers from multiple map engines

In most cases layers from multiple map engines will exist in a Weave client map. This is the case in the Tutorial client example, where two layers come from the Weave Map Engine, and the OpenStreetMap layer comes from a Tiled Map Engine. A ToC model is able to accommodate layers from multiple map engines, by using a mapengine attribute as part of each ToC model <entry> element, instead of as an element of the ToC Model. This approach is shown in the below example XML:

- This ToC model will generate a ToC that appears as shown below :

Creating groups of layers in a ToC

It is possible to group layers in a ToC, using an additional <entry> element. The additional <entry> element contains the layers of its group. The resultant ToC appearance would be as follows, allowing the contained layers to be grouped into the defined group, which in this case is called “Vector Layers“

The corresponding XML to create a grouped ToC is given below. Note the label attribute may be any string.

Omitting layers from the ToC.

Layer entries that are omitted from the ToC model will not be included in the display ToC; They will however continue to be drawn on the map display, since they are defined in the <layers> element of the subject map engine. This is a useful feature where the Weave Administrator requires that a subject layer be displayed on the map, however they do not want the visibility of the subject layer to be changed.

For example, the below code snippet will cause the Drain Pipes layer to be removed from the ToC, however the Drain Pipes layer will continue to be displayed on the map.

Layer Ordering in the ToC

The order that layers are listed in the ToC is entirely dependant on the order of the layer <entry> elements in the ToC model. This ToC layer order will have no effect on the order that layers are displayed in the map (this is controlled by map engine layer ordering), rather, it can be used to logically organise available map layers, and group them if desired,

Layer Visibility on the Map

Layers listed in the toc:model will, by default, be visible when the corresponding Weave map loads. This visibility may be changed by including the optional checked attribute in a layer’s entry element. - The checked attribute would be set to false, thus making the subject layer invisible when the ToC first displays.
For example, the following ToC contains 4 layers from the mapengine, "vector"; When the associated map loads all layers will be visible, excepting the trees layer.

The trees layer is made visible at runtime by using the Trees checkbox, as shown in Figure 2.3.5, below.

Setting a layer’s checked attribute in the toc:model will override the visible attribute of the subject layer in the <weave:mapengine> layer XML

The following tutorial provides an example walk through of generating a ToC model from multiple map engines, refining the Toc model XML, and adding the created ToC to the client application using a tocView..