Oracle Fusion Middleware Data Visualization Tools Tag Reference for Oracle ADF Faces
12c (12.2.1.3)

E80087-01

<dvt:mapPointTheme>

mapPointTheme map point theme


The mapPointTheme tag is used within the <dvt:map> tag to render a set of points. The rendering of each point can be specified via custom images, built-in images or by specifying html tags. The Point Theme ensures that each point is displayed at the appropriate location and stylized correctly based on the specified attributes.

The location and data associated with each point is specified in the data model. The Point Theme together with the Point Style Item tags specifies the display of the points.

Model

An instance of oracle.adf.view.faces.bi.model.GeoMapDataModel must be used to specify the data model for the Point Theme.

The GeoMapDataModel is a collection of GeoRowObject instances and contains location information for each point which is stored in a GeoObject instance. Location for a point can be specified in the GeoObject instance in 2 ways:

  1. Via latitude & longitude
  2. Via an address that will be geocoded by the Point Theme. A geocoderURL must be specified in your map configuration.

Refer to the java doc for more information on how to create a data model.

Rendering Points

The Point Theme along with the Point Style Item tag provides various options for specifying the rendering of the points that are in the model.

Type Description & Example

Built-In Images

The Point Theme provides a collection of built-in images including the normal, selected and hover states. Consider the following:

  1. Same image for all data points -- simply set the builtInImage attribute on the Point Theme tag.
  2. Different image based on data value -- add one or more Point Style Item tags and specify the builtInImage attribute on each tag.

In the example below, all the points are shown using the built-in large orange pin rather than the default orange ball.

                    <dvt:map ...map attributes...>
                      <dvt:mapPointTheme id="theme1" value="#{backingBean.geoMapModel}"
                         builtInImage="OrangePinLarge"/> <-- Changes default rendering of all points -->
                    </dvt:map>
                    

Custom Images

To specify custom images for all the points in the data model or to display different images based on a data value associated with a point add one or more Point Style Items tags to the Point Theme and specify the appropriate attributes.

HTML

By specifying a value for the customPointCallback attribute HTML representing the point can be returned to the Point Theme for each point in the data model. The Point Theme will render the HTML at the location of the point.

The attribute takes a method expression that taeks a oracle.adf.view.faces.bi.component.geoMap.DataContent object as the argument and returns an instance of oracle.adf.view.faces.bi.component.geoMap.PointContent

In the example below, the mapPointTheme is bound to a method expression, "backingBean.processPointInfo"

                    <dvt:map ...map attributes...>
                      <dvt:mapPointTheme id="theme1" value="#{backingBean.geoMapModel}"
                         customPointCallback="#{backingBean.processPointInfo}" />
                    </dvt:map>
                    

The method for generating the custom HTML content:

                    public PointContent processPointInfo(DataContent dataContent) {
                        String pointHTML = "<div>" + dataContent.getValues()[0] + "</div>";
                        String selectHTML = "<div><b>You are selected</b></div>";
                        String hoverHTML = "<div><b>Mouse over</b></div>";
                        PointContent pContent = new PointContent(pointHTML, selectHTML, hoverHTML);
                        return pContent;
                    }
                    

Interactivity

The Point Theme provides the ability to specify different behaviors when the end user clicks on or hovers over a point on the map.

Action Type Description & Example

Left Click

The leftClickBehavior attribute defines the behavior when the end user left clicks on a point. In the example below, when the user left clicks on a point, a popup dialog will be shown. The popup dialog is defined in the "popup" facet.

                    <dvt:map ...map attributes...>
                      <f:facet name="popup">
                        <af:dialog title="TestPopup" modal="true">
                          <af:panelGroupLayout layout="vertical">
                            <af:image id="photoImage" source="#{popupBean.imageSrc}"/>
                          </af:panelGroupLayout>
                        </af:dialog>
                      </f:facet>
                      <dvt:mapPointTheme id="theme1" value="#{backingBean.geoMapModel}"
                         clickListener="#{popupBean.processClickAction}" 
                         leftClickBehavior="Popup"/>
                    </dvt:map>
                    

Right Click

The rightClickBehavior attribute defines the behavior when the end user right clicks on a point. In the example below, when the user right clicks on a point, a context menu will be shown. The menu is defined in the "rtPopup" facet.

                    <dvt:map ...map attributes...>
                      <f:facet name="rtPopup">
                        <af:menu>
                          <af:commandMenuItem text="menu1"/>
                          <af:commandMenuItem text="menu2"/>
                          <af:commandMenuItem text="menu3"/>
                        </af:menu>
                      </f:facet>
                      <dvt:mapPointTheme 
                         clickListener="#{popupBean.processClickAction}"
                         rightClickBehavior="Popup"/>
                    </dvt:map>
                    

Hover

The hoverBehavior attribute defines the behavior when the end user hovers over a point with the mouse. In the example below, when the user mouses over a point, the info window will be shown.

                    <dvt:map ...map attributes...>
                      <dvt:mapPointTheme 
                         hoverBehavior="InfoWindow" />
                    </dvt:map>
                    

Legend Customization

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

The labels for each point in the legend are determined by the labels that were used to create the GeoMapDataModel for this theme.

Relationship with other tags

The <dvt:mapPointTheme> tag is a child of the <dvt:map> tag

The <dvt:mapPointTheme> tag can have the following children:

Deprecated children:

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 identifier for the component
rendered boolean yes Specifies whether the theme is rendered or not
value java.lang.String yes Specifies the data model for theme - have to be an instance of oracle.adf.view.faces.bi.model.GeoMapDataModel
shortLabel java.lang.String yes 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 yes Specifies the label of this theme on the ThemeSelectionDialog and SelectMenuItem. If the attribute is not specified, the id of the theme will be used.
builtInImage java.lang.String yes

Specifies the built-in images for this point style item. Each built in image has a set of normal images, selected images and hovered images

Built-in image can take the value of shape_color where shape is one of the following:

  • SquareBubble
  • PointerBubble
  • DiagonalSquare
  • Bubble
  • Flag
  • Hexagon
  • SignOne
  • PushPin
  • SignTwo
  • TrafficSignDiagonal
  • TrafficSign
  • 3DCube

whereas color is one of the following:

  • Orange
  • Blue
  • Green
  • Red
  • Purple

For example, it can be Bubble_Orange or SignTwo_Blue. Other than those, built-in image can also be one of the following:

  • OrangePinLarge
  • OrangePinMedium
  • OrangePinSmall
  • Ball_Orange
  • Pin_Large_Orange
  • Pin_Medium_Orange
  • Pin_Small_Orange
overlayText java.lang.String yes Specifies what text will appear over the displayed points. Valid values are: None (Default), RowIndex
overlayStyle java.lang.String yes Attribute for defining the inlineStyle of the overlayText
overlayClass java.lang.String yes Specifies the style class for the overlayText
defaultItemLabel java.lang.String yes Specifies the label of a point style on the legend. If no pointStyleItem is specified, the point theme will show the default point images for all the points in the theme. This attribute let the developers to customize the label of the the points on the legend when no pointStyleItem is specified
animationEffect java.lang.String yes the animationEffect to use for ADS.
Valid values are - Blink (Default), Fade, Blink_And_Fade.
minZoom int yes Specifies the minimum zoom scale where this theme will still be visible.
maxZoom int yes Specifies the maximum zoom scale where this theme will still be visible.
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:
public void processSelection(MapSelectionEvent mapSelectionEvent) {
    Iterator iterator = mapSelectionEvent.getIterator();
        
    while (iterator.hasNext())
    {
        DataContent dt = (DataContent)iterator.next();    
        String selectedLocation = dt.getLocationName();
        System.out.println (selectedLocation);
    }                        
}                
        
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:
        public void processMouseClick(MapClickActionEvent mapClickActionEvent) {
            if (mapClickActionEvent.getDataContent() != null)
            {
                DataContent dt = mapClickActionEvent.getDataContent();
                System.out.println ("Location Name: " + dt.getLocationName());
            }
        
            System.out.println("MouseX " + mapClickActionEvent.getMouseX()); 
            System.out.println("MouseY " + mapClickActionEvent.getMouseY());         
       }
Refers to a backing bean method that takes ClickEvent as argument.
leftClickBehavior java.lang.String yes Specifies the behavior when user left clicks on an element of a theme. Valid value of 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" (Default) - 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 yes Specifies the behavior when user right clicks on an element of a theme. Valid value of theme are:
  • "Popup" - A popup will be shown. The content of the popup is defined in the rtPopup facet of the map
  • "None" (Default) - Nothing will be done.
useWindow boolean yes 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. It is false by default.
windowWidth int yes Specifies the width of the window if useWindow is true. It is -1 by default.
windowHeight int yes Specifies the height of the window if useWindow is true. It is -1 by default.
infoWindowCallback java.lang.String no Specifies a callback for overriding the default text in the info Window.
customPointCallback java.lang.String no Specifies a callback for overriding the point. The value of this attribute should be a method expression that returns a oracle.adf.view.faces.bi.component.geoMap.PointContent and will take a oracle.adf.view.faces.bi.component.geoMap.DataContent as its parameter.
This callback lets developer show custom HTML for each point. The DataContent object contains all the necessary information for developers to determine what to show for a point.
This attribute has a higher priority than the mapPointStyleItem. If this attribute is set, all the mapPointStyleItem tag will be ignored.
customLegendCallback java.lang.String yes Specifies a callback for displaying the legend if developers use customPointCallback for the pointTheme.
hoverBehavior java.lang.String yes Specifies the behavior when user hovers over a point on the pointTheme Valid value of theme are:
  • "None" - Nothing will happen
  • "Tooltip" - A tooltip will be shown
  • "InfoWindow" - An info window will be shown
The default value is None.
scaling java.lang.String yes 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.