<dvt:mapColorTheme>

mapColorTheme map color theme

The mapColorTheme tag is used within the <dvt:map> tag to provide the ability to associate different regions of a map with different colors. Each color represents a range of data values known as a "bucket", and the color of a region depends on which bucket its data falls into. For example, this tag might be used to identify a range of colors to represent the popularity of a product in different states, where a state gets colored red if the product is not popular and green if the product is very popular.

To use a Color Theme, the developer needs to specify the colors that will be used. This can be done either by defining the min and max color values with the total number of buckets, or by defining a list of discrete colors to use.

Only one color theme can be visible in a map at a given time.

Model

The Color Theme uses an underlying model to abstract the data that gets displayed in the theme. The specific model class is oracle.adf.view.faces.bi.model.GeoMapDataModel . The GeoMapDataModel contains information about the location and data associated with each colored region. The model can be set through the value attribute of the mapColorTheme tag.

Min/Max Colors

A Color Theme can be defined by a gradient of colors over a particular range specified by the minColor and maxColor attributes. In this case the map will divide the data associated with the theme into a number of buckets determined by the bucketCount attribute. It will then calculate the colors, ranging from minColor to maxColor with graduated colors in between, to assign to each bucket.

In the example below, the Color Theme has minColor = #000000, maxColor = #ffffff, and bucketCount = 5, so the colors of the five buckets are: #000000, #444444, #888888, #bbbbbb, and #ffffff.

Discrete Colors

A Color Theme can also be defined by a list of discrete colors set by the attribute. In this case, each bucket is represented by a color explicitely named in the colorList. The colorList can either be a color array or a semicolon-separated string.

In the example below, the theme's colorList is "#ff0000;#00ff00;#0000ff", so the color of the first bucket is #ff0000, the second bucket is #00ff00, and the third bucket is #0000ff.

Connection to Base Map Themes

The base map theme on which this Color Theme layer is based is specified by the themeName attribute. This base map theme determines the geometries of the colored and uncolored regions, and must come from the same data source as the base map.

If you are using Oracle's hosted eLocation services to configure the Map component, the themeName attribute for this tag should be set to one of the following five choices:

MAP_CONTINENTS_NAME

MAP_COUNTIES_NAME

MAP_COUNTRIES_NAME

MAP_STATES_NAME

MAP_STATES_ABBRV

Depending on the base map theme you choose your data model should have the corresponding polygon names. If you choose MAP_STATES_ABBRV then your data model must have state abbreviations for matching the rows with the appropriate polygons.

Legend Customization

By default, the ID of the mapColorTheme is used as the label when that theme is displayed in the legend or in the Theme Selection dialog. However, each mapColorTheme tag has the following attributes that serve as optional labels for the theme:

shortLabel: Specifies a label for the theme when displayed in the map legend

menuLabel: Specifies a label for the theme in the Theme Selection dialog

The labels for each bucket in the legend can also be specified through the legendLabels attribute. This list can either be a string array or a semicolon-separated string.

Selection

The Color Theme supports the ability to select one or more regions on the map using the mapToolbar's rectangle/circle/polygon/point selection tools. When the user defines a selected area on the map, any of the predefined theme regions, colored or uncolored, that fall within the selected area will be highlighted and the selectionListener will be fired.

Relationship with other tags

For number formatting, the use of af:convertNumber is recommended over dvt:numberFormat. If both tags are present, only the af:convertNumber will be used.

Events

Type

Phases

Description

oracle.adf.view.faces.bi.event.MapSelectionEvent

Apply Request Values

MapSelectionEvent is fired when the user finishes selecting a region on the map, or when the user unselects the region. The rectangle tool, circle tool, polygon tool, or point tool can be used to select a region, and right clicking on the map will unselect it

oracle.adf.view.faces.bi.event.MapClickActionEvent

Apply Request Values

MapClickActionEvent is fired when the user left clicks or right clicks on an element of the theme.

Attributes

Name

Type

Supports EL?

Description

id

java.lang.String

no

The id for this component

themeName

java.lang.String

yes

Specifies the predefined theme on which this theme layer is based. The theme must come from the same data source as the base map. The theme is defined in mapbuilder. For detail, please refer to the documentation of mapviewer.

shortLabel

java.lang.String

no

Specifies the label of this theme on the legend. If the attribute is not specified, the id of the theme will be used as the label on the legend.

menuLabel

java.lang.String

no

Specifies the label of this theme on the ThemeSelectionDialog and SelectMenuItem that are displayed from the toolbar. If the attribute is not specified, the id of the theme will be used.

minZoom

int

no

Specifies the minimum zoom scale where this theme will still be visible.

maxZoom

int

no

Specifies the maximum zoom scale where this theme will still be visible.

legendLabels

java.lang.String

no

Specifies the labels for each bucket on the legend. To specify labels for multiple buckets, developers can bind a string array to this attribute or use a semi-colon separated string. For example, if the value of this attribute is "item1;item2;item3", it means that the label in the legend for the first bucket will be "item1", the second bucket will be "item2" and the third bucket will be "item3"

minColor

java.lang.String

no

Specifies the color for the bucket with the smallest value. Valid values are RGB hexadecimal. For example, color="#000000" specifies black color. The default value is #33FF33.
This attribute will be ignored if the user specifies a value for colorList.
The ADF map uses the value of minColor, maxColor and bucketCount to determine the color for each bucket. For example, if minColor = #000000, maxColor = #ffffff and bucketCount = 5, then the color for the four buckets are: #000000, #444444, #888888, #bbbbbb, #ffffff.

maxColor

java.lang.String

no

Specifies the color for the bucket with the largest value. Valid values are RGB hexadecimal. For example, color="#000000" specifies black color. The default value is #FF3333.
This attribute will be ignored if the user specifies a value for colorList.
The ADF map uses the value of minColor, maxColor and bucketCount to determine the color for each bucket. For example, if minColor = #000000, maxColor = #ffffff and bucketCount = 5, then the color for the four buckets are: #000000, #444444, #888888, #bbbbbb, #ffffff.

bucketCount

int

no

Specifies the number of buckets for the colorTheme. The ADF map will automatically divide data into a set of buckets based on the value of this attribute. For example, if the data in the theme has a minum value of 10 and a maximum value of 50, and the value of this attribute is 4, then the range for the four buckets will be: 10-20, 20-30, 30-40 and 40-50.

colorList

java.lang.String

no

Specifies the color for each bucket. To specify colors for multiple buckets, developers can bind a color array to this attribute or use a semi-colon separated string. Color can be specified using RGB hexadecimal. For example, if the value of this attribue is "#ff0000;#00ff00;#0000ff", then the value of the first bucket is red, the second bucket is green and the third bucket is blue.

selectionListener

java.lang.String

no

a method reference to a selection listener Refers to a backing bean method that takes MapSelectionEvent as an argument. The MapSelectionEvent contains the information on the selected region. Sample code:

Specifies the name of a polygon column in a column the underlying table of the theme. This column is used to join with the location column in the mapModel of the value attribute.

clickAction

java.lang.String

no

Refers to a backing bean method that performs navigation processing for the map and returns an outcome String. Or a static outcome String can be specified. The JSF NavigationHandler selects the page to display next by matching the outcome String against the navigation rules in the application configuration resource file. The application writes the Navigation rules.

clickListener

java.lang.String

no

a method reference to a click listener Refers to a backing bean method that takes MapClickActionEvent as an argument. The MapClickActionEvent contains the information on the clicked point. Sample code:

Specifies the behavior when user left clicks on an element of a theme. Valid values for the theme are:

"Action" - An action event will be fired.

"Popup" - A popup will be shown. The content of the popup is defined in the popup facet of the map

"InfoWindow" - An InfoWindow will be shown. The user can further customize the content of the infoWindow through the infoWindowCallback

"None" - Nothing will be done.

rightClickBehavior

java.lang.String

no

Specifies the behavior when user right clicks on an element of a theme. Valid value for the theme are:

"Popup" - A popup will be shown. The content of the popup is defined in the rtPopup facet of the map

"None" - Nothing will be done.

useWindow

boolean

no

Specifies whether processes launched by this command should be launched in a secondary dialog window. 'useWindow' works only in the case of dialogs i.e, if the "action" starts with a "dialog:". Set useWindow to 'false' for the dialog to be opened in the existing window.

windowWidth

int

no

Specifies the width of the window if useWindow is true

windowHeight

int

no

Specifies the height of the window if useWindow is true

infoWindowCallback

java.lang.String

no

Specifies a callback for overriding the default text in the info Window.

rendered

boolean

no

Specifies whether the theme is rendered or not

opacity

int

no

Specifies the opacity of the color of the theme. Valid values are 0 to 100. 0 means the color is totally tranparent while 100 means the color is not transparent. The default value is 40.

scaling

java.lang.String

no

Scaling factor for numbers that are displayed Valid values are:

none - (Default) The number will not be scaled.

thousand - Scales the number to thousands.

million - Scales the number to millions.

billion - Scale the number to billions.

trillion - Scale the number to trillions.

quadrillion - Scale the number to quadrillions.

value

java.lang.String

no

Specifies the data model for theme - have to be an instance of oracle.adf.view.faces.bi.model.GeoMapDataModel