<dvt:thematicMap>

The thematic map is used for displaying data that is associated with a geographic location. One of the primary uses of this component is to show trends or patterns in data with a spatial element to it. The thematic map does this by using the data to sylize a region (e.g. assigning fill color based on data values), associating a marker with the region, or both.

The thematic map was designed to portray data cleanly so that inherent spatial patterns and trends can be easily seen. Because of this goal, the thematic map doesn't include geographic or political features such as rivers or roads because those would only add visual clutter. If these features are required, then using the <dvt:map> tag would be better suited to your application.

Basemaps

The different maps the thematic map displays are called basemaps. The thematic map comes pre-shipped with a number of basemaps, including a USA basemap, a world basemap, as well as basemaps for continents and regions of the world such as EMEA and APAC. Since the basemaps come pre-shipped, the thematic map does not need a map service to serve up maps for it to display. Use the <dvt:thematicMap> tag's "basemap" attribute to set which basemap is shown.

Each basemap has multiple layers, with each layer representing a set of regions at different levels in the spatial hierarchy. For example, in the USA basemap, there are three layers. There is a layer that shows the national border, a layer that shows all the states, and a third layer that shows all the counties in the USA. Use the <dvt:areaLayer> tag to set which basemap layers are shown.

In addition to layers for different geographic regions, each basemap also has a layer of built-in cities. If you want to use other points that are not included in the set of built-in cities, they can be specified by providing latitude and longitude coordinates (see the <dvt:pointLocation> tag for more details).

The <dvt:areaDataLayer> tag follows the stamping model to stylize each region in its given layer. Insert the <dvt:areaLocation> tag as a child to <dvt:areaDataLayer> to specify which column in the data control specifies the name of the spatial region with which the data is associated. Insert a <dvt:area> tag as a child to the <dvt:areaLocation> tag to sylize a region (e.g. assigning fill color based on data values) and insert a <dvt:marker> tag to associate a marker with the region. Conceptually, the tag structure would look as follows:

Data Model

Attribute Groups

The thematic map supports the use of the <dvt:attributeGroups> tag for generating stylistic attribute values such as colors or shapes for stamps based on categorical bucketing of the data set. Given the column in the model to group by, the attributeGroups can produce style values for each unique value ("group") in the data. The thematic map currently supports <dvt:attributeGroups> as a child of <dvt:marker> and <dvt:area>.

Legend

The legend is a component which is used to display multiple sections of marker and label pairs. Define the legend as a child of the thematic map component. For more detail, please refer to the <dvt:legend> tag doc and examples below.

Example 1: Marker

To include a marker or area as an item in the legend, point the "source" attribute of a legendSection to the id of the marker or area component. Add <f:attribute> as shown below to annotate the marker with a label to be used in the legend.

Example 2: Attribute Groups

To select a particular set of attribute types (color, shape, etc.) to include in the legend as a separate section, point the "source" attribute of a legendSection to the id of the desired attributeGroups component. Use the "label" attribute on attributeGroups as shown below to annotate this set of attributes with a label to be used in the legend.

Selection

Drilling

The thematic map component supports drilling on areas. Drilling is essentially revealing data directly underneath the area being drilled. An area has to be selected before being drilled. This can be achieved by setting the selectionMode property on the areaDataLayer or pointDataLayer. For details, please refer to the <dvt:areaDataLayer> and <dvt:pointDataLayer> tag docs. Below shows an example where the user drills down on Texas:

Supported child tags

Geometry Management

This component can be stretched by a parent layout component that stretches its children, e.g. panelStretchLayout, panelSplitter

This component does stretch to fill up the browser's viewport when it is the "sole visual root component" in the component tree.

When NOT stretched, this component will be displayed in its default dimensions which are provided by the skin. This can be modified by applying a dimension using the inlineStyle or styleClass attributes.

Events

Type

Phases

Description

org.apache.myfaces.trinidad.event.AttributeChangeEvent

Invoke Application,
Apply Request Values

Event delivered to describe an attribute change. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change event might include the width of a column that supported client-side resizing.

Attributes

Name

Type

Supports EL?

Description

animationDuration

int

Yes

Specifies the animation duration in milliseconds. The default value is 1000.

Specifies the type of animation to apply when the value of the basemap changes. Valid values are:

none

alphaFade

conveyorFromLeft

conveyorFromRight

cubeToLeft

cubeToRight

flipLeft

flipRight

slideToLeft

slideToRight

transitionToLeft

transitionToRight

zoom

attributeChangeListener

javax.el.MethodExpression

Only EL

a method reference to an attribute change listener. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change events might include the width of a column that supported client-side resizing.

basemap

String

Yes

Specifies the basemap shown by the thematic map. Valid values are:

"usa"

"world"

"africa"

"asia"

"australia"

"europe"

"northAmerica"

"southAmerica"

"apac"

"emea"

"latinAmerica"

"usaAndCanada"

"worldRegions"

binding

String

Only EL

Binding reference to store the UIThematicMap component

controlPanelBehavior

String

Yes

Valid Values: initCollapsed, initExpanded, hidden

Specifies the behavior of the control panel. Valid values are:

"initCollapsed" - initially collapsed

"initExpanded" - initially expanded

"hidden" - hidden from view

drillBehavior

String

Yes

Valid Values: none, zoomToFit

Specifies additional effect for drilling

"none" - no effect. This is the default.

"zoomToFit" - zoom to fit the drilled region

drilling

String

Yes

Valid Values: off, on

Specifies whether drilling should be on or off for this thematic map. The default value is off

featuresOff

java.util.Set

Yes

a list of default features to turn off for the thematicMap. Currently the supported values are "pan", "zoom", "zoomToFit".

id

String

Yes

the identifier for the component

inlineStyle

String

Yes

The inline style of the thematic map's outer DOM element.

maintainDrill

boolean

Yes

Specifies whether to maintain previously drilled area in the same layer when a new area is drilled. The default value is false

partialTriggers

String[]

Yes

the IDs of the components that should trigger a partial update. This component will listen on the trigger components. If one of the trigger components receives an event that will cause it to update in some way, this component will request to be updated too.

rendered

boolean

Yes

Specifies whether the component is rendered. The default value is true.

styleClass

String

Yes

Sets a CSS style class to use for this component.

summary

String

Yes

Sets a summary of this thematic map's purpose and structure for user agents rendering to non-visual media (e.g. screen readers).