Class ria.legend.LegendControl

A LegendControl is a user interface control containing descriptive information about features appearing on a map. It also provides the means to show and hide individual overlays on a map.

On the highest level a legend consists of zero or more overlay legends, each of them representing an overlay on a map. Each overlay legend contains one or more rows with a swatch image and a descriptive text. Each row corresponds to a unique style of feature appearing on the respective overlay. If an overlay is made up of several child layers, the rows of each layer are grouped accordingly.

In addition to that, each overlay legend also contains a checkbox that can be used to hide or show the corresponding overlay on the map.

The Spatial Server JavaScript API provides special support for OpenLayers maps. Particularly, it recognises layers of the type OpenLayers.Layer.MappingLayer in order to automatically populate a LegendControl with the corresponding data. See ria.legend.LegendMapOrchestrator for more details.

Beyond that, it is possible to use a LegendControl independently of an OpenLayers map, or populate it with arbitrary legend data, in order to annotate other layer types than OpenLayers.Layer.MappingLayer. For this purpose this class exposes several methods and events.

To populate a LegendControl with custom data, use #renderData(data). Refer to ria.legend.LegendService for more details about the supported data structure.

In order to add entries to a legend without having to provide the entire data, listen to the #onPreRenderData(data) event.

And finally, in order to intercept overlay toggle events, listen to #onOverlayToggled(legendEvent).

To style the LegendControl, the following CSS classes are provided:

Class	Purpose
.legendControl	Container of the entire LegendControl
.controlHeader	The header of the LegendControl
.overlayLegend	Each section of the LegendControl that corresponds to an overlay
.overlayLegend.header	The header of an overlay legend
.multipleSwatchLegendItem	A group of swatches logically belonging together (e.g. thematic map, child layer)
.multipleSwatchLegendItem.header	The header of a multi-swatch legend item (e.g. layer name with disclose button).
.multipleSwatchLegendItem.body	The body of a multi-swatch legend item, which contains one or more swatches.
.singleSwatchLegendItem	A legend row, containing a swatch image and a span with the description.

Method Summary
Method Attributes	Method Name and Description
renderData(data) Populates this legend control with the given data.

Event Summary
Event Attributes	Event Name and Description
onLegendControlUpdated() Notifies any listeners that the `LegendControl` has finished rendering the data.
onOverlayToggled(legendEvent) Notifies any listeners that an overlay has been toggled on or off.
onPreRenderData(data) Notifies any listeners that the `LegendControl` is about to render.

Constructor Detail

ria.legend.LegendControl(props, element)

Creates a new LegendControl.

Parameters:
{Object} props: Properties to mix in upon construction
{Element} element: DOM element that will act as a container element for this LegendControl

Method Detail

renderData(data)

Populates this legend control with the given data. The expected data structure is as follows:

legendData := {
    overlayName: overlayData        // An overlayData object as returned
                                    // by LegendService.getLegendData().
                                    // In addition an overlayData object
                                    // can have an isVisible property
                                    // which determines whether the 
                                    // respective check box is rendered
                                    // ticked or unticked.
    ...
}

overlayName := String               // Name of an overlay. This name
                                    // will be included in overlayToggle
                                    // events.

Parameters:
{Object} data: Data to be displayed on the LegendControl.

Event Detail

onLegendControlUpdated()

Notifies any listeners that the LegendControl has finished rendering the data.

onOverlayToggled(legendEvent)

Notifies any listeners that an overlay has been toggled on or off. An ria.legend.LegendEvent object is passed to listeners, which contains information about the overlay name and its visibility state.

Parameters:
{ria.legend.LegendEvent} legendEvent

onPreRenderData(data)

Notifies any listeners that the LegendControl is about to render. Listeners can alter the data before rendering, by adding their own overlays for example.

Parameters:
{Object} data: The JSON data to be rendered by the legend control.