33 Creating Databound ADF Data Visualization Components

This chapter describes how to use ADF data controls to create ADF Data Visualization components that visually represent business data. Data visualization components allow you to display and analyze data through a wide variety of graphs, several kinds of gauges, a pivot table and pivot filter bar, geographic and thematic maps with multiple layers of information, several kinds of Gantt charts, and a hierarchy viewer.

This chapter includes the following sections:

33.1 About ADF Data Visualization Components

ADF Data Visualization components provide extensive graphical and tabular capabilities for visually displaying and analyzing business data. Each component needs to be bound to data before it can be rendered since the appearance of the components is dictated by the data that is displayed. This chapter describes how to bind each component to a data source

Both graph and gauge components render graphical representations of data. However, graphs, which support more than 50 types of charts, allow you to evaluate multiple data points on multiple axes in a variety of ways. Many graph types assist in the comparison of results from one group with the results from another group. In contrast, gauges focus on a single data point and examine that point relative to minimum, maximum, and threshold indicators to identify problems.

The pivot table component produces a grid that supports multiple layers of data labels on the row edge or the column edge of the grid. An optional pivot filter bar represents a page edge that filters the available pivot table data. This component also provides the option of automatically generating subtotals and totals for grid data. Pivot tables let you pivot data layers from one edge to another to obtain different views of your data. For example, a pivot table might initially display total sales data for products within regions on the row edge, broken out by years on the column edge. If you pivot region and year at runtime, then you end up with total sales data for products within years, broken out by region. At runtime, end users can click buttons that appear in the inner column labels to sort rows in ascending or descending order.

The geographic map component represents business data spatially, enabling you to superimpose multiple layers, also referred to as themes, of information on a single map. For example, a map of the United States might use a color theme that provides varying color intensity to indicate the popularity of a product within each state, a pie chart theme that shows sales within product category, and a point theme that identifies the exact location of each warehouse. When all three themes are superimposed on the United States map, you can easily evaluate whether there is sufficient inventory to support the popularity level of a product in specific locations. Geographic maps require a connection to an Oracle MapViewer service, and optionally, a geocoder service to display geographical and political detail.

Thematic map components represents business data as patterns in stylized areas or associated markers and does not require a connection to an Oracle MapViewer service. Thematic maps focus on data without the geographic details in a geographic map. The thematic map is packaged with prebuilt base maps including a USA base map, a world base map, and base maps for continents and regions of the world including EMEA and APAC. Each base map includes several sets of regions and one fixed set of cities. A set of regions or cities is referred to as a layer. Each layer can be bound to a data collection and stylized to represent the data with color and pattern fills, or a data marker, or both. At runtime, only one map layer and its associated data can be displayed at a time, unless the thematic map has been enabled for drilling.

There are three types of ADF Gantt chart components: the project Gantt chart (which focuses on project management), the scheduling Gantt chart, and the resource utilization Gantt chart (both of which focus on resource management). Each Gantt chart displays the following regions combined with a splitter:

  • List region content: The left side of the splitter provides a list of tasks (for the project Gantt chart) or a list of resources (for the resource utilization and scheduling Gantt charts). This region can display any number of additional columns of related information, using a tree table model.

  • Chart region content: The right side of the splitter consists of an area in which task progress, resource utilization, or resource progress is graphed over time. The ability of the Gantt chart to zoom in or out on its time axis lets you view management information across the desired time period.

The ADF hierarchy viewer component produces an interactive graphic that displays hierarchical data as a set of linked shapes. The shapes and links correspond to the elements and relationships in the data. For example, a hierarchy viewer component might be used to generate an organizational chart based on employee data. At runtime, end users can pan and zoom the graphic and expand, select, and navigate the management hierarchy that the graphic displays.

Each Data Visualization component needs to be bound to data before it can be rendered since the appearance of the components is dictated by the data that is displayed. This chapter describes how to bind each component to a data source.

The prefix dvt: occurs at the beginning of each data visualization component name indicating that the component belongs to the ADF Data Visualization Tools (DVT) tag library.

33.1.1 End User and Presentation Features

Visually compelling data visualization components enable end users to understand and analyze complex business data. The components are rich in features that provide out-of-the-box interactivity support. For detailed descriptions of the end user and presentation features for each component, see the following:

33.1.2 Data Visualization Components Use Cases and Examples

For detailed descriptions of each data visualization use cases and examples, see the following:

33.1.3 Additional Functionality for Data Visualization Components

You may find it helpful to understand other ADF Faces features before you data bind your data visualization components. Additionally, once you have added a data visualization component to your page, you may find that you need to add functionality such as validation and accessibility. Following are links to other functionality that data visualization components use:

  • Partial page rendering: You may want a DVT component to refresh to show new data based on an action taken on another component on the page. For more information, see the "Rerendering Partial Page Content" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

  • Personalization: Users can change the way the DVT components display at runtime, those values will not be retained once the user leaves the page unless you configure your application to allow user customization. For more information, see the "Allowing User Customization on JSF Pages" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

  • Accessibility: You can make your DVT components accessible. For more information, see the "Developing Accessible ADF Faces Pages" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

  • Skins and styles: You can customize the appearance of DVT components using an ADF skin that you apply to the application or by applying CSS style properties directly using a style-related property (styleClass or inlineStyle). For more information, see the "Customizing the Appearance Using Styles and Skins" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

  • Placeholder data controls: If you know the DVT components on your page will eventually use ADF data binding, but you need to develop the pages before the data controls are ready, then you should consider using placeholder data controls, rather than manually binding the components. Using placeholder data controls will provide the same declarative development experience as using developed data controls. For more information, see Chapter 17, "Designing a Page Using Placeholder Data Controls."

33.2 Creating Databound Graphs

When you create a graph using a data collection inserted from the Data Controls panel, a Component Gallery allows you to choose from a wide number of graph categories, graph types, and layout options. Graph categories group together one or more types of graph. For example, the Bar category includes the following types of graphs:

  • Bar

  • Dual-Y Bar

  • Split Dual-Y Bar

  • Percent

  • Stacked Bar

  • Dual-Y Stacked Bar

  • Split Dual-Y Stack Bar

  • Floating Stacked Bar

Explore the Component Gallery that appears when you create a graph to view available graph categories, types, and descriptions for each one. Figure 33-1 shows the Component Gallery that appears for ADF graphs when you use the Data Controls panel.

Figure 33-1 ADF Graphs Component Gallery from Data Controls Panel

ADF Graphs Component Gallery

Note:

Some graph types require very specific kinds of data. If you bind a graph to a data collection that does not contain sufficient data to display the graph type requested, then the graph is not displayed and a message about insufficient data appears.

You can also create a graph by dragging a graph component from the Component Palette. This approach allows you the option of designing the graph user interface before binding the component to data. A Component Gallery appears to view graph types, descriptions, and quick layout options.

Table 33-1 lists the categories that appear in the Component Gallery for graphs. Each category has one or more graph types associated with it.

Table 33-1 ADF Graph Categories in the Component Gallery

Category Description

Area

Creates a graph in which data is represented as a filled-in area. Use area graphs to show trends over time, such as sales for the last 12 months. Area graphs require at least two groups of data along an axis. The axis is often labeled with time periods such as months.

Bar

Creates a graph in which data is represented as a series of vertical bars. Use to examine trends over time or to compare items at the same time, such as sales for different product divisions in several regions.

Bar (Horizontal)

Creates a graph that displays bars horizontally along the y-axis. Use to provide an orientation that allows you to show trends or compare values.

Bubble

Creates a graph in which data is represented by the location and size of round data markers (bubbles). Use to show correlations among three types of values, especially when you have a number of data items and you want to see the general relationships. For example, use a bubble graph to plot salaries (x-axis), years of experience (y-axis), and productivity (size of bubble) for your work force. Such a graph allows you to examine productivity relative to salary and experience.

Combination

Creates a graph that uses different types of data markers (bars, lines, or areas) to display different kinds of data items. Use to compare bars and lines, bars and areas, lines and areas, or all three.

Funnel

Creates a graph that is a visual representation of data related to steps in a process. The steps appear as vertical slices across a horizontal cylinder. As the actual value for a given step or slice approaches the quota for that slice, the slice fills. Typically a funnel graph requires actual values and target values against a stage value, which might be time. For example, use this component to watch a process (such as a sales pipe line) move towards a target across the stage of the quarters of a fiscal year.

Line

Creates a graph in which data is represented as a line, as a series of data points, or as data points that are connected by a line. Line graphs require data for at least two points for each member in a group. For example, a line graph over months requires at least two months. Typically a line of a specific color is associated with each group of data such as the Americas, Europe, or Asia. Use to compare items over the same time.

Pareto

Creates a graph in which data is represented by bars and a percentage line that indicates the cumulative percentage of bars. Each set of bars identifies different sources of defects, such as the cause of a traffic fatality. The bars are arranged by value, from the largest number to the lowest number of incidents. A pareto graph is always a dual-y graph in which the first y-axis corresponds to values that the bars represent and the second y-axis runs from 0 to 100% and corresponds to the cumulative percentage values. Use the pareto graph to identify and compare the sources of defects.

Pie

Creates a graph in which one group of data is represented as sections of a circle causing the circle to look like a sliced pie. Use to show relationship of parts to a whole such as how much revenue comes from each product line.

Radar

Creates a graph that appears as a circular line graph. Use to show patterns that occur in cycles, such as monthly sales for the last three years.

Scatter/Polar

Creates a graph in which data is represented by the location of data markers. Use to show correlation between two different kinds of data values such as sales and costs for top products. Scatter graphs are especially useful when you want to see general relationships among a number of items.

Sparkchart

Creates a simple, condensed graph that displays trends or variations, often in the column of a table, or inline with text.

Stock

Creates a graph in which data shows the high, low, and closing prices of a stock. Each stock marker displays three separate values.


Figure 33-2 shows the horizontal bar graph that appears in the Hot Items Statistics page of the StoreFrontModule application. This graph displays the quantity of orders for each product so that you can easily identify the items that have been ordered most frequently.

Figure 33-2 Hot Items Statistics Graph

Hot items statistics graph

For information about customizing graphs after the data binding is completed, see the "Using ADF Graph Components" chapter in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.2.1 How to Create a Graph

Graphs are based on data collections. Using data controls in Oracle ADF, JDeveloper makes this a declarative task. You drag and drop a collection from the Data Controls panel onto the JSF page and use a dialog to bind the data collection attributes in the graph.

The attributes in a data collection can be data values or categories of data values. Data values are numbers represented by markers, like bar height, or points in a scatter graph. Categories of data values are members represented as axis labels, or appear as additional properties in a tooltip. The role that an attribute plays in the bindings (either data values, or identifiers) is determined by both its data type (Graph requires numeric data values) and where it gets mapped (e.g., Bars vs. X Axis).

To create a databound graph:

  1. From the Data Controls panel, select a collection.

    For example, to create the bar graph that displays the order count for each product in the Hot Items Statistics page of the StoreFrontModule application, select the ProductOrdersCount collection. Figure 33-3 shows the ProductOrdersCount collection in the Data Controls panel.

    Figure 33-3 Data Collection for Counting Product Orders

    Data collection for counting product orders
  2. Drag the collection onto a JSF page and, from the context menu, choose Graphs to display the Component Gallery.

  3. Select a graph category and a graph type from the Component Gallery and click OK.

    For information about the graph categories and graph types that appear in the Component Gallery, see Table 33-1.

    The name of the dialog and the input field labels that appears depends on the category and type of graph that you select. For example, if you select Bar (Horizontal) as the category and Bar as the type, then the name of the dialog that appears is Create Horizontal Bar Graph and the input field is labeled Bars.

  4. Do the following in the dialog to configure the graph to display data:

    • Drag attributes from the Available list to the Bars or X Axis input fields, depending on where you want the values for the attributes to appear at runtime.

    • In the Attribute Labels table, accept the default value or select a value from the dropdown list in the Label field to specify the label that appears at runtime.

      If an attribute represents data values, then the choices in the Label field determine how that attribute's label is rendered in the graph:

      • Use Attribute Name: Select to render the value as a string using the label from the UIHints for that attribute in the underlying ViewObject. This is the default selection.

      • No Label: Select to render no label. This choice is useful if there is a single metric and you want to provide your own descriptive text on the page to describe the resulting graph.

      • Select Text Resource: Select to open a Select Text Resource dialog to select or add a text resource to use for the label. The text resource is a translatable string from an application resource bundle. If you need help, press F1 or click Help.

      • Expression Builder: Select to open the Expression Builder dialog to create an expression to be executed at runtime for the label. If you need help, press F1 or click Help.

      If the attribute represents a category of data values, then the choices are:

      • Use Attribute Name: Select to render the value as a string using the label from the UIHints for that attribute in the underlying ViewObject. This is the default selection.

      • From the dropdown list, choose an alternate attribute for the label. For example, use Employee Names for labels instead of Employee IDs.

    • If you want to change the display of the data represented in the bars to the Y-Axis, click the Swap Bars with Y-Axis button. This action switches the hidden data layer between the graph series and groups, not a simple manual swap of the bars and y-axis attributes.

    • If you want to change from the default selection of Typed Attributes to Name-Value Pairs to configure how data points are stored in a collection, then click the Change Data Shape button. A dialog appears that presents you with the following options:

      • Typed Attributes

        Each kind of data point in the collection is represented by a different attribute. This option is also valid when there is only a single kind of data point in the graph.

        For example, if you have data points for Estimated Value and Actual Value, then select Typed Attributes only if you have one attribute for the estimated value and a second attribute for the actual value.

      • Name-Value Pairs

        Indicates that there are two or more kinds of data points represented by exactly two attributes; a Name attribute that specifies the kind of data point, and a Value attribute that specifies the data value.

        For example, the Name attribute might have the value EST for a Value attribute that represents an estimated value, or the Name attribute might have a value ACT for a Value attribute that represents an actual value.

    • Select Set the current row for master-detail to use the graph's row selection listener to enable clicks on a bar, slice, or other graph data element to update the data in another ADF component. For more information see Section 33.2.3, "What You May Need to Know About Using a Graph's Row Selection Listener for Master-Detail Processing."

    Figure 33-4 shows the Create Horizontal Bar Graph dialog that generates a graph using data from the ItemsOrdered attribute in the ProductOrdersCount data collection. The ProductName attribute provides labels for the displayed data.

    Figure 33-4 Create Horizontal Bar Graph Dialog for ProductOrdersCount

    Create horizontal bar graph for ProductsOrderCount
  5. Optionally, click the Preview tab to display a live preview of the bar graph and its data. If necessary, go back to the Configuration tab so that you can adjust the bar graph specifications.

  6. Click OK.

After completing the data binding dialog, you can use the Property Inspector to specify settings for the graph attributes and you can also use the child tags associated with the graph tag to customize the graph further.

Note:

Use the emptyText attribute to specify the text to display when there is no data to return in the graph. The default message is No data to display. The attribute accepts HTML for formatting the message and an EL expression that evaluates to the viewable property of the data. If the graph is not viewable (for example, if there are authorization restrictions set against the graph), it displays Access Denied.

33.2.2 What Happens When You Use the Data Controls Panel to Create a Graph

Dropping a graph from the Data Controls panel has the following effect:

  • Creates the bindings for the graph and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

The data binding XML that JDeveloper generates varies depending on the type of graph you select. The XML represents the physical model of the specific graph type you create. Example 33-1 shows the bindings that JDeveloper generated in the page definition file where a horizontal bar graph was created using data from the ItemsOrdered attribute in the ProductOrdersCount data collection.

Example 33-1 Binding XML for an ADF Bar (Horizontal) Graph

<graph IterBinding="ProductOrdersCountIterator" id="ProductOrdersCount"
        xmlns="http://xmlns.oracle.com/adfm/dvt" type="BAR_HORIZ_CLUST">
  <graphDataMap convert="false" leafOnly="true">
    <series>
      <data>
        <item value="ItemsOrdered"/>
      </data>
    </series>
    <groups>
      <item value="ProductName"/>
    </groups>
  </graphDataMap>
</graph>

Example 33-2 shows the code generated for a horizontal bar graph when you drag the ProductOrdersCount data collection onto a JSF page.

Example 33-2 JSF Code for an ADF Bar (Horizontal) Graph

<dvt:horizontalBarGraph id="horizontalBarGraph1"
                        value="#{bindings.ProductOrdersCount.graphModel}"
                        subType="BAR_HORIZ_CLUST"
                        threeDEffect="true"
                        imageHeight="450" imageWidth="500">
  <dvt:background>
    <dvt:specialEffects/>
  </dvt:background>
  <dvt:graphPlotArea/>
  <dvt:seriesSet>
    <dvt:series/>
  </dvt:seriesSet>
  <dvt:o1Axis/>
  <dvt:y1Axis/>
  <dvt:legendArea automaticPlacement="AP_NEVER"
                  position="LAP_BOTTOM"/>
</dvt:horizontalBarGraph>

33.2.3 What You May Need to Know About Using a Graph's Row Selection Listener for Master-Detail Processing

You can use the row selection listener of a graph (which serves as a master view) to enable clicks on a bar, slice, or other graph data element to update the data in another ADF component (which serves as a detail view). For example, a click on a bar that represents sales for a given product in a graph might cause the display of the detailed sales data for that product in a pivot table.

The following requirements must be met to achieve this master-detail processing declaratively:

  1. You must use the same data control to provide data for both views as follows:

    1. Bind the graph as a row set to the parent collection in the data control, for example, DepartmentsView.

    2. Bind the other ADF view (such as a table or pivot table) to the dependent detail collection in the data control, for example EmployeesView.

  2. Select Set the current row for master-detail in the Create <type> Graph dialog to automatically set a value for the clickListener attribute of the graph tag and use the processClick method that is already part of the graph binding.

    For example, if the value attribute of the graph tag is value="#{bindings.myGraph.graphModel}", then the clickListener attribute is set to clickListener="#{bindings.myGraph.graphModel.processClick}".

You do not have to write Java code for handling clicks on data elements in the graph. The processClick event on the graph binding recognizes click events on data component in a graph and performs the necessary processing.

33.2.4 What You May Need to Know About Using Name-Value Pairs

When you configure a graph using data controls, by default the data binding dialog supports typed attributes, where each kind of data point in the collection is represented by a different attribute. For example, if you have data points for the sales and costs of multiple products, use typed attributes only if you have one attribute for the sales data of each product, and a second attribute for the cost of each product in the data collection.

Typed attributes data shape is also valid when there is only a single kind of data point in the graph. Figure 33-5 shows a typed attribute data shape.

Figure 33-5 Typed Attribute Data Shape

typed attributes data shape

You can select Change Data Shape in the data binding dialog to change the dialog to support name-value pairs, where there are two or more kinds of data points represented by exactly two attributes; a Name attribute that specifies the kind of data point, and a Value attribute that specifies the data value. In this case, each dedicated attribute has values that identify each kind of data point. For example, the Metrics attribute might have values for Sales and Costs for each product in a data collection. Figure 33-6 shows a data collection in a name-value pairs data shape.

Figure 33-6 Name-Value Pairs Data Shape

name-value pairs data shape

When using a name-value pairs data shape, specify these values in the graph data binding dialog:

  • Name Attribute: the attribute in the data collection representing the Name attribute, when its unique values categorize data points into different metrics.

  • Value Attribute: the attribute in the data collection representing the numeric data points plotted on the graph. Each data point is categorized as belonging to a particular metric by the corresponding Name attribute value.

  • Specify the values for the Value attribute in the relevant fields for the graph type as defined in the dialog, for example, Bubble Colors and Bubble Tooptips for a bubble graph. Values can be attributes in the data collection, or data values, representing a unique value of the Name attribute to be used at runtime to categorize data points into specific metrics. You must specify one or more data values, although you are not required to select all the metrics available in the Name attribute.

    You must add one or more data values by selecting Data Value from the field Add dropdown list. Each data value represents a unique value of the Name Attribute to be used at runtime to categorize data points into specific metrics. You are not required to select all the metrics available in the Name Attribute.

    After specifying attributes or data values for the input field, you can right click on any attribute to display a context menu for actions such as Move Right, Move Left, Delete, or Edit Data Value.

For example, you can create a stock graph that displays open, high, low, and close stock values bound to a data collection with a single numeric column of data in a name-value pairs shape as displayed in Figure 33-7.

33.2.5 How to Create a Graph Using Name-Value Pairs

You can create a graph where the data collection is arranged in a name-value pairs data shape. For example, stock values may be arranged in a single numeric column of data with multiple data points and multiple attributes to designate these points as displayed in the data collection in Figure 33-7.

Figure 33-7 Stock Values in Name-Value Pairs Data Shape

stock values in name-value pairs data shape

Before You Begin:

What you may need to know about n-v pairs

To create a graph using a name-value pairs data shape:

  1. From the Data Controls panel, select a collection.

    In the example to create a graph that displays the open, high, low, and close stock values over a week's time, select the collection StockSingleFactColView1. Figure 33-8 shows the StockSingleFactColView1 collection in the Data Controls panel.

    Figure 33-8 Data Collection for Stock Values in Single Column

    Data collection for stock values in single column
  2. Drag the collection onto a JSF page and, from the context menu, choose Graphs to display the Component Gallery.

  3. In the Component Gallery, select the Stock graph category, then the Open-Hi-Lo-Close Candle with Volume graph type, and click OK.

  4. Do the following to change the dialog to support a name-value pairs data shape:

    • Click Change Data Shape.

    • In the Change Chart Data Shape dialog, select Name-Value Pairs, and click OK.

    • If prompted, confirm your selection.

  5. Do the following in the modified dialog to configure the graph to display data:

    • For Name Attribute, select the attribute category Measures from the dropdown list.

    • For Value Attribute, specify the exact Name Attribute values corresponding to the Open, Hi, Lo, and Close data attribute from the dropdown list.

    • In the Chart Values table, accept the default value or select a value from the dropdown list in the Label field to specify the label that appears at runtime.

      If an attribute represents data values, then the choices in the Label field determine how that attribute's label is rendered in the graph:

      • Use Attribute Name: Select to render the value as a string using the label from the UIHints for that attribute in the underlying ViewObject. This is the default selection.

      • No Label: Select to render no label. This choice is useful if there is a single metric and you want to provide your own descriptive text on the page to describe the resulting graph.

      • Select Text Resource: Select to open a Select Text Resource dialog to select or add a text resource to use for the label. The text resource is a translatable string from an application resource bundle. If you need help, press F1 or click Help.

      • Expression Builder: Select to open the Expression Builder dialog to create an expression to be executed at runtime for the label. If you need help, press F1 or click Help.

      If the attribute represents a category of data values, then the choices

      • Use Attribute Name: Select to render the value as a string using the label from the UIHints for that attribute in the underlying ViewObject. This is the default selection.

      • From the dropdown list, choose an alternate attribute for the label. For example, use Employee Names for labels instead of Employee IDs.

    • Set the current row for master-detail: Select to use the graph's row selection listener to enable clicks on a bar, slice, or other graph data element to update the data in another ADF component. For more information see Section 33.2.3, "What You May Need to Know About Using a Graph's Row Selection Listener for Master-Detail Processing."

    Figure 33-9 shows the Create Stock Graph dialog that generates a graph using the attribute in the collection.

    Figure 33-9 Create Stock Graph for StockSingleFactColView1

    Create stock graph for StockSingleFactColView1
  6. Optionally, click the Preview tab to display a live preview of the stock graph and its data. If necessary, go back to the Configuration tab so that you can adjust the stock graph specifications.

  7. Click OK.

33.2.6 How to Create a Databound Spark Chart

Spark charts are simple, condensed graphs that display trends or variations, often in the column of a table, or inline with text. Line, bar, and area spark charts require a single series of data values. Figure 33-10 shows an example of a line spark chart in a table column.

Figure 33-10 Line Spark Chart in Table of Stock Prices

line spark chart in table

Floating bar spark charts require two series of data values, one for the float offset, and one for the bar value. Figure 33-11 shows an example of a floating bar sparkchart.

Figure 33-11 Floating Bar Spark Chart

floating bar spark chart

In a simple UI-first development scenario you can insert a sparkchart using the Component Palette and bind it to data afterwards.

You can provide data to sparkcharts in any of the following ways:

  • Specify data statically in child dvt:sparkItem tags. Example 33-3 shows an example of providing static data to a sparkchart.

    Example 33-3 Static Data in Sparkchart

    <dvt:sparkChart>
      <dvt:sparkItem value="20"/>
      <dvt:sparkItem value="15"/>
      <dvt:sparkItem value="30"/>
    </dvt:sparkChart>
    
  • Specify data using EL Expression in child dvt:sparkItem tags. Example 33-4 shows an example of providing data using EL Expressions.

    Example 33-4 EL Expression Data in Sparkchart

    <af:table value="#{sample.tableModel}" var="row">
      <af:column>
        <dvt:sparkChart>
          <dvt:sparkItem value="#{row.col1}"/>
          <dvt:sparkItem value="#{row.col2}"/>
          <dvt:sparkItem value="#{row.col3}"/>
        </dvt:sparkChart>
      </af:column>
    </af:table>
    
  • Specify data using a child accessor in a table. Example 33-5 shows an example of using af:iterator to provide sparkchart data from the data collection model, row.stockValues.

    Example 33-5 Sparkchart Data in Table Child Accessor

    <af:table value="#{sample.tableModel}" var="row">
      <af:column>
        <dvt:sparkChart>
          <af:iterator value="#{row.stockValues}" var="data">
            <dvt:sparkItem value="#{data.closeValue}"/>
          </af:iterator>
        </dvt:sparkChart>
      </af:column>
    </af:table>
    

You can also create a sparkchart by inserting a data control from the Data Controls Panel. Figure 33-12 shows the Component Gallery that displays when you drag a sparkchart component onto your page from the Data Controls panel.

Figure 33-12 Create Sparkchart Component Gallery

Create sparkchart component gallery.

A binding dialog prompts you to specify the value you wish to display for the selected sparkchart type. Line, bar, and area spark charts require a single series of data values, for example the changing value of a stock. Floating bar sparkcharts require two series of data values, one for the float offset, and one for the bar value. For example, in the Create Floating Stacked Bar Sparkchart dialog you specify:

  • Bar Height: Use to select the data value to use for the bar value.

  • Bar Float: Use to select the data value to use for the float offset, the distance between the axis and the floating bar.

Figure 33-13 shows a completed Create Floating Stacked Bar Sparkchart dialog.

Figure 33-13 Sparkchart Binding Dialog

Sparkchart Binding Dialog

33.3 Creating Databound Gauges

A gauge plots one data point with indication of whether the data point falls in an acceptable or unacceptable range. One databound gauge component can create a single gauge or an entire set of gauges, depending on the number of rows in the data collection used. In a collection, each row contains the values for a single gauge.

The Component Gallery for gauges allows you to choose from the following categories of gauges:

  • Dial: Indicates the metric value of a task along a configurable arc.

  • Status Meter: Indicates the progress of a task or the level of some measurement along a rectangular bar.

  • Status Meter (Vertical): Indicates the progress of a task or the level of some measurement along a rectangular bar.

  • LED: Depicts graphically a measurement such as a key performance indicator (KPI). Several styles of graphics are available for LED gauges such as arrows that indicate good (up arrow), fair (left- or right-pointing arrow), and poor (down arrow).

Each of these categories contains a number of different types of gauge. Explore the Component Gallery that appears when you create a gauge to view all available gauge and category types, and descriptions for each one. Figure 33-14 shows the Component Gallery that appears for ADF gauges.

Figure 33-14 ADF Gauges Component Gallery

ADF Gauges Component Gallery

The data binding process is essentially the same regardless of which type of gauge you create. Only the metric value (that is, the measurement that the gauge is to indicate) is required. However, if a row in a data collection contains range information such as maximum, minimum, and thresholds, then these values can be bound to the gauge to provide dynamic settings. If information that you want to use in a gauge's upper or lower labels is available in the data collection, then you can bind these values to the gauge also.

For information about customizing a gauge after the data binding is completed, see the "Using ADF Gauge Components" chapter in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.3.1 How to Create a Databound Dial Gauge

You can use the ADF gauge component to create a dial gauge against a background that specifies ranges of values (also called thresholds) that vary from poor to excellent. The gauge indicator specifies the current value of the metric while the graphic allows you to evaluate the status of that value easily.

Figure 33-15 shows a single dial gauge that appears if you create a gauge from the collection that stores WarrantyPeriodMonths data. Because only one gauge appears, this data collection must contain only a single row of data. The value of the metric (which is 6) appears in a label below the gauge. The range of values in the gauge is displayed as 0 to 24. Threshold ranges are identified at 8, 16, and 24 and are filled with the colors red for poor (below 8), yellow for adequate (from 8 to 16), and green for superior (above 16).

Figure 33-15 The Warranty in Months Dial Gauge

Warranty in months dial gauge

To create a dial gauge using a data control, you bind the gauge component to a collection. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Controls panel.

To create a databound dial gauge:

  1. From the Data Controls panel, select a collection.

    For example, to create a dial gauge in the StoreFrontModule application to display the current warranty period in months for a product in a particular warehouse, you would select the WarehouseStockLevels collection. Figure 33-16 shows the WarehouseStockLevels collection in the Data Controls panel.

    Figure 33-16 Data Collection with Warranty Period for a Product

    Data collection with warranty period for a product
  2. Drag the collection onto a JSF page and, from the context menu, choose Gauges.

  3. In the Component Gallery dialog, choose the category, type of gauge, and quick start layout, and then click OK.

  4. In the Configuration tab of the dialog, do the following:

    • In the Metric box, select the column in your data collection that contains the actual value that the gauge is to plot. This is the only required value in the dialog.

    • In the Minimum box, if your data collection stores a minimum value for the gauge range, select the column that contains this value.

    • In the Maximum box, if your data collection stores a maximum value for the gauge range, select the column that contains this value.

    • In the Top Label box, if your data collection stores a value that you want to display in the top label of the gauge, select the column that contains this value.

    • In the Bottom Label box, if your data collection stores a value that you want to display in the bottom label of the gauge, then select the column that contains this value.

    • In the Threshold Attributes list, if you want to specify threshold values, click the Add icon to insert a row for each threshold and specify the value in that row. Do not create a threshold equal to the maximum value for the gauge because the gauge automatically treats the maximum value as a threshold setting.

    Note:

    Gauge Top, Bottom, and Threshold labels can be configured to specify a text resource from a resource bundle using the Select Text Resource dialog, or use the EL Expression builder to evaluate the label text at runtime. Use the dropdown menu for the label field to open both dialogs.
  5. Optionally, click the Preview tab to display a live preview of the gauge and its data. If necessary, go back to the Configuration tab so that you can adjust the gauge specifications.

  6. Click OK.

You can examine and adjust the gauge bindings for WarehouseStockLevels in the Edit Gauge dialog. Figure 33-17 shows the dialog that appears when you click the Edit icon in the Property Inspector for the gauge component.

Note:

The data source and metric data values are required. Other data values in the dialog are optional and can be specified in the gauge component through the Property Inspector.

Figure 33-17 Edit Gauge Dialog

Edit Gauge Binding dialog

In the Property Inspector, after you complete the binding of the gauge, you can set values for additional attributes in the gauge tag and its child tags to customize the component.

33.3.2 What Happens When You Create a Dial Gauge from a Data Control

Dropping a gauge from the Data Controls panel has the following effect:

  • Creates the bindings for the gauge and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

Example 33-6 shows the bindings that JDeveloper generated for the dial gauge that displays warranty in months for a product in a warehouse. This code example shows that the gauge metric receives its value dynamically from the WarrantyPeriodMonths column in the data collection and that the remaining data values have static settings.

Example 33-6 Bindings for a Dial Gauge

<gauge IterBinding="WarehouseStockLevelsIterator" id="WarehouseStockLevels"
       xmlns="http://xmlns.oracle.com/adfm/dvt">
  <gaugeDataMap>
    <item type="threshold" value="8" valueType="literal"/>
    <item type="threshold" value="16" valueType="literal"/>
    <item type="metric" value="WarrantyPeriodMonths"/>
    <item type="minimum" value="0" valueType="literal"/>
    <item type="maximum" value="24" valueType="literal"/>
    <item type="topLabel"
          value="${adfBundle['view.ViewControllerBundle'].
                 WARRANTY_(MONTHS))" valueType="literal"/>
  </gaugeDataMap>
</gauge>

Example 33-7 shows the code that ­JDeveloper generated in the JSF page for a dial gauge. The <dvt:thresholdSet> element specifies one <dvt:threshold> element for each threshold. Colors for the threshold ranges default to red, yellow, and green as specified by the values for the fillColor attributes. The <dvt:indicator> element specifies IT_NEEDLE as the indicator to use. This renders a needle at runtime. The default value for <dvt:indicator> renders a line (IT_LINE).

Example 33-7 Code on the JSF Page for an ADF Dial Gauge

<dvt:gauge id="gauge1"
           value="#{bindings.WarehouseStockLevels.gaugeModel}"
           gaugeType="DIAL" imageFormat="FLASH">
  <dvt:gaugeBackground>
    <dvt:specialEffects fillType="FT_GRADIENT">
      <dvt:gradientStopStyle/>
    </dvt:specialEffects>
  </dvt:gaugeBackground>
  <dvt:thresholdSet>
    <dvt:threshold text="Low" fillColor="#d62800"/>
    <dvt:threshold text="Medium" fillColor="#ffcf21"/>
    <dvt:threshold text="High" fillColor="#84ae31"/>
  </dvt:thresholdSet>
  <dvt:gaugeFrame/>
  <dvt:indicator type="IT_NEEDLE"/>
  <dvt:indicatorBase/>
  <dvt:gaugePlotArea/>
  <dvt:tickLabel/>
  <dvt:tickMark/>
  <dvt:topLabel/>
  <dvt:bottomLabel/>
  <dvt:metricLabel position="LP_WITH_BOTTOM_LABEL"/>
</dvt:gauge>

33.3.3 How to Create a Databound Status Meter Gauge Set

You can use the ADF gauge component to create a status meter gauge where the inner rectangle shows the current level of a measurement against the ranges marked in the outer rectangle. The graphic of the status meter gauge allows you to evaluate the condition or progress of a measurement easily.

Figure 33-18 shows a set of status meter gauges that represent the inventory levels in a number of warehouses. This set of gauges results from binding one gauge component to a data collection (WarehouseStockLevels). This data collection contains a row of data for each warehouse. Each row produces one gauge in the set. Notice that all gauges in the set share the same range values of minimum (0) and maximum (1500) with thresholds set at 500 and 1000 and 1500. Each gauge in the set displays the name of the warehouse that it represents and the stock metric for that warehouse in its bottom label.

Figure 33-18 The Warehouse Inventory Status Meter Gauge Set

Wharehouse inventory status meter gauge set

To create a status meter gauge set using a data control, you bind the gauge component to a data collection that contains multiple rows of data. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Controls panel.

To create a databound status meter gauge:

  1. From the Data Controls panel, select a collection.

    For example, to create a status meter gauge in the StoreFrontModule application that displays the quantity of stock on hand in a warehouse, you select the WarehouseStockLevels collection.

  2. Drag the collection onto a JSF page and, from the context menu, choose Gauges.

  3. In the Component Gallery, choose the following:

    • Status Meter or Status Meter (Vertical) in the Categories list

    • The type of gauge that you want to create

    • The quick start layout for the gauge at runtime

  4. Click OK.

  5. In the Create Gauge dialog that appears, select values as described in the following list:

    • Select an attribute binding from the Metric dropdown list. This attribute binding contains the actual value that the gauge is to plot.

    • Input a minimum value in the Minimum field if your data collection stores a minimum value for the gauge range.

    • Input a maximum value in the Maximum field if your data collection stores a maximum value for the gauge range.

    • Write or select a value in the Top Label field if you want to display a label on top of the gauge at runtime.

    • Write or select a value in the Bottom Label field if you want to display a label below the gauge at runtime.

    • Click the Add icon to insert a row for each threshold and specify the value for that threshold if you want to specify threshold values in the Threshold Attributes list. Do not create a threshold equal to the maximum value for the gauge because the gauge automatically treats the maximum value as a threshold setting.

    Note:

    Gauge Top, Bottom, and Threshold labels can be configured to specify a text resource from a resource bundle using the Select Text Resource dialog, or use the EL Expression builder to evaluate the label text at runtime. Use the dropdown menu for the label field to open both dialogs.
  6. Optionally, click the Preview tab to display a live preview of the gauge and its data. If necessary, click the Configuration tab so that you can adjust the gauge specifications.

    Figure 33-19 shows the settings for the set of status meter gauges that appears in Figure 33-18. In addition to setting values for the required metric value, this dialog sets values for thresholds and for the name of the warehouse to appear in the gauge's bottom label.

    Figure 33-19 Create Gauge Dialog for Warehouse Inventory Gauge Set

    Gauge binding dialog for warehouse inventory
  7. Click OK.

In the Property Inspector, after you complete the binding of the gauge, you can set values for additional attributes in the gauge tag and its child tags to customize the component as needed.

33.3.4 What Happens When You Create a Status Meter Gauge from a Data Control

Dropping a gauge from the Data Controls panel has the following effect:

  • Creates the bindings for the gauge and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

Example 33-8 shows the row set bindings that were generated for the status meter gauge set that displays inventory levels for each warehouse as illustrated in Figure 33-19. This example shows the value binding created between the gauge metric attribute and the QuantityOnHand value in the data collection. It also shows the value binding between the Bottom Label attribute and the WarehouseName value in the data collection.

Example 33-8 Bindings Code for the ADF Status Meter Gauge Set

<gauge IterBinding="WarehouseStockLevelsIterator" id="WarehouseStockLevels"
        xmlns="http://xmlns.oracle.com/adfm/dvt">
  <gaugeDataMap>
    <item type="threshold" value="500" valueType="literal"/>
    <item type="threshold" value="1000" valueType="literal"/>
    <item type="metric" value="QuantityOnHand"/>
    <item type="minimum" value="0" valueType="literal"/>
    <item type="maximum" value="1500" valueType="literal"/>
    <item type="bottomLabel" value="WarehouseName"/>
  </gaugeDataMap>
</gauge>

Example 33-9 shows the code generated on the JSF page for the status meter gauge set that shows inventory levels for warehouses. The gaugeSetColumnCount attribute specifies that gauges should be displayed in two columns. The code also specifies three thresholds: Low, Medium, and High. For brevity, the value of the inlineStyle attribute has been omitted.

Example 33-9 Code on the JSF Page for the ADF Status Meter Gauge Set

<dvt:gauge id="gauge1"
           value="#{bindings.WarehouseStockLevels.gaugeModel}"
           gaugeType="STATUSMETER" imageFormat="FLASH">
  <dvt:gaugeBackground>
    <dvt:specialEffects fillType="FT_GRADIENT">
      <dvt:gradientStopStyle/>
    </dvt:specialEffects>
  </dvt:gaugeBackground>
  <dvt:thresholdSet>
    <dvt:threshold text="Low" fillColor="#d62800"/>
    <dvt:threshold text="Medium" fillColor="#ffcf21"/>
    <dvt:threshold text="High" fillColor="#84ae31"/>
  </dvt:thresholdSet>
  <dvt:indicatorBar/>
  <dvt:gaugePlotArea/>
  <dvt:tickLabel/>
  <dvt:tickMark/>
  <dvt:topLabel/>
  <dvt:bottomLabel/>
  <dvt:metricLabel position="LP_WITH_BOTTOM_LABEL"/>
</dvt:gauge>

33.4 Creating Databound Pivot Tables

The ADF pivot table displays data in a grid layout with unlimited layers of nested rows and columns. The pivot table supports an optional pivot filter bar, representing a page edge that filters the available pivot table data. The pivot table has the following structure:

  • Column edge: The horizontal axis above the pivot table containing one or more layers of information in the pivot table.

  • Row edge: The vertical axis to the left of the pivot table containing one or more layers of information in the pivot table.

  • Page edge: The optional pivot filter bar containing zero or more layers of information for filtering the display of data in the pivot table.

  • Data body: One or more measures, or data values, displayed in the cells of the pivot table.

Figure 33-20 shows a Sales pivot table that displays data values for sales and units in the data body, a geography data layer on the column edge, and year and product data layers on the row edge. A pivot filter bar displays a channel filter on the page edge.

Figure 33-20 Sales Pivot Table

Sales pivot table by year and product.

The pivot table example aggregates data based on a CSV file of data shown in Figure 33-21.

Figure 33-21 Pivot Table CSV Data

CSV file of data

A Create Pivot Table wizard provides declarative support for data-binding and configuring the pivot table. In the wizard pages you can:

  • Specify the initial layout of the pivot table

  • Associate and configure a pivot filter bar

  • Specify alternative labels for the data layers

  • Configure insert or filter drilling

  • Define aggregation of data values

  • Configure category and data sorting

  • View a live data preview of the pivot table

As you lay out the pivot table in the first page of the wizard, corresponding entries are initialized in the following wizard pages. You can use the Back and Next buttons to adjust the pivot table as you go through the wizard pages. You can also skip configuration options in later wizard pages by clicking Finish.

For information about customizing a pivot table after data binding is completed, see the "Using ADF Pivot Table Components" chapter in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.4.1 How to Create a Pivot Table

To create a pivot table using a data control, you bind the pivot table component to a collection. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Controls panel.

Tip:

You can also create a pivot table by dragging a pivot table component from the Component Palette. This approach allows you the option of designing the pivot table user interface before binding the component to data.

To demonstrate the creation of the sample Sales pivot table shown in Figure 33-20, a placeholder data control was created and data types defined for the CSV file shown in Figure 33-21. For more information, see Section 17.4, "Using Placeholder Data Controls."

To create a databound pivot table:

  1. From the Data Controls panel, select a collection.

    For example, to create a pivot table that displays sales and units sold by year for each product, you could select the ptExampleData defined for the ptExamplePlaceholder collection in the Data Controls panel, as shown in Figure 33-22.

    Figure 33-22 Data Collection for Product Sales by Year

    Data collection for product sales by year.
  2. Drag the data collection onto a JSF page and, from the context menu, choose Tables > ADF Pivot Table.

  3. In the Select Display Attributes page of the Create Pivot Table wizard, specify the initial layout of the pivot table by doing the following:

    1. If you want to associate a pivot filter bar with your pivot table, select Create Pivot Filter Bar. Optionally, you can drag attributes from the Available Attributes list to the page edge to configure the initial display of filters; otherwise, an empty pivot filter bar is created.

      Note:

      You can add or remove a pivot filter bar after completing the wizard by selecting the pivotTable component in the Property Inspector, clicking the Edit icon, and checking or unchecking the Create Pivot Filter Bar option. You can also drag and drop a pivotFilterBar component from the Component Palette adjacent to a pivot table and the bindings will be done for you.
    2. For the initial layout, select the attributes for the pivot table's columns, rows, page edge, and data body by dragging the attributes from the Available Attributes list to the pivot table layout.

      In the pivot table layout, Data Labels refers to a layer of the pivot table that identifies the data in the cells (data values), and that appears as header labels in the row, column, or page edge. Labels for attributes that you drag to the data body of the pivot table appear in the data labels layer.

      You can drag data labels to any location on the row, column, or page edge. You can also drag attributes to different locations on the same edge or on another edge.

      As an alternative to using a drag operation to place or move attributes in the layout, you can right-click the attribute or use Shift+F10 to display a context menu of options. Figure 33-23 shows the context menu options for the Geography attribute.

      Figure 33-23 Display Attributes Context Menu

      Display attributes context menu.

      Note:

      Potential drill paths between attributes are defined as you lay out multiple attributes on the row, column, and page edges. These drill paths can later be enabled to support pivot table drilling at runtime.
    3. If you want to change from the default selection of Typed Attributes to Name-Value Pairs to configure how data points are stored in a collection, then click the Change Data Shape button. A dialog appears that presents you with the following options:

      • Typed Attributes

        Each kind of data point in the collection is represented by a different attribute. This option is also valid when there is only a single kind of data point in the pivot table.

        For example, if you have data points for Estimated Value and Actual Value, then select Typed Attributes only if you have one attribute for the estimated value and a second attribute for the actual value.

      • Name-Value Pairs

        Indicates that there are two or more kinds of data points represented by exactly two attributes; a Name attribute that specifies the kind of data point, and a Value attribute that specifies the data value.

        For example, the Name attribute might have the value EST for a Value attribute that represents an estimated value, or the Name attribute might have a value ACT for a Value attribute that represents an actual value.

    For example, to specify the initial layout of the Sales pivot table shown in Figure 33-20, you would drag the Channel attribute to the page edge, Year and Product attributes to the row edge, Sales and Units attributes to the data body (Data Labels), Geography to the column edge, and select Create Pivot Filter Bar, as shown in Figure 33-24.

    Figure 33-24 Select Display Attributes Page of Create Pivot Table Wizard

    Select display attributes page of wizard.
  4. If you want to specify alternative labels or values for the attributes laid out in the Select Display Attributes page of the wizard, use the Specify Attribute Labels page to do the following:

    1. To specify alternative labels for data values in the Data Values area, change the default Use Data Attribute Name text label stamped in the header cell for the attribute at runtime. You can enter the text directly, select No Label to suppress the header cell as in the case of using a single data value for the pivot table, specify a text resource from a resource bundle, or use the EL Expression builder to evaluate the label text at runtime.

      Note:

      If you configured Project Properties > Resource Bundle page to Automatically Synchronize Bundle, then you can type an alternate label string, and the design time code will create a translatable Text Resource for you.
    2. To specify alternative labels for attribute categories in the Categories area, change the default Use Attribute Name text label stamped in the header cell for the attribute at runtime in the Attribute Display Name column. You can enter the text directly, specify a text resource from a resource bundle, or use the EL Expression builder to evaluate the label text at runtime. The label displays in the pivot handle at runtime.

      Note:

      If you configured Project Properties > Resource Bundle page to Automatically Synchronize Bundle, then you can type an alternate label string, and the design time code will create a translatable Text Resource for you.

      You can also specify an alternative value for an attribute category by selecting a different attribute in the Attribute Display Value column. For example, you might use a ProductId attribute in the data collection to lay out the pivot table, but you want the ProductName attribute values to appear in the pivot table header at runtime to make the information more readable.

    For example, to specify an alternate label for the Year attribute of the Sales pivot table shown in Figure 33-20, you would enter text (Time) in the Attribute Display Name field, as shown in Figure 33-25.

    Figure 33-25 Specify Attribute Labels Page of Create Pivot Table Wizard

    Specify Attributes Labels page of the wizard.
  5. If you want to expose drill operations in the pivot table at runtime, use the Configure Drilling page of the Create Pivot Table wizard to enable one of the following options:

    • Select Insert Drilling to provide a collapsed or expanded view of the detail data while preserving the sibling and aggregate data. At runtime, a drill icon is displayed in the parent attribute display label.

      Use Insert Parent Row to specify whether the aggregate total for the parent attribute will be displayed before or after the child attributes in the expanded view.

      To enable insert drilling you must also:

      • Select the drill paths to enable. Drill paths are configured based upon the layout of the attributes in the Select Display Attributes page of the wizard.

      • Configure aggregation in the Configure Aggregation page of the wizard.

      For example, Figure 33-26 shows a pivot table using insert drilling to expand the view for the Year data layer. The aggregated value of Sales (52,500 in 2007, 544,150 in 2006) and Units (410 in 2007, 507 in 2006) for each year is displayed in the row above the products.

      Figure 33-26 Pivot Table with Insert Drilling Enabled

      Pivot table with insert drilling expanded.
    • Select Filter Drilling to provide a collapsed or expanded view of the detail data without preserving the sibling or aggregate data. At runtime, a drill icon is enabled in the parent attribute display label.

      Filter drilling focuses the view on the details of the data layer attribute. For example, Figure 33-27 shows a pivot table using filter drilling to expand the view of the Year (2007) data layer, displaying the total Sales (52,500) and Units (410), while filtering out both the data for the other years and the aggregated total for all the years.

      Figure 33-27 Pivot Table with Filter Drilling Enabled

      Pivot table with filter drilling expanded.

      To enable filter drilling you must select the drill paths to enable. Drill paths are configured based upon the layout of the attributes in the Select Display Attributes page of the wizard.

    For example, to enable the insert drilling for the Sales pivot table shown in Figure 33-20, complete the Configure Drilling page of the wizard, as shown in Figure 33-28.

    Figure 33-28 Configure Drilling Page of Create Pivot Table Wizard

    Configure drilling page of the create pivot table wizard.
  6. If you want to define how data is aggregated in totals and subtotals for the pivot table, use one or both of the Configure Aggregation pages of the Create Pivot Table wizard.

    By default, if the attributes displayed in the pivot table do not uniquely identify each row in the data collection, the data from duplicate rows is aggregated to collapse that data into a single pivot table cell. You can also override the default aggregate type for a particular data item.

    • If you want to specify how data is aggregated in the pivot table, in the Data Aggregation page, do the following:

      • If you want to change the default aggregation method for handling duplicate rows, use the Default Function dropdown list to specify the value. Valid values are Sum, Average, Count, Maximum, Minimum, Standard Deviation, Median, and Variance.

      • If you want to override the default aggregate type for a specific data value, click the Add icon to insert a row for the available attributes. Then, in the Function column for each attribute, select the mathematical operation that you want to use for the aggregation. Available options are Sum, Average, Count, Maximum, Minimum, Standard Deviation, Median, and Variance. This attribute is useful only when you have multiple data values (such as Sales and Units) bound to your pivot table.

      For example, to override the default aggregation type for the Units data value in the Sales pivot table shown in Figure 33-20, use the Add icon to add the Units attribute and select Average in the Function column in the Data Aggregation page, as shown in Figure 33-29.

      Figure 33-29 Data Aggregation Page of Create Pivot Table Wizard

      Data aggregation page of the create pivot table wizard.
    • You can also define totals and subtotals for attribute categories added to the column, row, or page edges in the pivot table. In the Categories Totals page, use the Add icon to insert each attribute or select Aggregate All to add all available attributes, and do the following:

      • In the Attribute column, select the attribute that you want to total.

      • In the Function column, select the mathematical operation that you want to use for the aggregation. Available options are Sum, Average, Count, Maximum, Minimum, Standard Deviation, Median, and Variance.

      • In the Insert Total column, select the value that indicates where you want the aggregate display to appear relative to the item referenced in the Attribute column. Valid values are: Before, After, or Replace.

      • In the Total Label column, enter the text that you want to use as a label for the aggregation. You can enter the text directly, specify a text resource from a resource bundle, or use the EL Expression builder to evaluate the label text at runtime.

      Note:

      If you configured Project Properties > Resource Bundle page to Automatically Synchronize Bundle, then you can type an alternate label string, and the design time code will create a translatable Text Resource for you.

      Note:

      The read-only Insert Drill Totals table displays the category totals automatically defined as a consequence of enabling insert drilling on the pivot table.

      For example, to define totals for the Geography and Year data layers in the Sales pivot table shown in Figure 33-20, select Sum in the Function column and After in the Insert Total column, and enter text (Total Geography and Total Year) in the Total Labels column respectively for each attribute in the Categories Totals page, as shown in Figure 33-30.

      In the resulting pivot table at runtime, expanding a particular Year value will automatically preserve the aggregate total computed from its child value based on the layout and configuration of the insert drill option in the previous wizard page.

      Figure 33-30 Categories Totals Page of the Create Pivot Table Wizard

      Category totals page of Create Pivot Talble wizard.
  7. If you want to configure sorting in the pivot table, use one or both of the Configure Sorting pages in the Create Pivot Table wizard.

    By default, a pivot table initially sorts data based on values in the outer row data layer. You can specify sort order on the data layer of any row, column, or page edge, called a category sort. At runtime, when the data layer is pivoted to a different edge, the specified category sort order is honored.

    You cannot specify a category sort of data labels (data values), although you can order the attributes mapped to the data body in the Select Display Attributes page of the wizard. For example, Figure 33-24 shows a pivot table layout with data values for Sales and Units. While you cannot specify a category sort of these measures, you can specify the order in which the values will appear in the data body of the pivot table at runtime, shown in Figure 33-20.

    You can also specify an initial sort order of the data values in the data body when the pivot table is rendered, called a data sort.

    • To configure sorting by category, in the Category Sort page, use the Add icon to add the attribute for each row, column, or page edge you wish to configure, and do the following:

      • In the Sort Attribute column, accept the default Use Attribute Value to specify an alphabetical sort based on the actual values in the pivot table header, or customize the sort order by specifying an alternate sort order attribute from the dropdown list. For example, if the underlying query included a rank calculation for ranking products by profitability, you could choose to see products ordered by (ProductRank, Descending).

      • In the Initial Sort Order column, select the initial direction of the sort. Valid values are ASCENDING or DESCENDING.

      For example, Figure 33-31 shows the Category Sort page of the wizard configured to display the Channel data layer descending on the column edge and the Year data layer ascending on the row edge.

      Figure 33-31 Category Sort Page of Create Pivot Table Wizard

      Category sort page of the Create Pivot Table wizard.

      At runtime, the pivot table displays as shown in Figure 33-32.

      Figure 33-32 Category Sort Example

      Category sort example
    • To configure data sorting, in the Data Sort page, do the following:

      • Select Sort by Columns to specify an initial sort order of the data when the pivot table is rendered.

      • In the Initial Sort Order dropdown list select the initial direction of the sort. Valid values are ASCENDING and DESCENDING.

      • In the Sequence Nulls dropdown list, select First if you want the null values to appear at the beginning of a sort and select Last if you want the null values to appear at the end of the sort.

      • In the Initial Sort Column table, specify a data value in the Value column for each data layer displayed in the Layer Attribute column.

      For example, Figure 33-33 shows the Data Sort page configured to sort the Channel data layer grouped by Year, based upon Units/World/Canoes data values.

      Figure 33-33 Data Sort Page of the Create Pivot Table Wizard

      Dat sort page of the Create Pivot Table wizard.

      At runtime, the pivot table initially renders as shown in Figure 33-34.

      Figure 33-34 Data Sort Example

      Data sort example
  8. In the Preview Your Pivot Table page of the Create Pivot Table wizard, see a live preview of the data that will be displayed in the pivot table. The preview does not require that you compile and run code. If you are not satisfied with the preview, alter the settings in the binding wizard pages and return again to the preview page to verify that your data looks as desired.

    Figure 33-35 shows the Preview Your Pivot Table page of the wizard for the Sales pivot table shown in Figure 33-20.

    Figure 33-35 Live Data Preview of Pivot Table

    Live data preview of pivot table

33.4.2 What Happens When You Use the Data Controls Panel to Create a Pivot Table

Dropping a pivot table from the Data Controls panel has the following effect:

  • Creates the bindings for the pivot table and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

33.4.2.1 Bindings for Pivot Tables

When you create a pivot table from the Data Controls panel, the page definition file is updated with the bindings. Example 33-10 shows the row set bindings that were generated for the pivot table that displays product sales and units sold within geography by year. The pivot table data map contains the following elements:

  • <columns>: Defines each column item in the appropriate sequence

  • <rows>: Defines each row item in the appropriate sequence

  • <pages>: Defines the items to be included in the pivot filter bar

  • <aggregatedItems>: Defines the totals and subtotals of items

  • <hierarchies>: Defines the potential drill paths between two items

  • <sorts>: Defines category sorts and the initial sort order of pivot table data

The default data aggregation method for duplicate rows is specified in the <data> element. For more information about aggregating duplicates, see Section 33.4.3, "What You May Need to Know About Aggregating Attributes in the Pivot Table."

For more information about sorting operations, see Section 33.4.4, "What You May Need to Know About Specifying an Initial Sort for a Pivot Table."

Example 33-10 Binding XML for the ADF Pivot Table

<pivotTable IterBinding="ptExampleDataIterator" id="ptExampleData"
            xmlns="http://xmlns.oracle.com/adfm/dvt"
            ChangeEventPolicy="ppr">
  <pivotTableDataMap>
    <columns>
      <item value="Geography"
            itemLabel="${adfBundle['view.ViewControllerBundle'].
            LOCATION"/>
        <data aggregateDuplicates="true" defaultAggregateType="SUM">
          <item value="Sales"/>
          <item value="Units" aggregateType="AVERAGE"/>
  </data>
    </columns>
    <rows>
      <item value="Year"/>
    </rows>
    <pages>
      <item value="Channel"/>
    </pages>
    <aggregatedItems>
      <item aggregateLocation="AFTER" aggregateType="SUM" value="Geography"
            aggregateLabel="${adfBundle['view.ViewControllerBundle'].
            TOTAL_GEOGRAPHY"/>
      <item aggregateLocation="AFTER" aggregateType="SUM" value="Year"
            aggregateLabel="${adfBundle['view.ViewControllerBundle'].
            TOTAL_ACROSS_YEARS}"/>
    </aggregatedItems>
    <drills type="INSERT"/>
    <hierarchies>
      <item value="Year" location="BEFORE">
         <child value="Product"
                label="${adfBundle['view.ViewControllerBundle'].PRODUCT"/>
      </item>
    </hierarchies>
    <sorts>
      <categorySort item="Channel" direction="DESCENDING"/>
      <categorySort item="Year" direction="ASCENDING"/>
      <qdrSliceSort direction="DESCENDING" edge="rows" grouped="true"
                    nullsFirst="true">
        <item name="Geography" value="World"/>
      </qdrSliceSort>
    </sorts>
  </pivotTableDataMap>
</pivotTable>

33.4.2.2 Code on the JSF Page for a Pivot Table and Pivot Filter Bar

When the pivot table is created using the Data Controls panel, the necessary code is added to the page. Example 33-11 shows the code generated on the JSF page for the sales pivot table and associated pivot filter bar.

Example 33-11 XML Code on a JSF Page for the Pivot Table and Pivot Filter Bar

<dvt:pivotFilterBar id="pt1pivotFilterBar"
                    value="#{bindings.ptExampleData.pivotFilterBarModel}"
                    modelName="pt1Model"/>
<dvt:pivotTable id="pt1" value="#{bindings.ptExampleData.pivotTableModel}"
                         modelName="pivotTableModel"
                         var="cellData" varStatus="cellStatus">
  <dvt:headerCell>
    <af:switcher facetName="#{cellData.layerName}" defaultFacet="Default" id="s1">
      <f:facet name="DataLayer">
        <af:outputText value="#{cellData.label}" id="ot1"/>
      </f:facet>
      <f:facet name="Year">
        <af:outputText value="#{cellData.dataValue}" id="ot2">
          <af:convertNumber groupingUsed="false"
                            pattern="#{bindings.ptExampleData.
                            hints.Gnp.format}"/>
        </af:outputText>
      </f:facet>
      <f:facet name="Product">
        <af:outputText value="#{cellData.dataValue}" id="ot3"/>
      </f:facet>
      <f:facet name="Default">
        <af:outputText value="#{cellData.dataValue}" id="ot4"/>
      </f:facet>
    </af:switcher>
  </dvt:headerCell>
  <dvt:dataCell>
    <af:switcher facetName="#{cellStatus.members.DataLayer.value}"
                 defaultFacet="Default" id="s2">
      <f:facet name="Sales">
        <af:outputText value="#{cellData.dataValue}" id="ot5">
          <af:convertNumber groupingUsed="false"
                            pattern="#{bindings.ptExampleData.
                            hints.Population.format}"/>
        </af:outputText>
      </f:facet>
      <f:facet name="Default">
        <af:outputText value="#{cellData.dataValue}" id="ot6"/>
      </f:facet>
    </af:switcher>
  </dvt:dataCell>
</dvt:pivotTable>

33.4.3 What You May Need to Know About Aggregating Attributes in the Pivot Table

If the attributes that you choose to display in your pivot table do not uniquely identify each row in your data collection, then you can aggregate the data from duplicate rows to collapse that data into a single pivot table cell.

For example, if the rows in the data collection shown in Figure 33-20 also contained a store identification, then the data rows from all stores in a given combination of Product, Channel, and Geography would have to be collapsed into a single cell in the pivot table.

The pivot table has the following optional data binding attributes available for controlling the calculation of duplicate data rows:

  • aggregateDuplicates: Boolean property of the <data> element that determines whether special processing is enabled at binding runtime to aggregate data values in duplicate rows. If this attribute is not specified, then false is assumed.

  • defaultAggregateType: String property of the <data> element that specifies a default aggregation method for handling duplicates. Valid values are SUM, AVERAGE, COUNT, MIN, MAX, STDDEV, MEDIAN, VARIANCE. If aggregateDuplicates is true and defaultAggregateType is unspecified, then SUM is assumed.

  • aggregateType: String property of an <item> element that enables you to override the default aggregate type for a particular data item. This attribute is useful only when you have multiple data values (such as Sales and Units) bound to your pivot table.

33.4.3.1 Default Aggregation of Duplicate Data Rows

By default, the pivot table uses the SUM operation to aggregate the data values of duplicate data rows in a data collection to produce a single cell value in the pivot table. This means that the aggregateDuplicates attribute is set to true and the defaultAggregateType is assumed to be SUM.

The <data> element shown in Example 33-10 is an example of such default aggregation.

33.4.3.2 Custom Aggregation of Duplicate Rows

If you want the pivot table to use a different mathematical operation to aggregate the data values of duplicate rows, then you set the defaultAggregateType to the desired operation.

Example 33-12 shows a data element with the defaultAggregateType set to SUM. This operation would be appropriate if you want to see the total of sales from all stores for each unique combination of Product, Channel, and State.

Example 33-12 Binding XML for Custom Aggregation of Duplicate Rows

<pivotTable IterBinding="SalesPivotTable1Iterator" id="SalesPivotTable11"
            xmlns="http://xmlns.oracle.com/adfm/dvt">
  <pivotTableDataMap>
    <columns>
      <data aggregateDuplicates="true" defaultAggregateType="SUM">
        <item value="Sales"/>
      </data>
      <item value="Geography"/>
    </columns>
    <rows>
      <item value="Channel"/>
      <item value="Product"/>
    </rows>
    <aggregatedItems>
      <item aggregateLocation="After" aggregateType="AVERAGE" 
            value="Product" aggregateLabel="Average"/>
    </aggregatedItems>
  </pivotTableDataMap>
</pivotTable>

If you have a pivot table with multiple data values (such as sales and the average size of a store in square feet) and you want to sum the sales data values in duplicate rows, but you want to average the square feet data values, then do the following:

  • On the <data> element, set the defaultAggregateType to SUM.

  • On the <item> element for the square feet attribute, set the aggregateType to AVERAGE.

Example 33-13 shows the <columns> elements wrapped by a PivotTableDataMap element. The <data> element contains the default attributes for aggregation. These apply to all data items that do not have a specific custom aggregateType attribute specified.

Example 33-13 Data and Item Elements for Multiple Custom Aggregations

    <columns>
       <data aggregateDuplicates="true" defaultAggregateType="SUM">
         <item value="Sales" label="Total Sales"/>
         <item value="StoreSqFeet" label="Avg Sq Feet" aggregateType="AVERAGE"/>
       </data>
       <item value="State"/>
    </columns>

33.4.4 What You May Need to Know About Specifying an Initial Sort for a Pivot Table

By default, a pivot table initially sorts data based on values in the outer row data layer. You can specify sort order on the data layer of any row, column, or page item, called a category sort. At runtime, when the data layer is pivoted to a different edge, the specified category sort order is honored. Insert a categorySort element inside the sorts element and set values for the attributes as described in Table 33-2.

Table 33-2 Attribute Values for categorySort Element

Attribute Description

item

Specify the column, row, or page item for which you are setting the category sort. A value for this attribute is required.

direction

Specify the initial direction of the sort. Valid values are ASCENDING and DESCENDING. A value for this attribute is required.


You can also specify the initial sort order of the data values in the data body when the pivot table is rendered, called a data sort. You can change the default behavior by inserting a sorts element inside the pivotTableDataMap element of a pivot table binding in the page definition file. Insert a qdrSliceSort element inside the sorts element and set values for the attributes as described in Table 33-3.

Table 33-3 Attribute Values for qdrSliceSort Element

Attribute Description

direction

Specify the initial direction of the sort. Valid values are ASCENDING and DESCENDING. A value for this attribute is required.

edge

Specify columns or rows to determine which edge sorts data. A value for this attribute is required.

grouped

Specify true if you want to sort slices within their parent or false if you want to sort across the entire edge. A value for this attribute is optional. The default value is false.

nullsFirst

Specify true if you want null values to appear at the beginning of a sort and false if you want null values to appear at the end of a sort. The default value is false. A value for this attribute is optional.


Insert one or more item tags inside the qdrSliceSort tag. An item tag specifies the slice on the opposite edge from which the values to be sorted should be obtained. For example, if sorting rows based upon the data, then you must specify an item tag for each layer on the column edge. Set values for the attributes as described in Table 33-4.

Table 33-4 Attribute Values for item Tag

Attribute Description

name

Specify the name of the layer to sort on. Typically, this is the column name in the row set. Specify DataLayer to identify the layer that contains the data columns in a row set (for example, Sales, Costs, and so on).

value

Specify the value of the specified layer on the desired slice.


33.5 Creating Databound Geographic Maps

An ADF geographic map is an ADF Data Visualization component that provides the functionality of Oracle Spatial within Oracle ADF. This component allows users to represent business data on a geographic map and to superimpose multiple layers of information (known as themes) on a single map. These layers can be represented as any of the following themes: bar graph, pie graph, color, point, and predefined theme.

Figure 33-36 shows a geographic map component that uses a base map for a region in the United States with the following themes:

  • Color theme: For the selected product, this theme colors states based on product popularity. The colors range from green (which represents the highest popularity for that product) to red (which represents the lowest popularity for that product).

  • Pie graph theme: This theme displays a pie graph in each state to indicate the popular product categories in that state. In this example, the pie graph shows the following product categories as pie slices: Media, Office, and Electronics.

  • Point theme: This theme identifies warehouses as points. For each point, it displays an icon to indicate the inventory level at that warehouse for the selected product. A separate icon is displayed for each of the following ranges of inventory: low inventory, medium inventory, and high inventory.

Figure 33-36 Geographic Map with Color Theme, Pie Graph Theme, and Point Theme for a Product

Geographic map with color, pie graph, and point themes

A geographic map component differs from other ADF Data Visualization components as you do not need to put multiple maps on a page to display multiple sets of data. This contrasts to components such as graphs where you can put multiple graphs on a page. Instead, you show how multiple sets of data relate to each other spatially or, for a specific point, you display different attributes layered in separate themes.

The geographic map component itself is not bound to data. However, each map theme has its own data bindings.

A base map forms the background on which the ADF geographic map component layers the themes that developers create.

In Oracle Spatial, administrators create base maps that consist of one or more themes. The administrator controls the visibility of the base map themes. When you zoom in and out on a base map, various base map themes are hidden or displayed. At the ADF geographic map component level, you cannot use zoom factor to control the display of the themes created by the administrator on the base map.

When you overlay themes on the ADF geographic map, you can control the visibility of your themes by setting the maxZoom and minZoom properties of the components related to these themes. At runtime, you can also hide or display your custom themes by using the View menu of the Map toolbar or by using other ADF components that you create on the page.

For information about customizing a geographic map after data-binding is completed, see the "Using ADF Geographic Map Components" chapter in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.5.1 How to Create a Geographic Map with a Point Theme

To create a geographic map, you first configure the map (that is, select a base map and provide URLs for processing) and then bind a theme of the map to a data collection. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Controls panel for the theme that you want to create.

When you create a map point theme, you have the option of customizing the style of the points that appear in the map. For each different point style, you can use a mapPointStyleItem tag.

To create a geographic map with a databound point theme:

  1. From the Data Controls panel, select a collection.

    Figure 33-37 shows an example where you could select the WarehouseStockLevelsByProduct1 collection in the Data Controls panel to create a geographic map with a point theme that displays an image to represent the quantity on hand for each warehouse point.

    Figure 33-37 Data Collection for Warehouse Stock Levels

    Data collection for warehouse stock levels
  2. Drag the collection onto a JSF page and, from the context menu, choose Geographic Map > Map and Point Theme.

  3. If you have not yet configured a map on the page, then in the ensuing Create Geographic Map dialog, click the New icon to display the Create Geographic Map Configuration dialog and do the following:

    1. In the Id field enter the unique identifier for the map configuration.

    2. In the MapViewer URL field enter the URL for the Oracle MapViewer service.

    3. In the Geocoder URL field select the URL for the Geocoder Web service that converts street addresses into latitude and longitude coordinates for mapping.

      Note:

      The Geocoder URL is needed only if you do not already have longitude and latitude information for addresses.
    4. Click OK to dismiss the dialog and return to the Create Geographic Map dialog.

  4. In the Maps page, you select the base map for the geographic map component and provide other settings to use with the map by doing the following:

    1. From the Data Source list select the collection of maps from which you will choose a base map.

    2. From the Base Map list select the map that will serve as the background for the geographic map component.

    3. To specify values for the StartingX field and the StartingY field click on the image of the map to center it within the Preview window.

      You can use the arrows in the map navigator in the upper left-hand corner to move the map in the appropriate direction.

    4. Optionally use the sliding arrow in the Preview window to adjust the zoom factor of the map.

    5. Click OK to dismiss the dialog and to display the Create Point Map Theme dialog.

  5. In the Theme Id field enter the unique identifier for the point map theme.

  6. In the Location section, specify whether the point location is to be specified by Address or by a pair of x and y coordinates (Longitude and Latitude).

    The choice you select for location will determine which controls appear in the Location section.

    Tip:

    Using x and y coordinates is a more efficient way to present data on the map rather than using the Address controls, which must be converted by a Geocoder to x and y coordinates. If the data collection has more than 100 rows, use x and y coordinates for better performance.
  7. For the x and y point location, select attributes from the data collection that represents the following items:

    • X (Longitude): The horizontal location of the point on the map.

    • Y (Latitude): The vertical location of the point on the map.

    • Label: The labels for the points in the top section of the information window, which is displayed when you click a point.

  8. In the Point Data section, provide the following information that identifies the data associated with the point, its label, and optionally the style for the point:

    • In the Data field, select the data column that is associated with the point, such as QuantityOnHand.

    • In the Label field, enter the text that will appear in the information window before the data value when you click a point. You can enter a text resource to use for the label. The text resource can be a translatable string from a resource bundle or an EL expression executed at runtime. Use the dropdown list to open a Select Text Resource or Expression Builder dialog. If you need help, press F1 or click Help.

    • Optionally, in the Category field, select a data column to use for finding the appropriate style for a point. If you select a value for Category, that value is stored in the binding for this point theme and then matched against the itemValue attribute of the mapPointStyleItem tags that you create for this point theme.

      Note:

      If your data does not have a column that you want to use as a category for finding the style of a point, you can also use mapPointStyleItem tags to define styles related to data ranges (such as high, medium, and low) that are matched to the values in the column that you select in the Data field. For more information, see Section 33.5.2, "How to Create Point Style Items for a Point Theme".
  9. Select the Enable Row Selection Select if you want to enable master-detail relationships. This is useful when the data collection for the geographic map is a master in a master-detail relationship with a detail view that is displayed in another UI component on the page. Selecting this options enables both selectionListenter and clickListener attributes.

  10. Click OK.

Figure 33-38 shows the Create Point Map Theme dialog for a geographic map with a point theme that displays an image representing quantity on hand for each warehouse point.

Figure 33-38 Create Point Map Theme Dialog for Warehouse Inventory Levels

Binding dialog for point map theme for warehouse levels

33.5.2 How to Create Point Style Items for a Point Theme

There are a variety of options available for creating point style items for use in a given map point theme. These are:

  • A single image for all data points

  • Separate images for each data point category

  • Images that represent low, medium, and high data value ranges

After you create the data binding for a map point theme, you have the option of selecting a single built-in image that should be used for all points in that map theme. In the Property Inspector, you can make this selection in the builtInImage attribute of the mapPointTheme tag. The default value for this attribute is an orange ball.

Alternatively, if you specify a value for Category in the Create Point Map Theme dialog, then you should also create a set of point style items to determine a separate image that represents data points in each category. In this case, you do not use the minimum and maximum values in the point style item tags. Instead, you set the itemValue attribute of point style item tags to a value that matches entries in the data column that you specified for Category.

In a point theme for a geographic map, if you do not specify a value for Category, you can still use the mapPointStyleItem child tags of the mapPointTheme tag to specify ranges of values (such as low, medium, and high) and the images that are to represent these ranges. If you do this, then each point will be represented by an image that identifies the range in which the data value for that point falls.

The following procedure assumes that you have already created a geographic map with a point theme.

To add point style items to a map point theme to represent low, medium, and high data value ranges:

  1. In the Structure window, right-click the dvt:mapPointTheme tag and choose Insert inside the dvt:mapPointTheme > Point Style Item.

  2. In the Point Style Item Property Inspector, set values as described Table 33-5, "Properties for Point Style Item".

    Table 33-5 Properties for Point Style Item

    For this property Set this value

    Id

    Specify a unique ID for the point style item.

    MinValue

    Specify the minimum value in a data range that you define.

    MaxValue

    Specify the maximum value in a data range that you define.

    ShortLabel

    Specify text to appear when a user hovers over the point item. For example, if you define a point item for low inventory, then enter Low Inventory as the value for this property.

    ImageURL

    Specify the URL to the image file or select it from the dropdown list. At runtime, the image you specify appears on the map to represent the data range identified by the MinValue and MaxValue properties.

    Alternatively, you can select one of a number of predefined images referenced by the BuiltInImage dropdown list that appears in the Other section.

    HoverImageURL

    Specify the URL to the image file or select it from the dropdown list. At runtime, the image you specify appears when a user hovers over the point item.

    SelectedImageURL

    Specify the URL to the image file or select it from the dropdown list. At runtime, the image you specify appears when a user selects the point item.


  3. If you defined a data value range for a low data value range in Steps 1 and 2, then repeat Steps 1 and 2 to define medium and high data value ranges with appropriate values.

Note:

The use of mapPointStyleItem child tags to customize the style of points is a declarative approach that lets you provide custom point images. For information about using a callback to provide not only custom images but also custom HTML, see Section 33.5.4, "What You May Need to Know About Adding Custom Point Style Items to a Map Point Theme".

33.5.3 What Happens When You Create a Geographic Map with a Point Theme

Dropping a geographic map and a point theme (which in this case would be the initial theme added to the map) from the Data Controls panel has the following effect:

  • Creates the bindings for the point theme and adds the bindings to the page definition file

  • Adds the necessary tags to the JSF page for the geographic map component

  • Adds the necessary point theme child tags within the geographic map tag to the JSF page

33.5.3.1 Binding XML for a Point Theme

Example 33-14 shows the row set bindings that were generated for the point theme of the geographic map.

Example 33-14 Point Theme Binding XML

<mapTheme IterBinding="WarehouseStockLevelsByProduct1Iterator"
          id="WarehouseStockLevelsByProduct1"
          xmlns="http://xmlns.oracle.com/adfm/dvt">
  <mapThemeDataMap convert="false" mapThemeType="point">
    <data>
      <item value="QuantityOnHand"
            label="${adfBundle['view.ViewControllerBundle'].PRODUCT_QUANTITY"/>
    </data>
      <item type="lat_long" latitude="Latitude"
            longitude="Longitude"
            label="${adfBundle['view.ViewControllerBundle'].WAREHOUSE_NAME"/>
  </mapthemeDataMap>
</mapTheme>

33.5.3.2 XML Code on the JSF Page for a Geographic Map and Point Theme

Example 33-15 shows the XML code generated on the JSF page for the geographic map and its point theme. Notice the code for the three kinds of point style settings based on data value.

The initial point style setting (ps0) applies to values that do not exceed 500. This point style displays an image for very low inventory and provides corresponding tooltip information.

The second point style setting (ps1) applies to values between 500 and 1000. This point style displays an image for low inventory and provides corresponding tooltip information.

The final point style setting (ps2) applies to values between 1000 and 1600. This point style displays an image for high inventory and provides corresponding tooltip information.

Example 33-15 Geographic Map and Point Theme XML Code on the JSF Page

<dvt:map id="map1"
         mapServerConfigId="mapConfig1"
         inlineStyle="width:850px;height:490px"
         startingX="-96.0"
         baseMapName="ELOCATION_MERCATOR.WORLD_MAP"
         startingY="37.0" zoomBarPosition="WEST"
         showScaleBar="false"
  <dvt:mapPointTheme id="mapPointTheme1"
                    shortLabel="#{viewcontrollerBundle.WAREHOUSE_STOCK_LEVELS}"
                    value="#{bindings.WarehouseStockLevelsByProduct1.geoMapModel}"
                    rendered="#{AppState.showPointTheme}">
    <dvt:mapPointStyleItem id="ps0"
                           minValue="0"
                           maxValue="500"
                           imageURL="/images/low.png"
                           selectedImageURL="/images/lowSelected.png"
                        shortLabel="#{viewcontrollerBundle.VERY_LOW_
                             INVENTORY}"/>
    <dvt:mapPointStyleItem id="ps1"
                           minValue="500"
                           maxValue="1000"
                           imageURL="/images/medium.png"
                           selectedImageURL="/images/mediumSelected.png"
                           shortLabel="#{viewcontrollerBundle.LOW_INVENTORY}"/>
    <dvt:mapPointStyleItem id="ps2"
                           minValue="1000"
                           maxValue="1600"
                           imageURL="/images/regularGreen.png"
                           selectedImageURL="/images/regularGreenSelected.png"
                           shortLabel="#{viewcontrollerBundle.HIGH_INVENTORY}"/>
  </dvt:mapPointTheme>
</dvt:map>

33.5.4 What You May Need to Know About Adding Custom Point Style Items to a Map Point Theme

If you want to provide custom HTML as well as custom images for map points, then you can use the customPointCallback attribute of the dvt:mapPointTheme tag to accomplish this customization.

Important:

If you set the customPointCallback attribute for a map point theme, the map ignores any dvt:mapPointStyleItem child tags because the callback overrides these tags.

To use a callback to customize the style of map points:

  1. Write a method in Java to perform the desired point customization.

  2. Store this method in a managed bean for the map.

    For more information about managed beans, see the "Creating and Using Managed Beans" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

  3. After you finish data-binding the map point theme, use the Property Inspector to specify a reference to the managed bean method in the customPointCallback attribute of the dvt:mapPointTheme tag.

    For example, if the managed bean is named MapSampleBean and the method is named setCustomPointStyle, then the reference becomes #{mapSampleBean.CustomPointStyle}.

33.5.5 How to Add a Databound Color Theme to a Geographic Map

When you create a geographic map, you can choose to create themes (point, color, and graph) in any sequence that you wish.

The following procedure assumes that a geographic map has already been configured and, therefore, the map component does not display the dialog for configuring the map. Instead, only the dialog for creating the color theme appears.

To add a databound color theme to a geographic map:

  1. From the Data Controls panel, select a collection.

    Figure 33-39 shows an example where you could select the ProductPopularity1 collection in the Data Controls panel to create a color map theme that shows product popularity by the color of regions (for example, states).

    Figure 33-39 Data Collection for Product Popularity by State

    Data collection for product popularity by state
  2. Drag the collection onto a JSF page which already contains a geographic map component and, from the context menu, choose Geographic Map > Color Theme.

  3. In the ensuing Create Color Map Theme dialog, enter a unique identifier for the map theme in the Id field.

  4. In the Base Map Theme section, identify the base map color theme to use for the geographic map by doing the following:

    1. In the Name field, select the name of the base map theme.

    2. For Location, select the location column in the data collection that should be matched to the location column in the base map theme that you selected.

    3. Optionally, click View Sample Theme Data to display the Sample Theme Data dialog, in which you can examine the first several rows of the actual data so that you can identify the appropriate location column.

      For example, if you want to view the data for a region that consists of states in the United States map, you might select MAP_STATES_NAME as shown in Figure 33-40.

      Note:

      It is possible for an administrator of Oracle Spatial to disable the display of sample data. If this button is not available, then consult the administrator for guidance.

      Figure 33-40 Sample Theme Data for Regions or States

      Sample theme data for regions or states
  5. In the Appearance section, specify the look of the color theme as follows:

    1. In Data Bucket Count, enter the number of groups for the data in this geographic map. Each group is coded with a color. After specifying this number, you can provide colors for the minimum value and the maximum value. The colors for the other values are chosen automatically using an RGB algorithm.

    2. In Minimum Value Color, select the color for the minimum value.

    3. In Maximum Value Color, select the color for the maximum value.

    Note:

    If you want to specify an exact color for each data bucket, see Section 33.5.7, "What You May Need to Know About Customizing Colors in a Map Color Theme".
  6. In the Data section, provide the following information about the data in the collection:

    1. For Location, select the column in the data collection that should match the values in the location column that you selected from the base map theme.

    2. For Location Label, select the column in the data collection that contains the labels associated with the values in the location column. These labels are shown in the information window that is displayed when you click or hover over a color.

    3. For Data Label, enter the label to use for describing the data in the information window and the tooltip that is displayed when you click or hover over a color. For example, the information window might include a label before the data value, such as Product Popularity. You can also enter a text resource to use for the data label. The text resource can be a translatable string from a resource bundle or an EL expression executed at runtime for a dynamic label. Use the dropdown list to open a Select Text Resource or Expression Builder dialog. If you need help, press F1 or click Help.

  7. Use Enable Row Selection only if you want to enable master-detail relationships. This is useful when the data collection for the map theme is a master in a master-detail relationship with a detail view that is displayed in another UI component on the page.

Figure 33-41 shows the Create Color Map Theme dialog for the product popularity by state color theme.

Figure 33-41 Create Color Map Theme for Product Popularity By State

Create Color Map Theme for Product Popularity By State

33.5.6 What Happens When You Add a Color Theme to a Geographic Map

Dropping a color theme from the Data Controls panel to an existing geographic map has the following effect:

  • Creates the bindings for the color theme and adds the bindings to the page definition file

  • Adds the necessary color theme child tags within the geographic map tag to the JSF page

33.5.6.1 Binding XML for a Color Theme

Example 33-16 shows the row set bindings that were generated for the color theme of the geographic map.

Example 33-16 Color Theme Binding XML

<mapTheme IterBinding="ProductPopularity1Iterator" id="ProductPopularity1"
          xmlns="http://xmlns.oracle.com/adfm/dvt">
  <mapThemeDataMap mapThemeType="color">
    <data>
      <item value="CountAddressesStateProvince"
            label="${adfBundle['view.ViewControllerBundle'].POPULARITY"/
    </data>
      <item type="location" value="StateProvince"
            label="${adfBundle['view.ViewControllerBundle'].STATE_PROVINCE"/
   </mapThemeDataMap>
</mapTheme>

33.5.6.2 XML Code on the JSF Page for a Color Theme

Example 33-17 shows the XML code generated on the JSF page for a color theme that represents product popularity in different states on the United States map.

Example 33-17 Color Theme XML Code on the JSF Page

<dvt:mapColorTheme id="mapColorTheme1"
     themeName="MAP_STATES_NAME"
     shortLabel="#{viewcontrollerBundle.PRODUCT_POPULARITY}"
     value="#{bindings.ProductPopularity1.geoMapModel}"
     locationColumn="POLYGON_NAME"
     minColor="#ff0000"
     maxColor="#008200"
     bucketCount="5"/>
</dvt:mapColorTheme>

33.5.7 What You May Need to Know About Customizing Colors in a Map Color Theme

While you are data-binding a map color theme, you can specify only a minimum color and a maximum color for the data buckets. The map uses an algorithm to determine the colors of the buckets between the minimum and maximum. However, after the data-binding is finished, you have the option of specifying the exact color to be used for each data bucket.

In the Object Inspector, for the dvt:mapColorTheme tag you can use the colorList attribute to specify the color for each bucket. You can either bind a color array to this attribute or you can specify a string of colors using a semicolon separator.

For example, if the value of this attributes is set to: #ff0000;#00ff00;#0000ff, then the color of the first bucket is red, the second bucket is green, and the third bucket is blue.

33.5.8 How to Add a Databound Pie Graph Theme to a Geographic Map

When you create a geographic map, you can choose to create themes (point, color, and graph) in any sequence that you wish. However, only one graph theme (pie or bar) can be visible at a time on the ADF geographic map component.

The following procedure assumes that a geographic map has already been configured and, therefore, the map component does not display the dialog for configuring the map. Instead, only the dialog for creating the pie graph theme appears.

To add a databound pie graph theme to a geographic map:

  1. From the Data Controls panel, select a collection.

    Figure 33-42 shows an example where you could select the PopularCategories1 collection to create a pie bar theme in an existing geographic map component to represent the popular product categories within a state.

    Figure 33-42 Data Collection for Popular Product Categories by State

    Data collection for popular product categories by state
  2. Drag the collection onto a JSF page and, from the context menu, choose Create > Pie Graph Theme.

  3. In the ensuing Create Pie Graph Theme Binding dialog, do the following to identify the new theme and the base map theme elements that you want to work with:

    1. For Theme Id, enter a unique identifier for the pie graph theme that you are creating.

    2. In the Base Map Theme section, select the name of the base map and the region in which you want to place the pie graphs.

  4. In the Appearance section, under Data, do the following:

    1. For Location, select the location column in the data collection that should be matched to the location column in the base map theme that you selected.

      If needed, click View Sample Theme Data to examine the first several rows of the actual data so that you can identify the appropriate location column.

    2. For Location Label, select the column in the data collection that contains labels for the locations in the data collection.

    3. In the grid for Series Attributes, enter each attribute that contains values that you want represented in the pie graph that you are creating.

    4. Beside each series attribute, enter text that should be used as a label for the data values in the series attribute.

  5. Select Enable Row Selection only if you want to enable the selection of rows in a related component. You select this component when the page contains a component that is linked to a data collection that is related to the geographic map that you are creating.

  6. Click OK.

Figure 33-43 shows the completed Create Pie Graph Map Theme dialog for the product popularity by state pie graph theme.

Figure 33-43 Create Pie Graph Map Theme for Product Popularity by State

Dialog for pie graph map theme

33.5.9 What Happens When You Add a Pie Graph Theme to a Geographic Map

Dropping a pie graph theme from the Data Controls panel to an existing geographic map has the following effect:

  • Creates the bindings for the pie graph theme and adds the bindings to the page definition file

  • Adds the necessary pie graph theme code to the JSF page within the map XML

33.5.9.1 Binding XML for a Pie Graph Theme

Example 33-18 shows the row set bindings that were generated for the pie graph theme of the geographic map.

Example 33-18 Pie Graph Theme Binding XML

<mapTheme IterBinding="PopularCategoriesByState1Iterator"       
        id="PopularCategoriesByState1"
        xmlns="http://xmlns.oracle.com/adfm/dvt">
  <mapThemeDataMap mapThemeType="pieChart">
    <item type="location" value="StateProvince" label="StateProvince"/>
    <data>
      <item value="AudioVideo"
            label="${adfBundle['view.ViewControllerBundle'].AUDIO_VIDEO}"/>
      <item value="CellPhones"
            label="${adfBundle['view.ViewControllerBundle'].CELL_PHONES}"/>
      <item value="Games"
            label="${adfBundle['view.ViewControllerBundle'].GAMES}"/>
    </data>
  </mapThemeDataMap>
</mapTheme>

33.5.9.2 Code on the JSF Page for a Pie Graph Theme

Example 33-19 shows the XML code generated on the JSF page for the pie graph theme of the geographic map.

Example 33-19 Pie Graph Theme Code on the JSF Page

<dvt:mapPieGraphTheme id="mapPieGraphTheme1"
     themeName="MAP_STATES_NAME"
     shortLabel="#{viewcontrollerBundle.POPULAR_CATEGORIES}"
     pieRadius="10"
     styleName="comet"
     value="#{bindings.PopularCategoriesByState1.geoMapModel}"
     locationColumn="POLYGON_ID"/>
</dvt:mapPieGraphTheme>

33.6 Creating Databound Thematic Maps

A thematic map represents business data as patterns in stylized areas or associated markers and does not require a connection to a remote Oracle MapViewer service. Thematic maps focus on data without the geographic details in a geographic map.

The thematic map is packaged with prebuilt base maps including a USA base map, a world base map, and base maps for continents and regions of the world including EMEA and APAC. Each base map includes several sets of regions and one fixed set of cities. A set of regions or cities is referred to as a layer. Each layer can be bound to a data collection and stylized to represent the data with color and pattern fills, or a data marker, or both. At runtime, only one map layer and its associated data can be displayed at a time, unless the thematic map has been enabled for drilling.

The data displayed in a thematic map is based on data collections. Using ADF data controls, JDeveloper makes data binding a declarative task. You drag and drop a collection from the Data Controls panel onto the JSF page and use a Component Gallery to select the base map and map layers on which to display the data. You can then use a Layer Browser and binding dialogs to bind data collection attributes to the data layers in the thematic map.

Stamping is used to associate map layers with a row of data in a data collection. Using stamping, each row of data in the data model can be identified by a style, for example a color or pattern; a marker, for example a circle or square; or an image. When you use stamping, child components are not created for every area, marker, or image in a thematic map. Rather, the content of the component is repeatedly rendered, or stamped, once per data attribute, such as the rows in a data collection.

For detailed information about thematic map end user and presentation features, use cases, tag structure, and adding special features to thematic maps, see the "Using Thematic Map Components" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.6.1 How to Create a Thematic Map Using ADF Data Controls

You can create a thematic map that displays business data associated with a regional layer in the base map, stylizing the map areas to visually illustrate the data.

For example, you could use a USA base map with a states map layer to display the preferences in each state for a particular brand of soft drink using colors as displayed in Figure 33-44. The example illustrates thematic map default features including a data bound legend and labels associated with the stylized areas when you use the Data Controls panel and thematic map binding dialogs.

Figure 33-44 Thematic Map Displaying Product Preference by US State

thematic map displaying product preference by state

The thematicMap component uses a model to access the data in the underlying list. The specific model class is oracle.adf.view.rich.model.CollectionModel. You can also use other model instances, for example, java.util.List, java.util.Array, and javax.faces.model.DataModel. The data layer will automatically convert the instance into a CollectionModel.

Before you begin:

It may be helpful to have an understanding of how thematic map attributes and thematic map child tags can affect functionality. For more information, see the "Configuring Thematic Maps" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have an ADF data control or ADF managed bean that represents the data you wish to display on the thematic map.

To create a thematic map using the Data Controls panel:

  1. From the Data Controls panel, select a data collection.

    Figure 33-45 shows an example where you could select the TmapStatesView1 collection in the Data Controls panel to create a thematic map using colors to represent the preference in each state for a particular product.

    Figure 33-45 Data Collection for Product Preference by State

    Data collection for product preference by state
  2. Drag the collection onto a JSF page and, from the context menu, choose Thematic Map.

  3. In the Component Gallery, select the map layer associated with the base map you want to configure for displaying data. In the example, a states map layer in the US base map is selected. Figure 33-46 shows the Component Gallery with the USA states map layer selected.

    Figure 33-46 Thematic Map Component Gallery

    Thematic map component gallery.

    By default, the Create Data Layer dialog opens for adding an area or point data layer to the selected map layer. In the example, an area data layer is configured. For information about adding and configuring point data layers, see Section 33.6.4, "How to Add Data Layers to Thematic Maps."

  4. In the Create Data Layer dialog, enter the following:

    • Layer Id: Enter a unique name for the data layer you are defining. By default, a unique, consecutively numbered id is entered, dl1, dl2, and so on.

    • Area: Select to add an area data layer to the map layer.

    • AreaLayer: References the map layer to which you are adding a data layer. In the example, a USA States map layer.

    • Location: Select the attribute that represents the column in the data model that determines the location of the data for the areas in the data layer. The locations are Ids of the regions from the base map for which the data is being displayed. For more information, see Section 33.6.3, "What You May Need to Know About Base Map Location Ids."

    • Set current row for master-detail: Select if you want to enable master-detail relationships. This is useful when the data collection for the thematic map is a master in a master-detail relationship with a detail view that is displayed in another UI component on the page. For more information, see Section 33.6.6, "What You May Need to Know About Configuring Master-Detail Relationships."

    Figure 33-47 shows the completed Create Data Layer dialog.

    Figure 33-47 Create Area Data Layer Dialog

    Create area data layer dialog.

    An area data layer representing the areaDataLayer component, and an area, representing the area component is added in the Layer Browser hierarchy. Figure 33-48 shows the expanded Layer Browser after adding an area data layer and area to the map layer.

    Figure 33-48 Thematic Map Layer Browser

    Thematic map layer browser
  5. In the Layer Browser, expand the area data layer, select the area to be stylized, and click the Edit icon to open the Configure Area dialog.

    Note:

    You configure an area with a default stamp across all areas in the thematic map layer, or you can you can use a child attributeGroups tag to generate the style attribute type automatically based on categorical groups in the data set. If the same style attribute is set in both the area tag, and by an attributeGroups tag, the attributeGroups style type will take precedence. For more information, see Section 33.6.7, "Styling Areas, Markers, and Images to Display Data."
  6. In the Configure Area dialog, Attribute Groups page, enter the following:

    • Grouping Rules: Use this table to specify the styling of categorical groups of data in a data collection. Use the Add icon to add a row to the table for configuring rules for a categorical group and use the Delete icon to remove any row selected in the table. Each grouping rule is represented as a attributeGroups component, and assigned a unique, consecutively numbered Id, ag1, ag2, and so on.

      For each row added to the table, enter the following:

      • Group by Value: Enter or use the dropdown list to select the attribute representing the column in the data set by which you wish to group the data values. For example, Category represents the product preference by state of the different soft drinks.

        Note:

        The selected attribute should consist of discrete values that can be categorized. For example, a range of numeric values between 40 and 45, are not automatically grouped.
      • Area Properties: Use the dropdown list to select the property to use for styling that area. Areas can be styled using color, pattern, opacity, or any combination of these valid values. Choose Select multiple attributes from the dropdown list for a dialog to specify any combination of values.

        The default style values that are generated for each property are defined using CSS style properties in the ADF skin. Each attributeGroups type has a default ramp defined in the skin, and these can be customized by setting the index-based properties to the desired values. For more information, see Section 33.6.7.4, "What You May Need to Know About Default Style Values for Attribute Groups."

      • Legend Label: Enter text or use the dropdown list to select the attribute representing the text to use for the categorical group in the thematic map legend. You can also select Expression Builder from the dropdown list to create an EL expression to specify the legend text. For more information, see Section 33.6.8, "Creating Databound Legends."

    • Value-Specific Rules: Click to open the Match Rules and Exception Rules tables used to specify a finer detail for one or more data values in categorical groups in a data set. For example, use a match rule to style every state with a preference of Dr Pepper with an aqua, #00ffff, color, instead of a predefined range of colors.

      Note:

      Any match or exception rule specified in these tables will override the settings defined in the Grouping Rules table.
    • Match Rules: Use to specify the style rule matched to one or more data values in a group of data in a data collection. Use the Add icon to add a row to the table for configuring a match rule for a categorical group and use the Delete icon to remove any row selected in the table. Each match rule is represented as a attributeMatchRule component, and assigned a unique, consecutively numbered Id, amr1, amr2, and so on. The property and property value is defined in a child f:attribute tag. For example:

      <dvt:attributeMatchRule id="amrl" group="Mountain Dew">
        <f:attribute name="color" value="#ffff00"/>
      </dvt:attributeMatchRule>
      

      For each row added to the table, enter the following:

      • Group Value: Enter the exact value for a Group By Value attribute that will trigger this Match Rule to execute. In the example, soft drink preference data collection attribute, values include Dr Pepper, 7 Up, and so on.

      • Property: Use the dropdown list to select the property to use for styling that data value. Areas can be styled using color, pattern, or opacity values. The property selected here must match one of the property types listed in the Area Properties for the attribute Grouping Rules.

      • Property Value: Enter or use the dropdown list to assign a value to the property. If the value provided by the match override is also in the prebuilt ramp returned by the Grouping Rules, then that value will only be used by the overrides and will be skipped in the prebuilt ramp.

        Valid values for color are RGB hexidecimal colors.

        Valid values for pattern include a choice of twelve prebuilt patterns, for example, smallChecker, largeDiamond, smallDiagonalRight, largeCrosshatch. If fill color is specified, the pattern displays in that color on the default white background.

        Valid values for opacity range from 0.0 for transparent to 1.0 for opaque.

    • Exception Rules: Use to specify one or more exception to the style rules for categorical groups in the data set. Use the Add icon to add a row to the table for configuring an exception rule and use the Delete icon to remove any row selected in the table. Each exception rule is represented as an attributeExceptionRule component, and assigned a unique, consecutively numbered Id, aer1, aer2, and so on. The property and property value is defined in a child f:attribute tag. For example:

      <dvt:attributeExceptionRule id="aer1" condition="#{row.name=='TX'}"
                                  label="Texas">
        <f:attribute name="color" value="#ff00ff"/>
      </dvt:attributeExceptionRule>
      

      For each row added to the table, enter the following:

      • Condition: Enter an EL expression, or use the dropdown list to open an Expression Builder dialog to create an EL expression that replaces the style property value with another when certain conditions are met. For example:

        #{row.Sales gt 100000}
        
      • Property: Use the dropdown list to select the property to use for styling that data value. Areas can be styled using color, pattern, or opacity values. The property selected here must match one of the property types listed in the Area Properties for the attribute Grouping Rules.

      • Property Value: Enter or use the dropdown list to assign a value to the property. If the value provided by the match override is also in the prebuilt ramp returned by the Grouping Rules, then that value will only be used by the overrides and will be skipped in the prebuilt ramp.

        Valid values for color are RGB hexidecimal colors.

        Valid values for pattern include a choice of twelve prebuilt patterns, for example, smallChecker, largeDiamond, smallDiagonalRight, largeCrosshatch. If fill color is specified, the pattern displays in that color on the default white background.

        Valid values for opacity range from 0.0 for transparent to 1.0 for opaque.

      • Legend Label: Enter a text resource to use for the legend label. The text resource can be a translatable string from a resource bundle or an EL expression executed at runtime. Use the dropdown list to open a Select Text Resource or Expression Builder dialog. If you need help, press F1 or click Help.

        Note:

        the text resource option is only available for a fixed area. For row-varying areas, use an EL expression to retrieve a row-varying key to look up the text resource in a resource bundle, for example:
        #{viewController.ResourceBundle[row.label]}
        
    • Messages: Review and clear as necessary any alerts related to the configuration of the area.

    Figure 33-49 shows the completed Configure Area dialog. The warning in the message pane alerts the user that the default area color specified in the Default Stamp page of the dialog will be overwritten by the color specified in the Grouping Rules and any value-specific overrides specified in the Attribute Groups page.

    Figure 33-49 Configure Area Dialog Attribute Groups Page

    Configure area dialog attribute groups page

You can add additional map layers representing available regions in the geographical hierarchy of the base map, and associate area or point data layers using the same data collection you used to create the thematic map. The Layer Browser represents the logical structure of the map layers, area and point data layers, and stylized areas and markers. Use the Layer Browser to:

After creating a thematic map using data controls, you can customize the default map labels, legend display, and add interactivity and animation effects. For more information, see in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.6.2 What Happens When You Use Data Controls to Create a Thematic Map

When you use ADF data controls to create a thematic map, JDeveloper:

  • Defines the bindings for the thematic map in the page definition file of the JSF page, and

  • Inserts code in the JSF page for the DVT thematic map components.

Example 33-20 shows the bindings defined in the page definition file of the JSF page for the example thematic map in Figure 33-44.

Example 33-20 XML Bindings in Page Definition File

<bindings>
  <tree IterBinding="TmapStatesView1Iterator" id="TmapStatesView1">
    <nodeDefinition DefName="model.TmapStatesView">
      <AttrNames>
        <Item Value="Abbrev"/>
        <Item Value="Category"/>
        <Item Value="Color"/>
        <Item Value="Data"/>
        <Item Value="Id"/>
        <Item Value="Name"/>
      </AttrNames>
    </nodeDefinition>
  </tree>
</bindings>

Example 33-21 shows the code inserted in the JSF page for the example thematic map in Figure 33-44.

Example 33-21 JSF Code for Thematic Map Components

<dvt:thematicMap id="tm1" basemap="usa">
  <dvt:areaLayer layer="states" id="al1">
    <dvt:areaDataLayer id="dl1"
          value="#{bindings.TmapStatesView1.collectionModel}" var="row">
      <dvt:areaLocation name="#{row.Name}" id="al2">
        <dvt:area id="a1">
          <dvt:attributeGroups id="ag1" value="#{row.Category}" type="color"
                               label="#{row.Category}">
            <dvt:attributeMatchRule id="amr1" group="Mountain Dew">
              <f:attribute name="color" value="#ffff00"/>
            </dvt:attributeMatchRule>
            <dvt:attributeMatchRule id="amr2" group="Sunkist">
              <f:attribute name="color" value="#ff00ff"/>
            </dvt:attributeMatchRule>
            <dvt:attributeMatchRule id="amr3" group="Dr Pepper">
              <f:attribute name="color" value="#00ffff"/>
            </dvt:attributeMatchRule>
            <dvt:attributeMatchRule id="amr4" group="7 Up">
              <f:attribute name="color" value="#00ff00"/>
            </dvt:attributeMatchRule>
            <dvt:attributeMatchRule id="amr5" group="Pepsi">
              <f:attribute name="color" value="#0000ff"/>
            </dvt:attributeMatchRule>
            <dvt:attributeMatchRule id="amr6" group="Coke">
              <f:attribute name="color" value="#ff0000"/>
            </dvt:attributeMatchRule>
          </dvt:attributeGroups>
         </dvt:area>
       </dvt:areaLocation>
     </dvt:areaDataLayer>
   </dvt:areaLayer>
  <dvt:legend id="l1">
    <dvt:legendSection source="al1:dl1:ag1" id="ls1"/>
  </dvt:legend>
</dvt:thematicMap>

33.6.3 What You May Need to Know About Base Map Location Ids

Each base map provided for the thematic map component has two or more prebuilt map layers that represent a set of regions. For example, the world base map includes a map layer for continents and another layer for countries. The regions in the lower level map layers are aggregated to make up the next level in the geographical hierarchy. The map layer is specified in the layer attribute of the areaLayer component.

When you are binding your data collection to a thematic map, you must provide a column in the data model that specifies the location of the area or point data using the map location Ids of the regions from the base map for which the data is being displayed. Area locations are specified in the name attribute of the areaLocation component, and point locations are specified in the pointName attribute for the pointLocation component when its type attribute is set to pointName.

For the United States base map, the locations Ids are determined by the following naming rules:

  • country layer: USA

  • states layer: Use the two-letter postal abbreviation. For example, the location Id for Massachusetts is MA, and the location Id for Texas is TX.

  • counties layer: Use the states layer location Id, followed by an underscore, and then the name of the county, all in capital letters with underscores replacing characters that are not letters. For example, the location Id for Middlesex county in Massachusetts is MA_MIDDLESEX, and the location Id for Red River county in Texas is TX_RED_RIVER.

  • cities layer: Use the states layer location Id, followed by an underscore, and then the name of the city, all in capital letters with underscores replacing characters that are not letters. For example, the location Id for the id for Boston, Massachusetts is MA_BOSTON, and the location Id for San Antonio, Texas is TX_SAN_ANTONIO.

For all other base maps, location Ids are determined by the following naming rules:

  • continents layer: AF (Africa), AS (Asia), AU (Australia), EU (Europe), NA (North America), and SA (South America) for the world, africa, asia, australia, europe, northAmerica, and southAmerica base maps.

  • worldRegions layers: APAC (Asia-Pacific), EMEA (Europe and the Middle East), LAT (Latin America), NA (United States and Canada) for the worldRegions, apac, emea, latinAmerica, and usaAndCanada base maps.

  • countries layer: Use the ISO 3166-1 alpha-3 country codes. For example, the location Id for Canada is CAN, and the location Id for China is CHN.

  • cities layer: Use the three-letter countries location ID, followed by an underscore, and then the name of the city, all in capital letters with underscores replacing characters that are not letters. For example, the location Id for Tornonto, Canada is CAN_TORONTO, and the location Id for Los Angeles, United States is USA_LOS_ANGELES.

You can download a comma-separated value (CSV) file for each of the prebuilt map layers with a complete listing of all the thematic map base map location Ids. Find these links in the tag documentation for the areaLocation component, name attribute. To access tag documentation for the data visualization components, select the component in the Structure window and click the help button in the Property Inspector.

33.6.4 How to Add Data Layers to Thematic Maps

You use data layers to associate map layers with a data collection. Using stamping, each row of data in the data model can be identified by a style, for example a color or pattern; a marker, for example a circle or square; or an image. When a map layer is displayed at runtime, the data appears as stylized areas, markers, or images.

Map layers can display data using an area data layer and/or one or more point data layers. Area data layers can be styled using areas, markers, or images. Point data layers can be styled using markers or images.

When a point data layer is associated with the base map as a direct child of thematicMap instead of as a child of a specific map layer, the data displays at all times and is called a global point layer.

Before you begin:

It may be helpful to have an understanding of how thematic map attributes and thematic map child tags can affect functionality. For more information, see the "Configuring Thematic Maps" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have a thematic map on your page. If you do not, follow the instructions in this chapter to create a thematic map. For more information, see Section 33.6.1, "How to Create a Thematic Map Using ADF Data Controls."

To add an area data layer to a map layer:

  1. Select the thematic map in the Visual Editor.

  2. In the Layer Browser, select the map layer to which you wish to bind a row in the data collection. If the Layer Browser is not open in the Visual Editor, right-click inside the map and choose Open Layer Browser.

  3. From the Add icon dropdown list, choose Add Data Layer to open the Create Data Layer dialog.

  4. In the Create Data Layer dialog, enter the following:

    • Layer Id: Enter a unique name for the data layer you are defining. By default, a unique, consecutively numbered id is entered, dl1, dl2, and so on.

    • Bind Data Now: Select and click Browse to open the Picker dialog > Data Controls Definitions page. Select the data collection in the ADF data controls you are using to data bind your data layer.

      Note:

      Alternatively, you can use the Expression Builder page to select an ADF managed bean you are using to databind your area data layer and areas. You can also use the Expression Builder dialog in each remaining field.
    • Area: Select to add an area data layer to the map layer.

    • AreaLayer: References the map layer to which you are adding a data layer.

    • Location: Select attribute that represents the column in the data model that determines the location of the data for the areas in the data layer. The locations are Ids of the regions from the base map for which the data is being displayed. For more information, see Section 33.6.3, "What You May Need to Know About Base Map Location Ids."

    • Set current row for master-detail: Select if you want to enable master-detail relationships. This is useful when the data collection for the thematic map is a master in a master-detail relationship with a detail view that is displayed in another UI component on the page. For more information, see Section 33.6.6, "What You May Need to Know About Configuring Master-Detail Relationships."

Figure 33-50 shows the completed Create Area Data Layer dialog.

Figure 33-50 Create Area Data Layer Dialog

Create Area Data Layer Dialog

By default, an area data layer representing the areaDataLayer component, and an area, representing the area component is added in the Layer Browser hierarchy. Example 33-22 shows the code added to the JSF page when you add an area data layer to a map layer.

Example 33-22 Area Data Layer Code in JSF Page

<dvt:thematicMap id="tm1" basemap="usa">
  <dvt:areaLayer layer="counties" id="al1">
    <dvt:areaDataLayer id="dl2"
                       value="#{bindings.TmapStatesView11.collectionModel}"
                       var="row">
      <dvt:areaLocation name="#{row.Name}" id="al2">
        <dvt:area id="a1"/>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
...
</dvt:thematicMap>

To add a point data layer to a map layer:

  1. Select the thematic map in the Visual Editor.

  2. In the Layer Browser, select the map layer to which you wish to bind a data layer. If the Layer Browser is not open in the Visual Editor, right-click inside the map and choose Open Layer Browser.

  3. From the Add icon dropdown list, choose Add Data Layer to open the Create Data Layer dialog.

    Note:

    If you wish to create a global point layer that displays at all times on the thematic map, choose Create Global Point Layer.
  4. In the Create Data Layer dialog, enter the following:

    • Layer Id: Enter a unique ID for the data layer you are defining. By default, a unique, consecutively numbered id is entered, dl1, dl2, and so on.

    • Bind Data Now: Select and click Browse to open the Picker dialog > Data Controls Definitions page. Select the data collection in the ADF data controls you are using to data bind your data layer.

      Note:

      Alternatively, you can use the Expression Builder page to select an ADF managed bean you are using to databind your point data layer and markers. You can also use the Expression Builder dialog in each remaining field.
    • Points: Select to add a point data layer to the map layer.

    • AreaLayer: Use the dropdown list to select the map layer to which you are associating a data layer. If you select All, the point data layer will be configured as a global point layer and display at all times. If you select an available map layer, the point data layer will only display with that map layer is displayed.

    • Data Type: Choose one of the following:

      • City: Select to use a pointName data type representing the named points, such as cities, in the data collection that map to named points in the base map.

      • Coordinates: Select to use a pointXY data type representing the columns in the data collection that join pointX and pointY to define the point locations.

    • Location: Available if a City Data Type is specified. Use the dropdown list to select the attribute that represents the column in the data model that determines the location of the data for the points in the data layer. The locations are IDs of the points from the base map for which the data is being displayed. For more information, see Section 33.6.3, "What You May Need to Know About Base Map Location Ids."

    • Longitude: Available if a Coordinates Data Type is specified. Use the dropdown list to select the attribute in the data collection that represents the longitude, or pointX of the marker.

    • Latitude: Available if a Coordinates Data Type is specified. Use the dropdown list to select the attribute in the data collection that represents the latitude, or pointY of the markers.

    • Set current row for master-detail: Select if you want to enable master-detail relationships. This is useful when the data collection for the thematic map is a master in a master-detail relationship with a detail view that is displayed in another UI component on the page. For more information, see Section 33.6.6, "What You May Need to Know About Configuring Master-Detail Relationships."

Figure 33-51 shows the completed Create Point Data Layer dialog for a pointName data type.

Figure 33-51 Create Point Data Layer Dialog

Create Point Data Layer Dialog

By default, a point data layer representing the pointDataLayer component, and a marker, representing the marker component is added in the Layer Browser hierarchy. Example 33-23 shows the code added to the JSF page when you add a point data layer to a map layer.

Example 33-23 Point Data Layer Code in JSF Page

<dvt:thematicMap id="tm1" basemap="usa">
  <dvt:areaLayer layer="states" id="al1">
    <dvt:pointDataLayer id="dl1"
                        value="#{bindings.TmapCitiesView11.collectionModel}"
                        var="row">
      <dvt:pointLocation type="pointName" pointName="#{row.City}" id="pl1">
        <dvt:marker id="m2"/>
      </dvt:pointLocation>
    </dvt:pointDataLayer>
  </dvt:areaLayer>
...
</dvt:thematicMap>

Example 33-24 shows the code added to the JSF page when you add a global point data layer to a thematic map.

Example 33-24 Global Point Data Layer Code in JSF Page

<dvt:thematicMap>
  <areaLayer layer="states" id="al1"/>
  <dvt:pointDataLayer id="dl2"
                      value="#{bindings.TmapCitiesView12.collectionModel}"
                      var="row">
    <dvt:pointLocation type="pointXY" pointX="#{row.Longitude}"
                       pointY="#{row.Latitude}" id="pl2">
      <dvt:marker id="m3"/>
    </dvt:pointLocation>
  </dvt:pointDataLayer>
...
</dvt:thematicMap>

After adding the area or point data layer to the thematic map, you style the data using areas, markers, or images. For more information, see Section 33.6.7, "Styling Areas, Markers, and Images to Display Data."

33.6.5 How to Configure Drilling in Thematic Maps

A thematic map with related data views in different map layers can be configured for drilling between the higher and lower level data views. For example, a thematic map can display data for sales category by USA state drilled down to USA county data as illustrated in Figure 33-62. When a state or county is selected, drilling up or down is initiated through a context menu choice or the Control Panel.

The following requirements must be met to achieve thematic map area drilling declaratively:

  • For each map layer (areaLayer) in the drilling hierarchy, you must bind its child areaDataLayer with a data control that defines the related data for that map layer.

  • Each areaDataLayer in the map layer drill hierarchy must have its selectionMode attribute set to single or multiple.

  • You must configure the area in the lower level map layer drill hierarchy to display data using the same default stamp or categorical attribute style used in the higher level map layer area component.

  • The thematicMap component drilling attribute must be set to on.

Note:

If drilling is enabled for the thematic map, drilling between a custom layer and the map layer used to aggregate the custom layer is available.

Before you begin:

It may be helpful to have an understanding of how thematic map attributes and thematic map child tags can affect functionality. For more information, see the "Configuring Thematic Maps" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have a thematic map on your page. If you do not, follow the instructions in this chapter to create a thematic map. For more information, see Section 33.6.1, "How to Create a Thematic Map Using ADF Data Controls."

You should already have data controls that define the data model for each of the map layers in the drill hierarchy.

To configure a thematic map area for drilling:

  1. In the Structure window, select the dvt:thematicMap component.

  2. In the Property Inspector, expand the Behavior section. Use this section to set the following attributes:

    • Drilling: Use to enable drilling the area data view between thematic map layers. From the dropdown list select on to enable drilling. The default value is off.

    • MaintainDrill: Optionally, use to specify an optional true value for maintaining the drilled state of a previously drilled area when a new area is drilled. The default value is false.

    • DrillBehavior: Optionally, use to specify an optional zoomToFit effect on the area being drilled. The default value is none.

  3. In the Layer Browser, select each Area Layer component in the desired drilling hierarchy and do the following:

    • Select the Add icon and choose Add Data Layer to open the Create Data Layer dialog. Complete the dialog to add an area data layer and bind the data layer to the data control for that map layer. If you need help, press F1 or click Help.

      Note:

      If the Area Data Layer is already present, select the Edit icon to confirm binding to the data control.
    • In the Property Inspector, expand the Behavior section and set the SelectionMode attribute to single or multiple.

  4. In the Layer Browser, select each Area Data Layer component in the desired drilling hierarchy and do the following:

    • Select the Add icon and choose Add Area to open the Configure Area dialog. Complete the dialog to define a default stamp or use attribute groups to style the area for that map layer. If you need help, press F1 or click Help.

      Note:

      If the Area is already present, select the Edit icon to confirm the styling of the area.

Figure 33-51 shows sample code for drilling enabled for USA states and counties map layers with an area styled to display data about sales categories.

Example 33-25 Sample Code for Configuring Drilling

<dvt:thematicMap id="thematicMap"
                 basemap="usa"
                 drilling="on"
                 maintainDrill="true"
                 drillBehavior="zoomToFit"
                 animationOnDisplay="none"
  <dvt:areaLayer id="al1" layer="states">
    <dvt:areaDataLayer id="adl1"
                       selectionMode="single"
                       contentDeliver="immediate"
                       value="#{row.state}"
                       var="row"
                       var="rowStatus">
      <dvt:areaLocation id="areaLocS" name="#{row.stname}">
        <dvt:area id="a1" fillColor="#{row.state}"/>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
  <dvt:areaLayer id="al2" layer="counties">
    <dvt:areaDataLayer id="adl2"
                       selectionMode="single"
                       contentDelivery="immediate"
                       value="#{row.county}"
                       var="row"
                       varStatus="rowStatus">
      <dvt:areaLocation id="areaLocC" name="#{row.coname}">
        <dvt:area id="a2" fillColor="#{row.county}"/>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
...
</dvt:thematicMap>

33.6.6 What You May Need to Know About Configuring Master-Detail Relationships

You can configure a thematic map to display its associated data in another UI component on the page such as a table. In this configuration the data collection for the thematic map is a master in a master-detail relationship with a detail view in another UI component. Figure 33-52 shows a thematic map displaying unemployment rates by state. Users can select one or multiple states to display the data detail view in the table.

Figure 33-52 Thematic Map Master and Detail Table View

Thematic map master and table detail view.

The following requirements must be met to achieve this master-detail processing declaratively:

  • You must use the same data collection to provide data for both views as follows:

    • Bind the thematic map areaDataLayer or pointDataLayer to the data collection whose attributes represent the data to be styled by areas or markers in the thematic map layer.

    • Bind the other ADF component (such as a table) to same data collection.

  • Select Set the current row for master-detail in the Create Data Layer dialog to automatically set a value for the selectionListener attribute of the thematic map areaLayer component and use the processSelection method that is already part of the thematic map binding.

    For example, if the value attribute of the thematic map area data layer component is value="#{stateData.employmentData}", then the selectionListener attribute is set to:

    selectionListener="#{stateData.employmentData.processSelection}".
    
  • Ensure that the selectionMode attribute on the areaDataLayer or pointDataLayer component is set to single or multiple, depending on the requirements for the thematic map.

33.6.7 Styling Areas, Markers, and Images to Display Data

An area data layer is used to associate map layers with a data collection. Using stamping, each row of data in the data model can be identified by a style, for example a color or pattern; a marker, for example a circle or square; or an image.

A point data layer is used to associate a set of points on a map with a data collection. The data point can be specified by a named point in a map layer, for example, cities in the US map, or by longitude and latitude. Using stamping, each row of data in the data model can be identified by a marker, for example a circle or square, or an image.

33.6.7.1 How to Style Areas to Display Data

You configure an area with a default stamp across all areas in the thematic map areaLayer, or you can use a child attributeGroups tag to generate the style attribute type automatically based on categorical groups in the data set. If the same style attribute is set in both the area tag, and by an attributeGroups tag, the attributeGroups style type will take precedence.

By default, when you add an area data layer, a configurable area is added to the Layer Browser. You can use the Layer Browser to add additional areas or markers to an area data layer, or markers to a point data layer. The Layer Browser reflects the logical structure of the map layers, area or point data layers, and areas or markers configured in the thematic map.

For example, using the default stamp, you can style all the states in the states layer of the usa base map with the color red as illustrated in Figure 33-53.

Figure 33-53 Thematic Map with Area Default Stamp Configured

Thematic map with area default stamp configured.

Before you begin:

It may be helpful to have an understanding of how thematic map attributes and thematic map child tags can affect functionality. For more information, see the "Configuring Thematic Maps" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have a thematic map on your page. If you do not, follow the instructions in this chapter to create a thematic map. For more information, see Section 33.6.1, "How to Create a Thematic Map Using ADF Data Controls."

To style areas using a default stamp:

  1. In the Layer Browser, select the area at the area location inside the map layer you are configuring.

  2. Choose the Edit icon to open the Configure Area dialog.

  3. In the Configure Area dialog, Default Stamp page, enter the following:

    • Location: By default, the attribute that represents the column in the data model that determines the location of the data for the areas in the data layer. The locations are Ids of the regions from the base map for which the data is being displayed. This read-only field displays the EL expression that maps the stamped area to a region in the base map. For more information, see Section 33.6.3, "What You May Need to Know About Base Map Location Ids."

    • Color: Optionally, from the dropdown list select the fill color for the area. Valid values are RGB hexidecimal. Choose Custom Color from the dropdown list to open a Color Picker dialog

    • Pattern: Optionally, from the dropdown list select one of twelve prebuilt patterns to style the area, for example, smallChecker, largeDiamond, smallDiagonalRight, largeCrosshatch. If fill color is specified, the pattern displays in that color on the default white background.

    • Opacity: Optionally, specify the opacity of the fill color of the area. Valid values range from 0.0 for transparent to 1.0 for opaque.

    • Include in Legend: Select and use the search icon to open a Select Text Resource dialog to select or create an application text resource to use for the legend text. The text resource can be a translatable string from a resource bundle or an EL expression executed at runtime. If you need help, press F1 or click Help.

      Note:

      the text resource option is only available for a fixed area. For row-varying areas, use an EL expression to retrieve a row-varying key to look up the text resource in a resource bundle, for example:
      #{viewController.ResourceBundle[row.label]}
      
    • Messages: Review and clear as necessary any alerts related to the configuration of the area.

Figure 33-54 shows the Configure Area dialog for the Default Stamp page.

Figure 33-54 Configure Area Dialog Default Stamp Page

Configure area dialog default stamp page

Example 33-26 shows the code inserted in the JSF page for the configured area.

Example 33-26 Sample Code for Area Default Stamp Configuration

<dvt:thematicMap id="tm1" basemap="usa">
  <dvt:areaLayer layer="states" id="al1">
    <dvt:areaDataLayer id="dl1"
                       value="#{bindings.TmapStatesView1.collectionModel}"
                       var="row">
      <dvt:areaLocation name="#{row.Name}" id="al2">
        <dvt:area id="a1" fillColor="#ff0000">
          <f:attribute name="legendLabel" 
                value="#{Bundle.US_STATES}"/>
        </dvt:area>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
</dvt:thematicMap>      

If you wish to style areas using categorical groups of data in the data collection, use the Attribute Groups page of the Configure Area dialog. For details about using the Attribute Groups page including sample code, see the use case described in Section 33.6.1, "How to Create a Thematic Map Using ADF Data Controls."

33.6.7.2 How to Style Markers to Display Data

You configure a marker with a default stamp across all markers in the thematic map layer, or you can use a child attributeGroups tag to generate the style attribute type automatically based on categorical groups in the data set. If the same style attribute is set in both the marker tag, and by an attributeGroups tag, the attributeGroups style type will take precedence.

By default, when you add a point data layer, a configurable marker element is added to the Layer Browser. You can use the Layer Browser to add additional areas or markers to an area data layer, or markers to a point data layer. The Layer Browser reflects the logical structure of the map layers, area or point data layers, and areas or markers configured in the thematic map.

For example, using the default stamp, you can identify all the predefined cities in the states layer of the USA base map with a red circle as illustrated in Figure 33-55. In the example, markers are styled on a point data layer. Styling markers on an area data layer is similar.

Figure 33-55 Thematic Map with Marker Default Stamp Configured

Thematic map with marker default stamp configured

Before you begin:

It may be helpful to have an understanding of how thematic map attributes and thematic map child tags can affect functionality. For more information, see the "Configuring Thematic Maps" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have a thematic map on your page. If you do not, follow the instructions in this chapter to create a thematic map. For more information, see Section 33.6.1, "How to Create a Thematic Map Using ADF Data Controls."

To style markers using a default stamp:

  1. In the Layer Browser, select the marker at the point location inside the map layer you are configuring

  2. Select the Edit icon to open the Configure Marker dialog.

  3. In the Configure Marker dialog, Default Stamp page, enter the following:

    • Location: By default, the attribute that represents the column in the data model that determines the location of the data for the markers in the data layer. The locations are Ids of the points from the base map for which the data is being displayed. This read-only field displays the EL expression that maps the stamped marker to a point in the base map. For more information, see Section 33.6.3, "What You May Need to Know About Base Map Location Ids."

    • Color: Optionally, from the dropdown list select the fill color for the marker. Valid values are RGB hexidecimal. Choose Custom Color from the dropdown list to open a Color Picker dialog.

    • Pattern: Optionally, from the dropdown list select one of twelve prebuilt patterns to style the marker, for example, smallChecker, largeDiamond, smallDiagonalRight, largeCrosshatch. If fill color is specified, the pattern displays in that color on the default white background.

    • Opacity: Optionally, specify the opacity of the fill color of the marker. Valid values range from 0.0 for transparent to 1.0 for opaque.

    • Shape: Optionally, select the shape of the marker. Valid values are circle (default), square, plus, diamond, triangleUp, triangleDown, and human.

      Optionally, use the Custom Shape field to specify the shapePath value to a Scalable Vector Graphics (SVG) file to use for the marker. Enter the path or use the Search icon to open the Select SVG File dialog and navigate to the file location. This option is only available if the default shape is selected in the Shape field.

      Shapes can also be specified using CSS style properties. Predefined marker shapes can be overwritten, and the paths to SVG files for custom markers can also be defined without using the shapePath attribute. For more information, see Section 33.6.7.3, "What You May Need to Know About Styling Markers."

    • Size: Optionally, enter a percentage by which to scale the marker from its default size for ScaleX (horizontal), and ScaleY (vertical). The percentages are then scaled to a float. For example, you can double the marker width by setting ScaleX to 200, written to the tag as 2.0, and halve the height by setting ScaleY to 50, written to the tag as 0.5.

    • Include in Legend: Enter a text resource to use for the legend label. The text resource can be a translatable string from a resource bundle or an EL expression executed at runtime. Use the dropdown list to open a Select Text Resource or Expression Builder dialog. If you need help, press F1 or click Help.

      Note:

      the text resource option is only available for a fixed area. For row-varying areas, use an EL expression to retrieve a row-varying key to look up the text resource in a resource bundle, for example:
      #{viewController.ResourceBundle[row.label]}
      
    • Messages: Review and clear any messages related to the configuration of the marker.

Figure 33-56 shows the Configure Marker dialog, Default Stamp page.

Figure 33-56 Configure Marker Dialog Default Stamp Page

Configure Marker Dialog default stamp page

Example 33-27 shows the code inserted in the JSF page for the configured marker.

Example 33-27 Sample Code for Marker Default Stamp Configuration

<dvt:thematicMap id="tm1" basemap="usa">
  <dvt:areaLayer layer="states" id="al1">
    <dvt:pointDataLayer id="dl2"
                        value="#{bindings.TmapCitiesView1.collectionModel}"
                        var="row">
      <<dvt:pointLocation type="pointName" pointName="#{row.City}" id="pl1">
        <dvt:marker id="m2" fillColor="#ff0000">
          <f:attribute name="legendLabel" 
                value="#{Bundle.US_CITIES}"/>
        </dvt:marker>
      </dvt:pointLocation>
    </dvt:pointDataLayer>
  </dvt:areaLayer>
</dvt:thematicMap>      

If you wish to style markers using categorical groups of data in the data collection, use the Attribute Groups page of the Configure Marker dialog. You can configure markers for a point data layer or an area data layer.

To style markers using categorical groups of data:

  1. In the Layer Browser, select the marker at the marker location inside the map layer you are configuring.

  2. Select the Edit icon to open the Configure Marker dialog.

  3. In the Configure Marker dialog, Attribute Groups page, enter the following:

    • Grouping Rules: Use this table to specify the styling of categorical groups of data in a data collection. Use the Add icon to add a row to the table for configuring rules for a categorical group and use the Delete icon to remove any row selected in the table. Each grouping rule is represented as a attributeGroups component, and assigned a unique, consecutively numbered Id, ag1, ag2, and so on.

      For each row added to the table, enter the following:

      • Group by Value: Enter or use the dropdown list to select the attribute representing the column in the data set by which you wish to group the data values.

        Note:

        The selected attribute should consist of discrete values that can be categorized. For example, a range of numeric values between 40 and 45, are not automatically grouped.
      • Marker Properties: Use the dropdown list to select the property to use for styling that marker. Markers can be styled using color, pattern, opacity, scaleX, scaleY, or any combination of these valid values. Choose Select multiple attributes from the dropdown list for a dialog to specify any combination of values.

        The default style values that are generated for each property are defined using CSS style properties in the ADF skin. Each attributeGroups type has a default ramp defined in the skin, and these can be customized by setting the index-based properties to the desired values. For more information, see Section 33.6.7.4, "What You May Need to Know About Default Style Values for Attribute Groups."

      • Legend Label: Enter text or use the dropdown list to select the attribute representing the text to use for the categorical group in the thematic map legend. You can also select Expression Builder from the dropdown list to create an EL expression to specify the legend text. For more information, see Section 33.6.8, "Creating Databound Legends."

    • Value-Specific Rules: Click to open the Match Rules and Exception Rules tables used to specify a finer detail for one or more data values for categorical groups in a data set.

      Note:

      Any match or exception rule specified in these tables will override the settings defined in the Grouping Rules table.
    • Match Rules: Use to specify the style rule matched to one or more data values in a group of data in a data collection. Use the Add icon to add a row to the table for configuring a match rule for a categorical group and use the Delete icon to remove any row selected in the table. Each match rule is represented as a attributeMatchRule component, and assigned a unique, consecutively numbered Id, amr1, amr2, and so on. The property and property value is defined in a child f:attribute tag. For example:

      <dvt:attributeMatchRule id="amrl" group="Mountain Dew">
        <f:attribute name="color" value="#ffff00"/>
      </dvt:attributeMatchRule>
      

      For each row added to the table, enter the following:

      • Group Value: Enter the exact value for the Group by Value attribute that will trigger the Match Rule to execute.

      • Property: Use the dropdown list to select the property to use for styling that data value. Markers can be styled using color, pattern, opacity, scaleX, scaleY, or any combination of these valid values. The property selected here must match one of the property types listed in the Marker Properties for the attribute Grouping Rules.

      • Property Value: Enter or use the dropdown list to assign a value to the property. If the value provided by the match override is also in the prebuilt ramp returned by the Grouping Rules, then that value will only be used by the overrides and will be skipped in the prebuilt ramp.

        Valid values for color are RGB hexidecimal colors.

        Valid values for pattern include a choice of twelve prebuilt patterns, for example, smallChecker, largeDiamond, smallDiagonalRight, largeCrosshatch. If fill color is specified, the pattern displays in that color on the default white background.

        Valid values for opacity range from 0.0 for transparent to 1.0 for opaque.

        Valid values for scaleX and scaleY are percentages that are then scaled to a float.

    • Exception Rules: Use to specify one or more exceptions to the style rules for categorical groups in the data set. Use the Add icon to add a row to the table for configuring an exception rule and use the Delete icon to remove any row selected in the table. Each exception rule is represented as an attributeExceptionRule component, and assigned a unique, consecutively numbered Id, aer1, aer2, and so on. The property and property value is defined in a child f:attribute tag. For example:

      <dvt:attributeExceptionRule id="aer1" condition="#{row.name=='TX'}"
                     label="Texas">
        <f:attribute name="color" value="#ff00ff"/>
      </dvt:attributeExceptionRule>
      

      For each row added to the table, enter the following:

      • Condition: Enter an EL expression, or use the dropdown list to open an Expression Builder dialog to create an EL expression that replaces the style property value with another when certain conditions are met. For example:

        #{row.Sales gt 100000}
        
      • Property: Use the dropdown list to select the property to use for styling that data value. Markers can be styled using color, pattern, opacity, scaleX, or scaleY. The property selected here must match one of the property types listed in the Marker Properties for the attribute Grouping Rules.

      • Property Value: Enter or use the dropdown list to assign a value to the property. If the value provided by the match override is also in the prebuilt ramp returned by the Grouping Rules, then that value will only be used by the overrides and will be skipped in the prebuilt ramp

        Valid values for color are RGB hexidecimal colors.

        Valid values for pattern include a choice of twelve prebuilt patterns, for example, smallChecker, largeDiamond, smallDiagonalRight, largeCrosshatch. If fill color is specified, the pattern displays in that color on the default white background.

        Valid values for opacity range from 0.0 for transparent to 1.0 for opaque.

        Valid values for scaleX and scaleY are percentages ranging from 100 to 500. The percentages are then scaled to a float, ranging from 1.0 to 5.0.

      • Legend Label: Enter a text resource to use for the legend label. The text resource can be a translatable string from a resource bundle or an EL expression executed at runtime. Use the dropdown list to open a Select Text Resource or Expression Builder dialog. If you need help, press F1 or click Help.

        Note:

        the text resource option is only available for a fixed area. For row-varying areas, use an EL expression to retrieve a row-varying key to look up the text resource in a resource bundle, for example:
        #{viewController.ResourceBundle[row.label]}
        
    • Messages: Review and clear as necessary any alerts related to the configuration of the marker.

For example, you can use markers in an area data layer to display categorical groups of data using colors as illustrated in Figure 33-57.

Figure 33-57 Marker Attribute Groups by Color

Marker attribute groups by color

Example 33-28 shows the sample code for marker attribute groups by color.

Example 33-28 Sample Code for Marker Attribute Groups by Color

<dvt:thematicMap basemap="usa" id="tm1"
  <dvt:areaLayer layer="states" id="al1" labelDisplay="off">
    <dvt:areaDataLayer id="dl1" var="row" value="#{stateData.colorModel}">
      <dvt:areaLocation id="al2" name="#{row.name}">
        <dvt:marker id="m1"
                    scaleX="3.0"
                    scaleY="3.0"
                    shape="circle">
          <dvt:attributeGroups id="ag1" type="color" value="#{row.category}"
                               label="#{row.category}"/>
        </dvt:marker>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
  <dvt:legend id="l1">
    <f:facet name="separator"/>
    <dvt:legendSection id="ls1" label="Category" source="ag1"/>
  </dvt:legend>
</dvt:thematicMap>

You can also use markers to display categorical groups of data using multiple attributes such as color and shape, and display an exception to the grouping rules when certain conditions are met. Figure 33-58 shows a thematic map with categorical groups using color and shape with an exception for the state of Texas.

Figure 33-58 Multiple Marker Attribute Groups with Exception Rule

Multiple marker attribute groups with exception rule

Example 33-29 shows sample code for multiple marker attribute groups with exception rule.

Example 33-29 Sample Code for Multiple Marker Attribute Groups with Exception Rule

<dvt:thematicMap basemap="usa" id="tm2"
  <dvt:areaLayer layer="states" id="al1" labelDisplay="off">
    <dvt:areaDataLayer id="dl1" var="row" value="#{stateData.colorModel}">
      <dvt:areaLocation id="al2" name="#{row.name}">
        <dvt:marker id="m1"
               scaleX="3.0"
               scaleY="3.0"
               shape="circle">
          <dvt:attributeGroups id="ag1" type="shape color" value="#{row.category}"
               label="#{row.category}">
            <dvt:attributeExceptionRule id="aer1" condition="#{row.name=='TX'}"
               label="Texas">
              <f:attribute name="color" value="#ff00ff"/>
            </dvt:exceptionRule>
          </dvt:attributeGroups> 
        </dvt:marker>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
  <dvt:legend id="l1">
    <f:facet name="separator"/>
    <dvt:legendSection id="ls1" label="Category" source="ag1"/>
  </dvt:legend>
</dvt:thematicMap>

33.6.7.3 What You May Need to Know About Styling Markers

Thematic maps support a predefined set of seven shapes (circle, square, and so on) that can be specified using the shape attribute in the marker component. For custom markers, the shapePath attribute can be used to specify the path of an SVG file that will get displayed in place of a predefined shape.

Marker shapes can be also specified through CSS style properties in an ADF skin. Using thematic map style properties, predefined marker shapes can be overwritten, and the paths to SVG files for custom markers can be defined without using the shapePath attribute. When using style properties, the shape attribute in the marker component is used for defining both predefined and custom shapes.

A predefined shape will be overwritten if a global or component-specific style property for that shape is specified in the ADF skin. For example, you can overwrite the predefined circle shape by specifying the newCircle.svg file in the thematic map component style property as follows:

af|dvt-thematicMap::shape-circle{
  -tr-path: url(/resources/path/newCircle.svg);
}

In the JSF page, the marker component shape attribute is set as follows:

<dvt:marker id="m1" shape="circle"/>

To specify a custom shape in the marker component shape attribute, you must use a prefix of custom in the shape style property name. For example, if the custom shape is named customName, then the ADF skin file should define either a global .AFDVTShapeCustomName:alias style property, or the thematic map specific af|dvt-thematicMap::shape-customName with the -tr-path property pointing to the SVG file as follows:

af|dvt-thematicMap::shape-customName{
  -tr-path: url(/resource/path/newCShape.svg);
}

In the JSF page, the marker component shape attribute is set as follows:

<dvt:marker id="m1" shape="customName"/>

For information about using ADF skins and style properties, see the "Customizing the Appearance Using Styles and Skins" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.6.7.4 What You May Need to Know About Default Style Values for Attribute Groups

The attributeGroups component is used to generate stylistic property values such as colors or shapes based on categorical grouping of the data in a data collection. Based on the attribute representing the column in the data model to group by, the attributeGroups component can generate style values for each unique value, or group, in the data.

The type of stylistic properties to generate values for is specified by the type attribute of the attributeGroups component. Supported types for area components are color, pattern, and opacity. Supported types for marker components are color, shape, pattern, opacity, scaleX, and scaleY. These types can be combined in a space-delimited list to generate multiple stylistic properties for each unique data value.

The default style values that are generated are defined using CSS style properties in the ADF skin. Each attributeGroups type has a default ramp defined in the ADF skin that can be customized by setting the index-based selectors to the desired values. Example 33-30 show sample code for using CSS style properties to specify attribute groups using CSS style properties.

Example 33-30 Attribute Groups CSS Style Properties

af|dvt-attributeGroups::shape1{
  -tr-shape: square;
}
af|dvt-attributeGroups::shape2{
  -tr-shape: square;
}
...
af|dvt-attributeGroups::color1{
  -tr-fill-color: #003366;
}

The default ramps for each attribute groups type are displayed in Table 33-6.

Table 33-6 Default Ramps for Thematic Map Attribute Groups

Type Default Ramps

color

j#003366 (blue), #CC3300 (red), #666699 (lavender), #0006666 (emerald), #FF9900 (orange yellow), #993366 (purple), #99CC33 (lime green), #624390 (violet,), #669933 (green), #FFCC33 (yellow), #006699 (turquoise blue), and #EBEA79 (pale yellow).

shape

square, circle, diamond, plus, triangleDown, triangleUp, and human

pattern

smallDiagonalLeft, smallDiagonalRight, smallTriangle, smallChecker, smallChecker, smallCrosshatch, smallDiamond, largeDiagonalLeft, largeDiagonalRight, largeTriangle, largeChecker, largeCrosshatch, largeDiamond

opacity

0.25, 0.50, 0.75, 1.0

scaleX and scaleY

1.0, 2.0, 3.0, 4.0, 5.0


For information about using ADF skins and style properties, see the "Customizing the Appearance Using Styles and Skins" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.6.7.5 How to Style Images to Display Data

You can use images to style data displayed in a thematic map. Using stamping, each row of data in the data model can be identified by an image. Images can be associated with either an area or point data layer.

For example, in an area data layer you can use a house image to identify prime locations on the states map layer of a US base map as illustrated in Figure 33-59.

Figure 33-59 Thematic Map Styling Data with Images

Thematic map styling data with images.

Before you begin:

It may be helpful to have an understanding of how thematic map attributes and thematic map child tags can affect functionality. For more information, see the "Configuring Thematic Maps" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have a thematic map on your page. If you do not, follow the instructions in this chapter to create a thematic map. For more information, see Section 33.6.1, "How to Create a Thematic Map Using ADF Data Controls."

To use an image to display data:

  1. In the Layer Browser, select the area or point data layer where you are configuring an image to display data.

  2. In the Structure window, right-click the area or point data layer child areaLocation or pointLocation component and select insert inside dvt:areaLocation or insert inside dvt:pointLocation > Image to open the Insert Image dialog.

  3. In the Insert Image dialog, enter the following:

    • Source: Enter the URI specifying the location of the image source. You can use the dropdown menu to choose Edit and open an Edit Property: Source dialog or the Expression Builder to specify the location of the image source.

    • ShortDesc: Enter the short description of the image used as the alt text for screen reader users.

Example 33-31 shows a code sample for using images to display data.

Example 33-31 Code Sample for Image Configuration

<dvt:thematicMap id="thematicMap" imageFormat="flash" basemap="usa"
                 summary="Thematic map showing the important real estate markets">
  <dvt:legend label="Legend">
    <dvt:legendSection source="areaLayer:dataLayer:img1"/>
  </dvt:legend>
  <dvt:areaLayer id="areaLayer" layer="states">
    <dvt:areaDataLayer id="dataLayer" contentDelivery="immediate"
                       value="#{tmapBean.colorModel}"
                       var="row"varStatus="rowStatus">
      <dvt:areaLocation id="dataLoc" name="#{row.name}">
        <af:image id="img1" source="/resources/images/geoMap/mansion.gif"
                            rendered="#{row.category == 'category1'}"
                            shortDesc="House image">
          <f:attribute name="legendLabel" value="Prime location"/>
        </af:image>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
</dvt:thematicMap>

33.6.7.6 What You May Need to Know About SVG Files

Scalable Vector Graphics (SVG) is the supported file format for creating custom shapes for thematic map markers.

SVG features that are not supported by custom shapes include:

  • Image tags within the SVG file. Everything must be declared using SVG's vector shapes.

  • Pattern fills

  • Gradients on strokes

33.6.8 Creating Databound Legends

Legends provide an explanatory table of the thematic map's styled data in symbol and label pairs. Thematic map legend components (legend) support symbols for color, shape, custom shape, fill pattern, opacity, images and size. One or more child legend item components (legendSection) are sourced from thematic map area, marker, attributeGroups, or af:image components stamped to style the data displayed in the map. The legend section structure supports control over content ordering and appearance. You can wrap legend items into a disclosable section using a showLegendSection component. Figure 33-60 shows a legend with a disclosable section for map areas and a marker.

Figure 33-60 Legend with Disclosable Section and Marker

llegend with disclosable section and marker

Legend items sourced from the attributeGroups component automatically split area or marker attribute types into different sections. You can specify a separator facet to draw separators between legend sections. Figure 33-61 shows a legend with attribute groups for color, shape, fill pattern, opacity, and size with separators between each section.

Figure 33-61 Legend with Attribute Groups

Legend with attribute groups.

Legends can be displayed in both Flash (default) and PNG image formats and both formats support bi-directional locales. When rendered in a PNG format, for example when printing the thematic map, disclosable sections in the legend are not supported, and legend items display as disclosed.

When you create a thematic map using the Data Controls panel and the thematic map binding dialogs, the legend data bindings are created for you. If you configure an area or marker as a default stamp across all areas in the thematic map, you can assign a static text resource to a fixed area or marker for the legend.

For default stamps displaying row-varying data, you can use an EL expression to assign the legend text and optionally, a managed bean to retrieve a row-varying key to look up the text resource in a resource bundle. Example 33-32 shows a code sample to generate legend entries for area and marker stamps. The code illustrates a disclosable section for a row-varying area and a fixed marker with an assigned text resource.

Example 33-32 Code Sample for Legend Area and Marker Stamps

<dvt:thematicMap id="tm1" basemap="usa" ...>
  <dvt:legend label=“Legend“>
    <dvt:showLegendGroupLabel label="Voting Majority">
      <dvt:legendSection id="ls1" source="al1:adl1:areaStamp“/>
    </dvt:showLegendGroupLabel>
    <dvt:legendSection id="ls2" source="al1:adl1:fixedMarker">
  </dvt:legend>
  <dvt:areaLayer id="al1" layer="states">
    <dvt:areaDataLayer id="adl1"...>
      <dvt:areaLocation id="aloc1" ,,,>
        <dvt:area id="areaStamp">
                  fillColor="#{row.value > 50 ? tmapLegendBean,color1 :
                  tmapLegendBean.color2}"
          <f:attribute name="legendLabel" value="#{row.value > 50 ?
                          'Candidate 2' : 'Candidate 1'}" />
        <dvt:marker id=“fixedMarker“ shape=“human” fillColor=“"#FF9900"
                                     scaleX="3" scaleY="3">
          <f:attribute name="legendLabel“ 
                       value="#{Bundle.Office_Locations}"/>
        </dvt:marker>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:area>
</dvt:thematicMap>    

If you configure an area or marker to use an attributes group to specify the styling of categorical groups of data in a data collection, you can use an EL expression to assign the legend text and optionally, a managed bean to retrieve a row-varying key to look up the text resource in a resource bundle.

If you specify a match rule for the attributes group, the legend text is specified in the group attribute. If you specify an exception rule, you can specify a text resource from the application resource bundle. Example 33-33 shows sample code for a legend with attribute groups, including both a match rule and an exception rule, and specifying a separator between legend sections.

Example 33-33 Sample Code for Legend with Attribute Groups

<dvt:thematicMap id="tm1" basemap="usa" ...>        
  <dvt:legend id="l1" label="Legend">
    <f:facet name="separator"
      <af:separator/>
    <dvt:legendSection id="ls1" source="al1:adl1:attributeGroupColor" />
    <dvt:legendSection id="ls2" source="al1:adl1:attributeGroupShape" />
    <dvt:legendSection id="ls3" source="al1:adl1:attributeGroupPattern" />
    <dvt:legendSection id="ls4" source="al1:adl1:attributeGroupOpacity" />>
  </dvt:legend>
  <dvt:areaLayer id="al1" layer="states">
    <dvt:areaDataLayer id="adl1" value=" " var=" " ...>
      <dvt:areaLocation id="dataLoc" name="#{row.name}">
        <dvt:marker id="m1"... >
          <dvt:attributeGroups id="attributeGroupColor" type="color"
                 label="#{row.category1}" value="#{row.category1}" />
            <dvt:attributeMatchRule id="amrl" group="Mountain Dew">
              <f:attribute name="color" value="#ffff00"/>
          </dvt:attributeMatchRule>
          <dvt:attributeGroups id="attributeGroupShape" type="shape"
                 label="#{row.category2}" value="#{row.category2}" />
            <dvt:attributeExceptionRule id="aer1" condition="#{row.name=='TX'}"
                 label="#{viewcontroller.Texas}">
              <f:attribute name="shape" value="human"/>
            </dvt:exceptionRule>
          <dvt:attributeGroups id="attributeGroupShape" type="pattern"
                 label="#{row.category3}" ... />
          <dvt:attributeGroups id="attributeGroupShape" type="opacity"
                 label="#{row.category4}" ... />
        </dvt:marker>         
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
</dvt:thematicMap>

You configure thematic map legend areas or markers in a custom region in the same way as any other map layer. shows sample code for a custom map layer legend.

Example 33-34 Sample Code for Legend for Custom Map Layer

<dvt:thematicMap>  
  <dvt:legend> 
    <dvt:legendSection label=“Sales Regions” source="customAreaStamp"/>
      </dvt:legend> 
      ...
  <dvt:customAreaLayer id="crl1“>
  ...
  </dvt:customAreaLayer>
  <dvt:areaLayer layer="crl1">
    <dvt:areaDataLayer var="row”>
      <dvt:areaLocation name="#{row.name}" id="al1">
        <dvt:area id=“customAreaStamp" fillColor="#{row.color}“>
          <f:attribute name="legendLabel“ value=“#{row.name}"/>
        </dvt:area>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
</dvt:thematicMap

You can customize the appearance of thematic map legends using ADF skins. For more information, see the "Customizing the Appearance Using Styles and Skins" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework

33.6.9 How to Define a Custom Map Layer

You can define a custom map layer from your own regional data and insert it into the natural geographical hierarchy of a thematic map. The custom layer is created by extending a predefined map layer and aggregating the lower level regions to form the new regions in the custom layer. After defining a custom map layer, it is used in the same way as any other map layer.

For example, you could define geographical regions for the NorthEast, Midwest, West and South in the United States in a US Regions custom map layer as illustrated in Figure 33-62. In the figure, the US Regions custom layer is extended from the states layer in the US base map. The new areas in the layer are aggregated from the states in the states layer. The label for the South US Region lists the states in that region. The MidWest US Region is drilled down to display the sales categories in the lower level counties region. For more information about drilling, see Section 33.6.5, "How to Configure Drilling in Thematic Maps."

Figure 33-62 US Regions Custom Map Layer

US Regions Custom Map Layer

The customAreaLayer component uses a model to access the data in the underlying list. The specific model class is oracle.adf.view.rich.model.CollectionModel. You can also use other model instances, for example, java.util.List, java.util.Array, and javax.faces.model.DataModel. The customAreaLayer will automatically convert the instance into a CollectionModel.

Before you begin:

It may be helpful to have an understanding of how thematic map attributes and thematic map child tags can affect functionality. For more information, see the "Configuring Thematic Maps" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have an ADF data control or ADF managed bean that defines the aggregated areas in the predefined base map you are extending.

You should already have a thematic map on your page. If you do not, follow the instructions in this chapter to create a thematic map. For more information, see Section 33.6.1, "How to Create a Thematic Map Using ADF Data Controls."

How to add and configure a custom map layer:

  1. Select the thematic map in the Visual Editor.

  2. In the Layer Browser, from the Add icon dropdown list, choose Add Custom Layer to open the Create Custom Layer dialog. If the Layer Browser is not open in the Visual Editor, right-click in the map and choose Open Layer Browser.

  3. In the Create Custom Layer dialog, enter the following:

    • Bind Data Now: Select and click Browse to open the Picker dialog > Data Controls Definitions page. Select the data collection in the ADF data controls you are using to data bind your custom layer and areas.

      Note:

      Alternatively, you can use the Expression Builder page to select an ADF managed bean you are using to databind your custom layer and areas. You can also use the Expression Builder dialog in each remaining field.
    • Layer Id: Enter a unique identifier for the customAreaLayer component. For example, if you divide the US into aggregate regions (Northeast, Midwest, West, and South), then you might define them with corresponding Ids (NE, MW, W, and S).

    • Extends: Use the search icon to display the built-in map layers that can be used to aggregate areas for the custom layer. Select the map layer that the custom layer will extend.

    • Area List: Use the dropdown list to select the data collection attribute representing the list of lower level map regions that are used to aggregate the areas in the custom map layer. The comma separated list of values aggregate the regions in the may layer defined in the in the Extends attribute.

    • Area Id: Use the dropdown list to select the data collection attribute representing the unique identifier of lower level map regions that are used to aggregate the areas in the custom map layer. By default, a unique identifier, ca1, ca2, and so on, is used in the for the customArea component.

    • Area Label: Use the dropdown list to select the data collection attribute representing the names of lower level map regions that are used to aggregate the areas in the custom map layer. At runtime the label will display the comma separated list of the aggregated regions.

Figure 33-63 shows the completed Create Custom Layer dialog.

Figure 33-63 Create Custom Layer Dialog

Create custom layer dialog

Figure 33-64 shows the Layer Browser after defining a custom layer. In the layer structure, the custom layer cal1 is referenced in the map layer al1, where you add area or point data layers to display data. For more information, see Section 33.6.4, "How to Add Data Layers to Thematic Maps."

Figure 33-64 Custom Map Layer in Layer Browser

Custom Map Layer in Layer Browser

Example 33-35 shows the code inserted in the JSF page

Example 33-35 Custom Map Layer Code

<dvt:thematicMap>
...
  <dvt:areaLayer layer="states" id="al1"/>
  <dvt:areaLayer layer="cal1" id="al3"/>
  <dvt:customAreaLayer id="cal1"
                       value="#{bindings.TmapStatesView.collectionModel}"
                       var="row"
                       extendsLayer="states">
    <dvt:customArea areaId="#{row.RowID}" areaList="#{row.RowID}"
                    label="#{row.RowID}" id="ca1"/>
  </dvt:customAreaLayer>
...
 </dvt:thematicMap>

After configuring and adding a custom layer to the map layer hierarchy, you can then use the map layer in the same way as any other map layer. For example, to create the thematic map illustrated in Figure 33-62, you will need to do the following:

Example 33-36 shows sample code for using a custom layer in a thematic map.

Example 33-36 Sample Code for Thematic Map with Custom Layer

<dvt:thematicMap id="thematicMap" imageFormat="flash" basemap="usa" drilling="on"
                 maintainDrill="true"
                 controlPanelBehavior="initExpanded" summary="US Custom Regions">
  <dvt:customAreaLayer id="crl1" value="#{tmapRegions.collectionModel}" var="row"
                       varStatus="rowStatus"
                       extendsLayer="states">
    <dvt:customArea areaId="#{row.name}" label="#{row.name}"
                    areaList="#{row.regions}" id="ca1"/>
  </dvt:customAreaLayer>
  <dvt:areaLayer id="custom" layer="crl1">
    <dvt:areaDataLayer contentDelivery="immediate"
                       value="#{tmapRegions.collectionModel}"
                       selectionMode="single"
                       var="row" varStatus="rowStatus" id="adl1">
      <dvt:areaLocation name="#{row.name}" id="al1">
        <dvt:area fillColor="#{row.color}" shortDesc="#{row.regions}"
                  id="a1" value="#{row.name}"/>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
  <dvt:areaLayer id="areaLayerS" layer="states"
    <dvt:areaDataLayer id="dataLayerS" selectionMode="multiple"
                       contentDelivery="immediate"
                       value="#{tmapStates.collectionModel}" var="row"
                       varStatus="rowStatus">
      <dvt:areaLocation id="areaLocS" name="#{row.name}">
        <dvt:area id="area1S" fillColor="#{row.color}"></dvt:area>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
  <dvt:areaLayer id="areaLayer" layer="counties">
    <dvt:areaDataLayer id="dataLayer" selectionMode="single"
                       contentDelivery="immediate"
                       value="#{tmapCounty.collectionModel}" var="row"
                       varStatus="rowStatus">
      <dvt:areaLocation id="areaLoc" name="#{row.name}">
        <dvt:area id="area1" fillColor="#{row.color}"
                             value="#{row.category}"></dvt:area>
      </dvt:areaLocation>
    </dvt:areaDataLayer>
  </dvt:areaLayer>
  <dvt:legend label="Sales Regions" id="l1">
    <dvt:legendSection source="custom:adl1:a1" id="ls1"/>
    <dvt:legendSection label="Counties" source="areaLayer:dataLayer:areaLoc"
                       id="ls3"/>
  </dvt:legend>
</dvt:thematicMap>

33.7 Creating Databound Gantt Charts

A Gantt chart is a type of bar graph (with time on the horizontal axis). It is used in planning and tracking projects to show tasks or resources in a time frame with a distinct beginning and end.

When you create a Gantt chart, you can choose from the following types:

  • Project

    A project Gantt chart lists tasks vertically and shows the duration of each task as a bar on a horizontal time line.

  • Resource Utilization

    A resource utilization Gantt chart shows graphically whether resources are over or under allocated. It shows resources vertically while showing their allocation and, optionally, capacity on the horizontal time axis.

  • Scheduling

    A scheduling Gantt chart is based on manual scheduling boards and shows resources vertically with corresponding activities on the horizontal time axis. Examples of resources include people, machines, or rooms.

For information about customizing Gantt chart charts after data-binding is completed, see the "Using ADF Gantt Chart Components" chapter in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.7.1 How to Create a Databound Project Gantt Chart

For a project Gantt chart, you must specify values for tasks. Optionally, you can specify values for split tasks, subtasks, recurring tasks, and dependencies between tasks, if your data collection has accessors for this additional information.

The project Gantt chart is displayed with default values for overall start time and end time and for the major and minor time axis values. In a project Gantt chart, the setting for the major time axis defaults to weeks and the setting for the minor time axis defaults to days.

Figure 33-65 shows a project Gantt chart in which each task is an order to be filled. The list region on the left side of the splitter shows columns with the name of the person who is responsible for the order and columns for the order date and shipped date. In the chart region on the right side of the splitter, the Gantt chart displays a horizontal bar from the order date to the ship date for each order.

Figure 33-65 The Order Shipping Project Gantt Chart

Display of the order shipping project gantt

To create a project Gantt chart using a data control, you bind the project Gantt chart component to a data collection. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Controls panel.

Tip:

You can also create a project Gantt chart by dragging a project Gantt chart component from the Component Palette and completing the Create Project Gantt dialog. This approach allows you to design the Gantt chart user interface before binding the component to data.

To create a databound project Gantt chart:

  1. From the Data Controls panel, select a data collection. For a Gantt chart, you can select a row set collection (which produces a flat list of tasks) or a basic tree collection (which produces a hierarchical list of tasks).

    Figure 33-66 shows an example where you could select the OrderShippingSummary1 collection in the Data Controls panel to create a project Gantt chart that displays the progress of order shipping.

    Figure 33-66 Data Collection for Shipping Orders

    Data collection for shipping orders
  2. Drag the collection onto a JSF page and, from the context menu, choose Gantt > Project.

  3. In the ensuing Create Project Gantt dialog, you do the following to connect task-related controls in the pages at the top of the dialog with corresponding columns in the data collection:

    1. In the Tasks page at the top of the dialog, you select the columns in the data collection that correspond to each of the following controls: Task Id, Start Time, and End Time. By clicking Show More in the dialog, you can select additional columns in the data collection that correspond to the following controls: Actual Start, Actual End, % Complete, Completed Through, Critical, and Is Container.

      Optionally, you can select a column in the data collection to map to the task type. If you do not bind Task Type to a column in your data collection, then all tasks default to Normal. The task type controls the appearance of the task bar when it is rendered in the Gantt chart.

      A project Gantt chart component supports the following task types that you configure the data collection to return: Summary, Normal, and Milestone.

    2. If the data collection has an accessor for subtasks, you have the option of using the Subtasks page in the dialog to select the subtasks accessor and to select the columns in the data collection that correspond to each of the following controls: SubTask Id, Start Time, and End Time. Optionally, you can select a column in the data collection to map to the subtask type. If you do not bind SubTask Type to data, then all subtasks default to Normal.

      A project Gantt chart component supports the following task types that you configure the data collection to return: Summary, Normal, and Milestone.

      If you do not bind subtasks, then the Gantt chart cannot render a hierarchy view of tasks. If you bind subtasks, then you can drill from tasks to subtasks in the hierarchy view of the Gantt chart.

    3. If the data collection has an accessor for dependent tasks, you have the option of using the Dependent Tasks page in the dialog to select the dependent task accessor and to select the columns in the data collection that correspond to the following controls: Dependency Type, From Task Id, and To Task Id.

      Dependent tasks are linked by their dependency between their finish and start times.

      A project Gantt chart component supports the following dependency types that you configure the data collection to return: fs (for finish to start), ss (for start to start), ff (for finish to finish), and sf (for start to finish).

    4. If the data collection has an accessor for split tasks, you have the option of using the Split Tasks page in the dialog to select Split Tasks accessor and to select the columns in that data collection that correspond to each of the following controls: SplitTask Id, Start Time, and End Time.

    5. If the data collection has an accessor for recurring tasks, you have the option of using the Recurring Tasks page in the dialog to select the recurring tasks accessor and to select the columns in that data collection that correspond to each of the following controls: Recurring Task Id, Type, Start Time, and End Time.

    6. You can use the Appearance page in the dialog to specify the attributes that correspond to the Label of the task bar, and up to three icons to associate with the task bar.

  4. In the Table Columns section, you specify the columns to appear in the list region of the Gantt chart. Specify one row of information for each column that is to appear. Use the New icon to add new rows. Use the arrow icons to arrange the rows in the exact sequence that you want the columns to appear in the Gantt chart list.

    Note:

    The first row that you specify in the Table Columns section designates the nodestamp column for the list region. The nodestamp column is the one that you can expand or collapse when you have a subtask collection.

    For each row, you provide the following specifications:

    • Display Label: Select the values for the headers of the columns in the Gantt chart list. If you select <default>, then the text for the header is automatically retrieved from the data binding.

    • Value Binding: Select the columns in the data collection to use for the columns in the Gantt chart list. The available values are the same as those for the tasks group.

    • Component to Use: Select the type of component to display in the cell of the Gantt chart list. The default is the ADF Output Text component.

  5. Click OK.

  6. If you want to include a legend in the Gantt chart, right-click the project Gantt chart node in the Structure window and choose Insert inside dvt:projectGantt > Legend.

    The legend shows information about each symbol and color coded bar that is used to represent different task types. It also shows detailed information about the task that is selected in the Gantt chart.

Figure 33-67 shows the dialog used to create the project Gantt dialog from the data collection for shipping orders.

Figure 33-67 Create Project Gantt Dialog for Orders Shipped

This diagram is described in surrounding text.

After completing the data binding dialog, you can use the Property Inspector to specify values for additional attributes for the project Gantt chart.

33.7.2 What Happens When You Create a Project Gantt Chart from a Data Control

Dropping a project Gantt chart from the Data Controls panel has the following effect:

  • Creates the bindings for the Gantt chart and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

Example 33-37 displays the row set bindings that were generated for the project Gantt chart that displays orders shipped. This code example shows that there are nodes defined for tasks and subtasks, along with attributes. There are also nodes defined for dependent tasks, split tasks, and recurring tasks but no attributes.

Example 33-37 Bindings for a Project Gantt Chart

<bindings>
  <gantt IterBinding="OrderShippingSummary2Iterator" id="GanttProjectView1"
         xmlns="http://xmlns.oracle.com/adfm/dvt">
    <ganttDataMap>
      <nodeDefinition DefName="oracle.fod.model.OrderShippingSummary"
                      type="Tasks">
        <AttrNames>
          <Item Value="TaskId" type="taskId"/>
          <Item Value="StartDate" type="startTime"/>
          <Item Value="EndDate" type="endTime"/>
          <Item Value="TaskType" type="taskType"/>
        </AttrNames>
      </nodeDefinition>
      <nodeDefinition type="subTasks">
        <AttrNames/>
      </nodeDefinition>
      <nodeDefinition type="Dependents">
        <AttrNames/>
      </nodeDefinition>
      <nodeDefinition type="SplitTasks">
        <AttrNames/>
      </nodeDefinition>
      <nodeDefinition type="RecurringTasks">
        <AttrNames/>
      </nodeDefinition>
  </ganttDataMap>
 </gantt>
</bindings>

Example 33-38 shows the code generated on the JSF page for the ADF project Gantt chart. This tag code contains settings for the overall start and end time for the project Gantt chart. It also shows the default time axis settings for the major axis (in weeks) and the minor axis (in days). Finally, it lists the specifications for each column that appears in the list region of the Gantt chart. For brevity, the code in the af:column elements for OrderStatusCode and ShippedDate has been omitted.

Example 33-38 Code on the JSF Page for a Project Gantt Chart

<dvt:projectGantt id="projectGantt1"
                  value="#{bindings.OrderShippingSummary2.projectGanttModel}"
                  var="row"
                  startTime="2011-04-15" endTime="2011-07-14">
  <f:facet name="major">
    <dvt:timeAxis scale="weeks" id="ta1"/>
  </f:facet>
  <f:facet name="minor">
    <dvt:timeAxis scale="days" id="ta2"/>
  </f:facet>
  <f:facet name="nodeStamp">
    <af:column
        sortProperty="#{bindings.OrderShippingSummary2.hints.FirstName.name}"
        sortable="false"
        headerText="#{bindings.OrderShippingSummary2.hints.FirstName.label}" 
        id="c1">
      <af:outputText value="#{row.FirstName}" id="ot1"/>
    </af:column>
  </f:facet>
    <af:column sortProperty="LastName" sortable="false"
             headerText="#{bindings.OrderShippingSummary2.hints.LastName.label}">
      <af:outputText value="#{row.LastName}"/>
    </af:column>
    <af:column sortProperty="OrderDate" sortable="false"
             headerText="#{bindings.OrderShippingSummary2.hints.OrderDate.label}">
       <af:outputText value="#{row.OrderDate}">
         <af:convertDateTime
             pattern="#{bindings.OrderShippingSummary2.hints.OrderDate.format}"/>
       </af:outputText>
     </af:column>
     <af:column sortProperty="ShippedDate" sortable="false"
         headerText="#{bindings.OrderShippingSummary2.hints.ShippedDate.label}">
       <af:outputText value="#{row.ShippedDate}">
       <af:convertDateTime
         pattern="#{bindings.OrderShippingSummary2.hints.ShippedDate.format}"/>
       </af:outputText>
     </af:column>
     <af:column sortProperty="TaskType" sortable="false"
         headerText="#{bindings.OrderShippingSummary2.hints.TaskType.label}">
       <af:outputText value="#{row.TaskType}"/>
     </af:column>
 </projectGantt>

33.7.3 What You May Need to Know About Summary Tasks in a Project Gantt Chart

A summary task shows start time and end time for a group of tasks (which are usually subtasks). A summary task cannot be moved or extended. However, your application should recalculate the summary task times when the dates of any subtask changes.

To detect a change in task duration, register an event handler by specifying a method binding expression on the DataChangeListener attribute of the Gantt chart component. When an action occurs that potentially changes data in the Gantt chart, the event fired is of type oracle.adf.view.faces.bi.event.DataChangeEvent. This event contains information about the data changes and is fired to the registered event listener. The listener is responsible for validating the new values and updating the underlying data model.

When the update is completed, the Gantt chart is refreshed with either the old data (if the update failed) or with the new data. The Gantt chart uses partial page rendering so that only the Gantt chart and not the entire page is refreshed.

33.7.4 What You May Need to Know About Percent Complete in a Project Gantt Chart

Percent complete can be represented as an inner bar that indicates what percentage of a task is complete. The length of the inner bar is calculated based on percent complete returned by the data object.

The data binding dialog for the project Gantt chart does not provide a control in which you can enter the percentage complete value, but this value is required to render a percent complete. However, the Gantt chart data object does contain a percentComplete attribute.

To provide the percent complete integer, you must add a new attribute mapping in the nodeDefinition for type Tasks. For example, if your data collection has a column named PercentDone, then the attribute mapping would appear as follows: <Item Value="PercentDone" type="percentComplete"/>.

Example 33-39 shows the percent complete attribute mapping added to the data binding code for the nodeDefinition of type Tasks in the project Gantt chart binding displayed in Example 33-37.

Example 33-39 Bindings for Project Gantt Chart with Percent Complete

<bindings>
  <nodeDefinition DefName="oracle.fod.model.OrderShippingSummary"
                                type="Tasks">
    <AttrNames>
      <Item Value="PersonId" type="taskId"/>
      <Item Value="OrderDate" type="startTime"/>
      <Item Value="TaskType" type="taskType"/>
      <Item Value="ShippedDate" type="endTime"/>
      <Item Value="PercentDone" type="percentComplete"/>
    </AttrNames>
  </nodeDefinition>
</bindings>

Another attribute (completedThrough) exists that allows you to specify a date rather than a percentage. The Gantt chart data object calculates the percentage complete based on the date that the completedThrough attribute references. For example, if your data collection has a column named PercentDone, then the attribute mapping would appear as follows: <Item Value="PercentDone" type="completedThrough"/>.

33.7.5 What You May Need to Know About Variance in a Project Gantt Chart

Variance can be rendered within two horizontal bars. One bar represents the base (or original) start and end time for the task. The second bar represents the actual start and end time for the task. You enter the binding information for the base start time and end time in the data binding dialog for a project Gantt chart.

The data binding dialog for Gantt chart does not provide controls in which you can enter the actual start time and actual end time for the Gantt chart, but these values are required to render variance. However, the Gantt chart data object does contain the following attributes: actualStart and actualEnd.

To provide the actual start and actual end time, you must add two new attribute mappings in the nodeDefinition for type Tasks. For example, if your data collection has columns named ActualStartDate and ActualEndDate, then the attribute mappings would appear as shown in Example 33-40.

Example 33-40 Attribute Mappings for Actual Start and Actual End

<Item Value="ActualStartDate" type="actualStart"/>
<Item Value="ActualEndDate" type="actualEnd"/>

Example 33-41 shows the actual start and actual end attribute mappings added to the data binding code for the nodeDefinition of type Tasks for a project Gantt chart.

Example 33-41 Bindings for Project Gantt Chart with Actual Start and Actual End

<nodeDefinition DefName="oracle.fod.model.OrderShippingSummary"
                type="Tasks">
  <AttrNames>
    <Item Value="PersonId" type="taskId"/>
    <Item Value="OrderDate" type="startTime"/>
    <Item Value="TaskType" type="taskType"/>
    <Item Value="ShippedDate" type="endTime"/>
    <Item Value="ActualStartDate" type="actualStart"/>
    <Item Value="ActualEndDate" type="actualEnd"/>
  </AttrNames>
</nodeDefinition>

33.7.6 How to Create a Databound Resource Utilization Gantt Chart

For a resource utilization Gantt chart, you must supply identification for resources, identification for time, and start and end times for resource usage. Optionally, you can provide data values for subresources.

The resource utilization Gantt chart is displayed with default values for the major and minor time axis values. In a resource utilization Gantt chart, the setting for the major time axis defaults to weeks and the setting for the minor time axis defaults to days.

Figure 33-68 shows a resource utilization Gantt chart that lists each resource and an associated calendar that can display when the resource is in use.

Figure 33-68 Resource Utilization Gantt Chart

Resource utilization Gantt chart

To create a resource utilization Gantt chart using a data control, you bind the resource utilization component to a data collection. JDeveloper allows you to do this declaratively by dragging a collection from the Data Controls panel and dropping it on a JSF page.

Tip:

You can also create a resource utilization Gantt chart by dragging a resource utilization Gantt chart component from the Component Palette and completing the Create Resource Utilization Gantt dialog. This approach gives you the option of designing the Gantt chart user interface before binding the component to data.

To create a resource utilization Gantt chart:

  1. From the Data Controls panel, select a data collection. For a Gantt chart, you can select a row set collection or a basic tree collection.

    Figure 33-69 shows an example where you could select the GanttRugResourcesView1 collection in the Data Controls panel to create a resource utilization Gantt chart to display the usage of a resource.

    Figure 33-69 Data Collection for Resource Utilization

    Data collection for resource utilization
  2. Drag the collection onto a JSF page and, from the context menu, choose Gantt > Resource Utilization.

  3. In the Create Resource Utilization Gantt dialog, connect resource- and time-related controls with corresponding columns in the data collection.

    1. For Resource Id, select the column in the data collection that corresponds to the unique identifier of the resource.

    2. In the Time Buckets page, select a value from the Bucket Accessor dropdown list that contains the time buckets assigned to the resource and select a value from the Bucket Date dropdown list that corresponds to a unit of time.

    3. In the Bucket Metrics list, you can optionally specify attributes that appear as bars within the time bucket. Each attribute that you specify in the Bucket Metrics list must be of type Number as the value of the attribute is used to calculate the height of the bar.

    4. In the Table Columns list, specify the column(s) to appear in the list region of the Gantt chart resource utilization on the left side of the splitter. Specify one row of information for each column that is to appear. Use the New icon to add new rows. Use the arrow icon to arrange the rows in the exact sequence that you want the columns to appear in the resource utilization list. For each row, provide values for Display Label, Value Binding, and Component to Use.

    5. If the data collection has an accessor for subresources, you can use the Subresources page to select a subresources accessor and a resource ID.

  4. Click OK.

    Figure 33-70 shows the dialog used to create a resource utilization Gantt chart from the data collection for resources available for a project.

    Figure 33-70 Create Resource Utilization Gantt Chart

    Create Resource Utilization Gantt Chart

33.7.7 What Happens When You Create a Resource Utilization Gantt Chart

Dropping a resource utilization Gantt chart from the Data Controls panel onto a JSF page has the following effects:

  • Creates bindings for the resource utilization Gantt chart and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

Example 33-42 shows the row set bindings that were generated for the resource utilization Gantt chart illustrated in Figure 33-70.

Example 33-42 Binding XML for a Resource Utilization Gantt Chart

<gantt IterBinding="GanttRugResourcesView2Iterator"
       id="GanttRugResourcesView2"
       xmlns="http://xmlns.oracle.com/adfm/dvt">
  <ganttDataMap>
    <nodeDefinition DefName="model.GanttRugResourcesView" type="Resources">
      <AttrNames>
        <Item Value="ResourceId" type="resourceId"/>
    </AttrNames>
  <Accessors>
    <Item Value="GanttRugTimebucketsView2" type="timeBuckets"/>
  </Accessors>
    </nodeDefinition>
    <nodeDefinition type="TimeBuckets"
                    DefName="model.GanttRugTimebucketsView">
      <AttrNames>
        <Item Value="TimeDaily" type="time"/>
        <Item type="metric" Value="Available"/>
        <Item type="metric" Value="Setup"/>
        <Item type="metric" Value="Used"/>
      </AttrNames>
    </nodeDefinition>
    <nodeDefinition type="Subresources">
      <AttrNames/>
    </nodeDefinition>
  </ganttDataMap>
</gantt>

Example 33-43 shows the code generated on the JSF page for the resource utilization Gantt chart. This tag code contains settings for the overall start and end time for the resource utilization Gantt chart. These settings have to be edited manually. The code also shows the time axis settings for the major time axis (in weeks) and the minor time axis (in days). Finally, it lists the specifications for each column to appear in the list region of the resource utilization Gantt chart.

Example 33-43 Code on the JSF Page for a Resource Utilization Gantt Chart

<dvt:resourceUtilizationGantt id="resourceUtilizationGantt1"
                              value="#{bindings.GanttRugResourcesView2.
                                  resourceUtilizationGanttModel}"
                              var="row"
                              metrics="#{bindings.GanttRugResourcesView2.metrics}"
                              taskbarFormatManager="#{bindings.
                                  GanttRugResourcesView2.
                                  resourceUtilizationGanttTaskbarFormatManager}"
                              startTime="2011-02-03"
                              endTime="2011-02-29">
  <f:facet name="major">
    <dvt:timeAxis scale="weeks"/>
  </f:facet>
  <f:facet name="minor">
    <dvt:timeAxis scale="days"/>
  </f:facet>
  <f:facet name="nodeStamp">
    <af:column sortProperty="ResourceId" sortable="false"
           headerText="#{bindings.GanttRugResourcesView2.hints.ResourceId.label}">
      <af:outputText value="#{row.ResourceId}"/>
    </af:column>
  </f:facet>
  <af:column sortProperty="ResourceName" sortable="false"
         headerText="#{bindings.GanttRugResourcesView2.hints.ResourceName.label}">
    <af:outputText value="#{row.ResourceName}"/>
  </af:column>
  <af:column sortProperty="ServiceRegion" sortable="false"
        headerText="#{bindings.GanttRugResourcesView2.hints.ServiceRegion.label}">
    <af:outputText value="#{row.ServiceRegion}"/>
  </af:column>
</dvt:resourceUtilizationGantt>

33.7.8 How to Create a Databound Scheduling Gantt Chart

For a scheduling Gantt chart, you must supply identification for resources, identification for tasks, and start and end times for tasks. Optionally, you can provide data values for subresources, recurring tasks, split tasks, and dependencies between tasks.

The scheduling Gantt chart is displayed with default values for overall start and end time and for the major and minor time axis values. In a scheduling Gantt chart, the setting for the major time axis defaults to weeks and the setting for the minor time axis defaults to days.

Figure 33-71 shows a scheduling Gantt chart that lists each resource and all the orders for which that resource is responsible. In contrast to a project Gantt chart, the scheduling Gantt chart shows all the tasks for a given resource on the same line, while the project Gantt chart lists each task on a separate line.

Figure 33-71 The Scheduling Gantt Chart for Order Shipping

Figure described in surrounding text.

To create a scheduling Gantt chart using a data control, you bind the schedulingGantt tag to a data collection. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Controls panel.

To create a databound scheduling Gantt chart:

  1. From the Data Controls panel, select a data collection. For a Gantt chart, you can select a row set collection or a basic tree collection.

    Figure 33-72 shows an example where you could select the Persons data collection to create a scheduling Gantt chart that displays the orders that each resource is responsible for.

    Figure 33-72 Data Collection for Resources

    Data collection for resources
  2. Drag the collection onto a JSF page and, from the context menu, choose Gantt, then Scheduling.

  3. In the ensuing Create Scheduling Gantt dialog, you do the following to connect resource- and task-related controls at the top of the dialog with corresponding columns in the data collection:

    1. For Resource Id, select the column in the data collection that corresponds to the unique identifier of the resource.

    2. In the Tasks page select a value from the Task Accessor dropdown list that contains the tasks assigned to the resource. Select the columns in the data collection that correspond to each of the following controls: Task Id, Start Time, and End Time. You can optionally specify a data column to map to task type. If you do not bind task type to data, then all task types default to Normal.

    3. If the data collection has an accessor that holds dependent tasks, you have the option of using the Dependent Tasks page in the dialog to select the dependent tasks accessor and to select the columns in that data collection that correspond to each of the following controls: Dependency Type, From Task Id, and To Task Id.

    4. If the data collection has an accessor for split tasks, you have the option of using the Split Tasks page in the dialog to select the split tasks accessor and to select the columns in that data collection that correspond to each of the following controls: Split Task Id, Start Time, and End Time.

    5. If the data collection has an accessor for recurring tasks, you have the option of using the Recurring Tasks page in the dialog to select the Recurring Tasks accessor and to select the columns in that data collection that correspond to each of the following controls: Recurring Task Id, Type, Start Time, and End Time.

    6. If the data collection has an accessor for subresources (lower-level resources), you have the option of using the Subresouces page to specify the appropriate accessor and to select the data column that contains the unique identifier of the subresource.

      For example, a manager might be a resource and his direct reports might be subresources. If data contains subresources, then you can drill in a resource to locate subresources.

  4. In the Table Columns section, you specify the columns that will appear in the list region of the Gantt chart on the left side of the splitter. Specify one row of information for each column that is to appear. Use the New icon to add new rows. Use the arrow icon to arrange the rows in the exact sequence that you want the columns to appear in the Gantt chart list. For each row, you provide the following specifications:

    • Display Label: Select the values for the headers of the columns in the Gantt chart list. If you select <default>, then the text for the header is automatically retrieved from the data binding.

    • Value Binding: Select the columns in the data collection to use for the column in the Gantt chart list. The available values are the same as those for the tasks group.

    • Component to Use: Select the type of component to display in the cell of the Gantt chart list. The default is the ADF Output Text component.

  5. Click OK to dismiss the Create Scheduling Gantt dialog.

  6. Select the dvt:schedulingGantt element in the Structure window of the JSF page and set dates for the following attributes of the dvt:schedulingGantt element in the Property Inspector:

    • StartTime

    • EndTime

    The dates that you specify determine the initial view that appears in the scheduling Gantt chart at runtime.

Figure 33-73 shows the dialog used to create the scheduling Gantt chart from the data collection for resources responsible for shipping orders.

Figure 33-73 Create Scheduling Gantt Dialog

CreateScheduling Gantt dialog

33.7.9 What Happens When You Create a Scheduling Gantt Chart

Dropping a scheduling Gantt chart from the Data Controls panel has the following effect:

  • Creates the bindings for the Gantt chart and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

Example 33-44 shows the row set bindings that were generated for the scheduling Gantt chart that displays resources and orders shipped.

Example 33-44 Binding XML for a Scheduling Gantt Chart

<gantt IterBinding="PersonsIterator" id="Persons"
       xmlns="http://xmlns.oracle.com/adfm/dvt">
  <ganttDataMap>
    <nodeDefinition DefName="oracle.fodemo.storefront.store.queries.PersonsVO"
                    type="Resources">
      <AttrNames>
        <Item Value="PersonId" type="resourceId"/>
      </AttrNames>
      <Accessors>
          <Item Value="OrdersVO" type="tasks"/>
      </Accessors>
    </nodeDefinition>
    <nodeDefinition type="Tasks"
                    DefName="oracle.fodemo.storefront.store.queries.OrdersVO">
      <AttrNames>
        <Item Value="OrderId" type="taskId"/>
        <Item Value="OrderDate" type="startTime"/>
        <Item Value="OrderStatusCode" type="taskType"/>
        <Item Value="OrderShippedDate" type="endTime"/>
      </AttrNames>
    </nodeDefinition>
    <nodeDefinition type="Dependents">
      <AttrNames/>
    </nodeDefinition>
    <nodeDefinition type="SplitTasks">
      <AttrNames/>
    </nodeDefinition>
    <nodeDefinition type="RecurringTasks">
      <AttrNames/>
    </nodeDefinition>
    <nodeDefinition type="Subresources">
      <AttrNames/>
    </nodeDefinition>
  </ganttDataMap
</gantt>

Example 33-45 shows the code generated on the JSF page for the scheduling Gantt chart. This tag code contains settings for the overall start and end time for the scheduling Gantt chart. It also shows the time axis settings for the major time axis (in months) and the minor time axis (in weeks). Finally, it lists the specifications for each column that appears in the list region of the Gantt chart. For brevity, the code in the af:column elements for MembershipId, Email, and PhoneNumber has been omitted.

Example 33-45 Code on the JSF Page for a Scheduling Gantt Chart

<dvt:schedulingGantt id="schedulingGantt1"
                     value="#{bindings.Persons.schedulingGanttModel}"
                     var="row" startTime="2011-03-29"
                     endTime="2011-05-30"
                     taskbarFormatManager="#{GanttBean.taskbarFormatManager}">
  <f:facet name="major">
    <dvt:timeAxis scale="months"/>
  </f:facet>
  <f:facet name="minor">
    <dvt:timeAxis scale="weeks"/>
  </f:facet>
  <f:facet name="nodeStamp">
    <af:column sortProperty="FirstName" sortable="false"
               headerText="#{bindings.Persons.hints.FirstName.label}">
      <af:outputText value="#{row.FirstName}"/>
   </af:column>
 </f:facet>
   <af:column sortProperty="LastName" sortable="false"
              headerText="#{bindings.Persons.hints.LastName.label}">
      <af:outputText value="#{row.LastName}"/>
    </af:column>
...
  <dvt:ganttLegend/>
</dvt:schedulingGantt>

33.8 Creating Databound Hierarchy Viewers

A hierarchy viewer is an ADF Data Visualization component that visually displays data where parent-child relationships exist within the data. This component is useful where you want to display organization charts, network diagrams, social networks, or similar visual displays.

Hierarchy viewers use a shape called a node to reference the data in a hierarchy. The shape and content of the nodes is configurable, as well as the visual layout of the nodes. Nodes can display multiple views in a panel card.

Figure 33-74 shows a runtime view of a hierarchy viewer component that renders an organization chart.

Figure 33-74 Hierarchy Viewer Component Rendering an Organization Chart

hierarchy viewer as an organizational chart

Each hierarchy viewer component (dvt:hierarchyViewer) that you create can include:

  • One or more node elements (dvt:node)

  • One or more link elements (dvt:link)

The optional panel card element (dvt:panelCard) can be used in conjunction with the hierarchy viewer component. The panel card provides a method to dynamically switch between multiple sets of content referenced by a node element using animation by, for example, horizontally sliding the content or flipping a node over.

For detailed information about hierarchy viewer end user and presentation features, use cases, tag structure, and adding special features to hierarchy viewers, see the "Using ADF Hierarchy Viewer Components" chapter in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

33.8.1 How to Create a Hierarchy Viewer Using ADF Data Controls

Hierarchy viewers are based on data collections where a master-detail relationship exists between one or more detail collections and a master data collection. Using data controls in Oracle ADF, JDeveloper makes this a declarative task. You drag and drop a data collection from the Data Controls panel that generates one or more root nodes onto a JSF page.

Before you begin:

It may be helpful to have an understanding of how hierarchy viewer attributes and hierarchy viewer child tags can affect functionality. For more information, see the "Configuring Hierarchy Viewers" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You should already have an ADF data control or ADF managed bean that represents the data you wish to display in the hierarchy viewer.

To create a hierarchy viewer using the Data Controls panel:

  1. From the Data Controls panel, select a collection.

    Figure 33-75 shows an example where you could select the HvtestView1 collection in the Data Controls panel to create a hierarchy viewer representing the personnel data in an organizational chart.

    Figure 33-75 Data Collection for Personnel Organizational Chart

    Data collection for personnel organizational chart
  2. Drag the collection onto a JSF page and, from the context menu, choose Hierarchy Viewer.

  3. From the Component Gallery, select the layout of the hierarchy viewer you want to create. Figure 33-76 shows the Component Gallery with the vertical top down layout selected.

    Figure 33-76 Hierarchy Viewer Component Gallery

    Hierarchy viewer component gallery
  4. In the Create Hierarchy Viewer dialog, enter the following:

    • Hierarchy: Select the collections you want to include as nodes in the runtime diagram. By default, the root collection is selected.

    • Node: For each collection that you select in the Hierarchy list, configure the attributes in the Title Area, and the title and attributes in each panel card, using one or more of the zoom levels available to you. By default, the node for the 100% zoom level follows an algorithm that:

      • Assigns the first three attributes in the data collection to the Title Area.

      • Assigns the next two attributes to the first panel card.

      • Assigns the following two attributes to the second panel card, and so on until all attributes are assigned to a panel card.

      Click the New icon to add a new panel card, attribute, or image to the node, relative to your selection in the node. After selecting an existing element, use the arrow icons (Up, Down, Top, Bottom) to reorder the element, or use the Delete icon to delete the selected element.

      Select a panel card, attribute, or image to configure one or more of the following for that element:

      • Text: Available for panel card elements. Not available for the Title Area element. Enter text for the panel card title in the hierarchy, or choose Select Text Resource from the dropdown list to open a dialog to select or add a text resource to use for the title. The text resource is a translatable string from an application resource bundle. If you need help, press F1 or click Help.

      • Attribute: Available for attribute and image elements. From the dropdown list, select the attribute in the data collection that represents the value you wish to display in the hierarchy viewer node.

      • Label: Available for attributes. Not available for default attributes assigned to the Title Area. From the dropdown list, select the attribute in the data collection that represents the label you wish to display for that element in the hierarchy viewer node. You can use the default Use Attribute Name to render the value as a string using the label from the UIHints for that attribute in the underlying ViewObject, select No Label to render no label for the attribute, or choose Select Text Resource to open a Select Text Resource dialog to select or add a text resource to use for the label. The text resource is a translatable string from an application resource bundle.

      • Component: Available for attributes. Select the type of component to use to display the data in the node. Valid values are: ADF Output Text/w label, ADF Output Text, ADF Output Formatted Text w/ Label, and ADF Output Formatted Text. For more information about using these components, see the "Using Output Components" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

      Use the 75%, 50%, and 25% pages to specify the expanded display of the hierarchy at each page level. Select Add Zoom Level to enable the page level. By default, the algorithms to assign node attributes and panel cards in the node are similar to the 100% zoom level.

      Note:

      The hierarchy viewer component defines four zoom levels. You cannot modify these zoom levels or create new zoom levels. The default zoom level is 100%.
    • Sample: A non-configurable display of the sample outline of the hierarchy viewer node. Areas such as Title Area and attributes are highlighted in the sample when selected in the node area.

  5. Click OK.

Figure 33-77 shows the Create Hierarchy Viewer dialog that appears if you create a hierarchy viewer using data from a data collection named HvtestView1.

Figure 33-77 Create Hierarchy Viewer Dialog

Create Hierarchy Viewer Dialog

After completing the Create Hierarchy Viewer dialog, you can use the Property Inspector to specify settings for the hierarchy viewer attributes and you can also use the child tags associated with the hierarchy viewer tag to customize the hierarchy viewer further.

When editing the hierarchy viewer in the visual editor, the display approximates the runtime display and functionality. You can move between panel cards, and work with stamped elements within the panel cards and title area to rearrange attributes or bind new attributes imported from the Data Controls panel.

33.8.2 What Happens When You Create a Databound Hierarchy Viewer

Creating a hierarchy viewer from Data Controls panel has the following effect:

  • Creates the bindings for the hierarchy viewer in the page definition file of the JSF page

  • Adds the necessary tags to the JSF page for the hierarchy viewer component

Example 33-46 displays bindings that JDeveloper generated for a hierarchy viewer component. The rules for populating the nodes of the master-detail tree are defined as a node definition. The example shows that two node definitions were generated. Each of these node definitions references a view object and associated attributes. The code example also references an accessor HvtestView.

Example 33-46 Bindings for a Hierarchy Viewer

<tree IterBinding="HvtestView1Iterator" id="HvtestView1">
  <nodeDefinition DefName="model.HvtestView"> Name="HvtestView10">
    <AttrNames>
    <Item Value="Adress"/>
    <Item Value="Email"/>
    <Item Value="Lastname"/>
    <Item Value="Thumburl"/>
    <Item Value="Firstname"/>
    <Item Value="Title"/>
    <Item Value="Managerid"/>
    <Item Value="Id"/>
    <Item Value="Phone"/>
    <Item Value="City"/>
    <Item Value="State"/>
  </AttrNames>
  <Accessors>
    <Item Value="HvtestView"/>
  </Accessors>
  </nodeDefinition>
  <nodeDefinition DefName="model.HvtestView">
  <AttrNames>
    <ittem Value="Adress"/>
    <Item Value="Email"/>
    <Item Value="Lastname"/>
    <Item Value="Thumburl"/>
    <Item Value="Firstname"/>
    <Item Value="Title"/>
    <Item Value="Managerid"/>
    <Item Value="Id"/>
    <Item Value="Phone"/>
    <Item Value="City"/>
    <Item Value="State"/>
  </AttrNames>
  <Accessors>
   <Item Value="ManageridHvtestView"/>
  </Accessors>
  </nodeDefinition>
</tree>

Example 33-47 shows the code generated on the JSF page that is associated with the page definition file in Example 33-46. For brevity, the code in the facet elements named zoom75, zoom50, and zoom25 has been omitted. Some code from elements such as <af:panelGroupLayout>, <af:spacer/>, and <af:separator/> has also been omitted.

The example shows a hierarchy viewer component that references the HvtestView1 tree binding. It includes a node (dvt:node) component that in turn includes a panel card component (dvt:panelCard). The panel card component defines slide_horz as the effect to use when changing the display of content referenced by the node.

Once you create your hierarchy viewer, you can modify the layout of the component or add additional components, such as a panel card, using the Create Hierarchy dialog illustrated in Figure 33-77. To open the dialog, use the Edit icon in the Property Inspector for the hierarcyViewer component. You can also customize the layout of a hierarchy viewer component directly in the code, in the visual editor, or by setting values in the Property Inspector. You can add additional components, such as panel card, using the Component Palette.

Example 33-47 Code on the JSF Page for a Hierarchy Viewer

<dvt:hierarchyViewer inlineStyle="width:100%;height:600px;" id="hv1" var="node"
                     value="#{bindings.HvtestView1.treeModel}"
                 selectionListener="#{bindings.HvtestView1.
                     treeModel.makeCurrent}"
                 featuresOff="nodeDetail" layout="hier_vert_top"
                 levelFetchSize="#{bindings.HvtestView1.rangeSize}"
                 summary="Emplyee Organizational Chart"/>
  <dvt:link linkType="orthogonalRounded" id="l1"/>
  <dvt:node type="model.HvtestView" width="233" height="233" id="n1">
    <f:facet name="zoom100">
      <af:image source="#{node.Image}" inlineStyle="width:85px;height:120px;"
                       inlineStyle="font-weight:bold;font-size:14px"
                       id="ot1"/>
      <af:outputText value="#{node.Firstname}"
                     inlineStyle="font-size:14px"
                     id="ot2"/>
      <af:outputText value="#{node.Lastname}"
                     inlineStyle="font-style:italic;font-size:14px"
                     id="ot3"/>
      <dvt:panelCard effect="slide_horz" id="pc1">
        <af:showDetailItem text="#{viewcontrollerBundle.CONTACT_INFO}"
                           id="sdi1">
        <af:panelFormLayout inlineStyle="padding:5px;" id="pfl1">
            <af:goLink text="#{viewcontrollerBundle.EMAIL}"
                      destination="mailto:#{node.bindings.Email.inputValue}"/>
          <af:panelLabelAndMessage label="#{viewcontrollerBundle.PHONE_NUMBER}"
                                   labelStyle="font-size:14px;color:#5A6A7A"
                                   id="plam3">
            <af:outputText value="#{node.Phone}"
                           inlineStyle="font-size:14px;color:#383A47" id="ot5"/>
          </af:panelLabelAndMessage>
          </af:panelFormLayout>
        </af:showDetailItem>
        <af:showDetailItem text="#{viewcontrollerBundle.REPORTING}" id="sdi2">
          <af:panelFormLayout inlineStyle="padding:5px;" id="pfl2">
            <af:outputText value="#{node.Title}"
                           inlineStyle="font-size:14px"
                           id="ot6"/>
          <af:panelLabelAndMessage label="#{viewcontrollerBundle.MANAGER}"
                                   labelStyle="font-size:14px" 
                                   id="plam4">
            <af:outputText value="#{node.Managerid}"
                           inlineStyle="font-size:14px;color:#383A47" id="ot7">
              <af:convertNumber groupingUsed="false"
                        pattern="#{bindings.HvtestView1.hints.Managerid.format}"/>
            </af:outputText>
           </af:panelLabelAndMessage>
           <af:panelLabelAndMessage label="#{viewcontrollerBundle.EMPLOYEE_ID}"
                                    labelStyle="font-size:14px" id="plam5">
             <af:outputText value="#{node.Id}"
                            inlineStyle="font-size:14px" id="ot8">
               <af:convertNumber groupingUsed="false"
                               pattern="#{bindings.HvtestView1.hints.Id.format}"/>
             </af:outputText>
           </af:panelLabelAndMessage>
           </af:panelFormLayout>
             </af:showDetailItem>
             <af:showDetailItem text="#{viewcontrollerBundle.ADDRESS}" id="sdi3">
             <af:panelFormLayout inlineStyle="padding:5px;" id="pfl3">
             <af:panelLabelAndMessage label="#{viewcontrollerBundle.ADDRESS}"
                                      labelStyle="font-size:14px" idd="plam6">
             <af:outputText value="#{node.Adress}"
                            inlineStyle="font-size:14px" id="ot9"/>
           <af:panelLabelAndMessage>
           <af:panelLabelAndMessage label="#{viewcontrollerBundle.STATE}"
                                    labelStyle="font-size:14px" id-"palm7">
             <af:outputText value="#{node.State}"
                            inlineStyle="font-size:14px" id="ot10"/>
           </af:panelLabelAndMessage>
           <af:panelLabelAndMessage label="#{viewcontrollerBundle.CITY}"
                                    labelStyle="font-size:14px" id="plam8">
             <af:outputText value="#{node.City}"
                            inlineStyle="font-size:14px" id="ot11"/>
           </af:panelLabelAndMessage>
         </af:panelFormLayout>
       </af:showDetailItem>
     </dvt:panelCard>
   </f:facet>
  </dvt:node>
</dvt:hierarchyViewer>

33.8.3 How to Create a Databound Search in a Hierarchy Viewer

The search function in a hierarchy viewer is based on the searchable attributes or columns of the data collection that is the basis of the hierarchy viewer data model. Using a query results collection defined in data controls in Oracle ADF, JDeveloper makes this a declarative task. You drag and drop an ExecuteWithParams operation into an existing hierarchy viewer component on the page.

Before you begin:

  1. You must have a databound hierarchy viewer component present on your page.

  2. Verify the query that retrieves the root node in the hierarchy viewer.

    For example, Figure 33-78 shows retrieving the root node by EMPNO column.

    Figure 33-78 Root Node Query

    Root node query
  3. Create a view object that performs the search.

    For example, Figure 33-79 shows the EmployeesSearchResults view object that performs the search based on the Job column in the data collection with a default value of % for matching any value, and a comparison value of = specifying an exact match against the column.

    Figure 33-79 EmployeeSearchResults View Object

    EmployeesSearchResults view object.

    For information about creating a view object, see Section 5.2.1, "How to Create an Entity-Based View Object."

To create a databound search with a hierarchy viewer:

  1. From the Data Controls panel, select the collection that corresponds to the query results and expand the Operations node to display the ExecuteWithParams operation.

  2. Drag the ExecuteWithParams operation and drop it onto the hierarchy viewer in the visual editor or onto the component in the Structure window. Alternatively, you can drag the parameter onto the hierarchy viewer.

  3. In the Create Hierarchy Viewer Search dialog that displays, use the Add icon to specify the list of results to display in the Search Results panel, and specify the following for each result:

    1. Display Label: Select the values for the headers of the nodes in the hierarchy. If you select <default>, then the text for the header is automatically retrieved from the data binding.

    2. Value Binding: Select the columns in the data collection to use for nodes in the tree for the hierarchy viewer.

    3. Component to Use: Select the type of component to display in the node. The default is the ADF Output Text component.

    After selecting an existing field, use the arrow icons (Up, Down, Top, Bottom) to reorder the results or use the Delete icon to delete that result.

  4. In the Operation dropdown list select the hierarchy root data collection to use when a search result is selected. Valid values include:

    • removeRowWithKey: Uses the row key as a String converted from the value specified by the input field to remove the data object in the bound data collection.

    • setCurrentRowWithKey: Sets the row key as a String converted from the value specified by the input field. The row key is used to set the currency of the data object in the bound data collection.

    • setCurrentRowWithKeyValue: Sets the current object on the iterator, given a key's value.

    • ExecuteWithParams: Sets the values to the named bind variables passed as parameters.

  5. In the Parameter Mapping table, use the dropdown list in the Results Attribute column to select the results collection attribute to map to the parameter displayed in the Hierarchy Parameter column.

Figure 33-80 shows the Create Hierarchy Viewer Search dialog that appears if you create a hierarchy viewer using data from a data collection named EmployeesSearchResults1.

Figure 33-80 Create Hierarchy Viewer Search Dialog

Create Hiearchy Viewer Search dialog.

At runtime, the search results are displayed in a table by Ename and Job. Figure 33-81 shows the resulting search results panel when the user enters "MANAGER" in the search box.

Figure 33-81 Hierarchy Viewer Search Results

Hierarchy viewer search results