For detailed descriptions of each data visualization use cases and examples, see the Map Component Use Cases and Examples section in Developing Web User Interfaces with Oracle ADF Faces.

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 End User and Presentation Features of Maps section in Developing Web User Interfaces with Oracle ADF Faces.

You can create a geographic map with a point theme to display specific locations in a map, identified by latitude and longitude or address. For example, a point theme might identify the locations of warehouses in a map. If you customize the style of the point that is displayed, you could choose to use a different image for a warehouse product count (high, acceptable, low) in a set of warehouses to differentiate them from each other.

To create a geographic map with a point theme, you first configure the base map and then bind a point 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. You can also layer a point theme on a base map that has already been configured and bound to another theme.

For example, the geographic map in Figure 41-7 has a point theme that identifies the location of warehouses and their product count levels in the United States.

Figure 41-7 Geographic Map with Point Theme

Description of "Figure 41-7 Geographic Map with Point Theme"

Before you begin:

It may be helpful to have an understanding of databound geographic maps. For more information, see Creating Databound Geographic Maps.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Data Visualization Components.

You will need to complete these tasks:

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

   Figure 41-8 shows an example where you could select the SWarehouseView1 collection in the Data Controls panel to create a geographic map with a point theme that displays an image to identify the location of each warehouse, styled to represent the product count level.

   Figure 41-8 Data Collection for Warehouse Location and Product Count

   
   Description of "Figure 41-8 Data Collection for Warehouse Location and Product Count"
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, complete the Create Geographic Map dialog. For more information, see How to Configure a Geographic Base Map. Otherwise, do one of the following:

   • Use the dropdown list to select the map configuration you wish to use

   • Click OK to accept the available map configuration

   • Click New to configure a new base map

   • Click Edit to modify the available map configuration

4. If you are layering a point theme on a base map that has already been configured and bound to another theme, in the Create dialog select Point Theme.
5. In the Create Point Map Theme dialog, in the Theme Id field, enter the unique identifier for the point map theme.
6. In the Location section, choose 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 ProductCount.

   • 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, acceptable, and low) that are matched to the values in the column that you select in the Data field. For more information, see 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 41-9 shows the completed Create Point Map Theme dialog for a geographic map with a point theme that displays an image representing the location and product count levels for each warehouse point.

Figure 41-9 Create Point Map Theme Dialog for Warehouse Product Counts

Description of "Figure 41-9 Create Point Map Theme Dialog for Warehouse Product Counts"

After you create a map point theme, you can further customize the style of the points that appear in the map to represent more detailed information. For example, the map point theme in Figure 41-7 uses a different image to represent the levels (high, acceptable, low) for the product count in each warehouse. For each different point style, use a mapPointStyleItem tag. For more information, see How to Create Point Style Items for a Point Theme.

1. In the Structure window, right-click the dvt:mapPointTheme tag and choose Insert inside the Point Theme > Point Style Item.
2. In the Point Style Item Properties window, set values as described Table 41-1.

   Table 41-1 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.

Creating a geographic map with a point theme 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

The example below shows the row set bindings that were generated for the geographic map with a point theme.

<bindings>
    <mapTheme xmlns="http://xmlns.oracle.com/adfm/dvt"></mapTheme>
    <mapTheme IterBinding="WorldProductInventory1Iterator"
              id="WorldProductInventory1"
              xmlns="http://xmlns.oracle.com/adfm/dvt">
      <mapThemeDataMap convert="false" mapThemeType="point">
        <data>
          <item value="AmountInStock"
                label="${adfBundle['view.ViewControllerBundle'].AMOUNT_IN_
                       STOCK}"/>
        </data>
        <item type="us_form_2" street="Address" city="City" state="State"
                   zipCode="ZipCode" label="WarehouseId"/>
      </mapThemeDataMap>
    </mapTheme>
    <mapTheme IterBinding="SWarehouseView1Iterator" id="SWarehouseView1"
              xmlns="http://xmlns.oracle.com/adfm/dvt">
      <mapThemeDataMap convert="false" mapThemeType="point">
        <data>
          <item value="ProductCount"
                label="${adfBundle['view.ViewControllerBundle'].PRODUCT_COUNT}"/>
        </data>
        <item type="lat_long" longitude="Longitude" latitude="Latitude"
              label="ProductCount"/>
      </mapThemeDataMap>
    </mapTheme>
  </bindings>

The example below shows the XML code generated on the JSF page for the geographic map and its point theme.

<dvt:map id="map" startingX="-104.15" mapServerConfigId="mapConfig1"
            baseMapName="ELOCATION.WORLD_MAP" mapZoom="3"
         inlineStyle="width:600px; height:375px;" startingY="42.09">
  <dvt:mapPointTheme id="mapPointTheme"
                     value="#{bindings.SWarehouseView1.geoMapModel}">
    <dvt:mapPointStyleItem maxValue="5.0"
                           shortLabel="#{viewcontrollerBundle.PRODUCT_COUNT_LOW}"
                           imageURL="/images/error.png" minValue="0.0"/>
    <dvt:mapPointStyleItem minValue="6.0" maxValue="7.0"
                           shortLabel="#{viewcontrollerBundle.PRODUCT_COUNT_OK}"
                           imageURL="/images/checkmark.png"/>
    <dvt:mapPointStyleItem minValue="8.0"
                           shortLabel="#{viewcontrollerBundle.PRODUCT_COUNT_HIGH}"
                           imageURL="/images/warning.png"/>
  </dvt:mapPointTheme>
</dvt:map>
<dvt:mapToolbar mapId="map" id="mt1"/>

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 Developing Web User Interfaces with Oracle ADF Faces.

3. After you finish data-binding the map point theme, use the Properties window 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}.

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

The example below shows the row set bindings that were generated for the color theme of the geographic map.

<bindings>
    <mapTheme IterBinding="WorldProductInventory1Iterator"
              id="WorldProductInventory1"
              xmlns="http://xmlns.oracle.com/adfm/dvt">
      <mapThemeDataMap convert="false" mapThemeType="color">
        <item type="location" value="State" label="State"/>
        <data>
          <item value="AmountInStock"
                label="${adfBundle['view.ViewControllerBundle'].STOCK_LEVELS}"/>
        </data>
      </mapThemeDataMap>
    </mapTheme>
  </bindings>

The example below 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.

<dvt:map id="map" startingX="-102.39" mapServerConfigId="mapConfig1"
         baseMapName="ELOCATION_MERCATOR.WORLD_MAP"
         mapZoom="3" inlineStyle="width:600px; height:375px;" startingY="40.27"
         summary="Geographic map with color theme">
  <dvt:mapColorTheme id="mapColorTheme" themeName="MAP_STATES_ABBRV"
                     value="#{bindings.WorldProductInventory1.geoMapModel}"
                     bucketCount="5" minColor="#ff0000"
                     maxColor="#00ff00" locationColumn="STATE_ABRV"/>
      </dvt:map>

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 Properties window, 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.

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

The example below shows the row set bindings that were generated for the pie graph theme of the geographic map.

<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>

The example below shows the XML code generated on the JSF page for the pie graph theme of the geographic map.

<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>

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

   Figure 41-20 shows the data collection for warehouse locations and product inventory levels.

   Figure 41-20 Data Collection for Warehouse Location and Inventory

   
   Description of "Figure 41-20 Data Collection for Warehouse Location and Inventory"
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 41-21 shows the Component Gallery with the USA states map layer selected.

   Figure 41-21 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 thematic map displayed in Figure 41-19, an area data layer is configured style USA states by warehouse product levels.

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 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 What You May Need to Know About Configuring Master-Detail Relationships.

   Figure 41-22 shows the completed Create Data Layer dialog.

   Figure 41-22 Create Area Data Layer Dialog

   
   Description of "Figure 41-22 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 41-23 shows the expanded Layer Browser after adding an area data layer and area to the map layer.

   Figure 41-23 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.

   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 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, ProductCount represents the warehouse product inventory levels by state.

       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 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 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 warehouse with a low product inventory level with a #DD1E2F 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, warehouse product inventory level data collection attribute, values include low, med, and high.

     • 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 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 41-24 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 41-24 Configure Area Dialog Attribute Groups Page

   
   Description of "Figure 41-24 Configure Area Dialog Attribute Groups Page"
7. Use the Layer Browser to add a global point data layer representing warehouse locations using the same data collection you used to create the thematic map. For detailed instructions, see How to Add Data Layers to Thematic Maps.
8. Use the Layer Browser to add a global point data layer representing customer addresses using a different data collection than the one you used to create the thematic map. For detailed instructions, see How to Add Data Layers to Thematic Maps. Figure 41-25 shows the data collection for customer locations.

   Figure 41-25 Data Collection for Customer Addresses

   
   Description of "Figure 41-25 Data Collection for Customer Addresses"
9. Use the Layer Browser to add and style a marker representing the customer locations in the global point data layer. For detail instructions, see Styling Areas, Markers, and Images to Display Data.

   Figure 41-26 shows the expanded Layer Browser for the thematic map in Figure 41-20.

   Figure 41-26 Thematic Map Layer Browser

   
10. Add and configure a data bound legend and labels associated with the styled points and areas. For detailed instructions, see Creating Databound Legends.

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.

The example below shows the bindings defined in the page definition file of the JSF page for the example thematic map in Figure 41-19.

<bindings>
    <tree IterBinding="WorldProductInventory1Iterator" id="WorldProductInventory1">
      <nodeDefinition DefName="model.WorldProductInventory" Name="WorldProductInventory10">
        <AttrNames>
          <Item Value="Address"/>
          <Item Value="AmountInStock"/>
          <Item Value="Category"/>
          <Item Value="CategoryId"/>
          <Item Value="City"/>
          <Item Value="Country"/>
          <Item Value="CountryCode"/>
          <Item Value="CountryId"/>
          <Item Value="Id"/>
          <Item Value="Id1"/>
          <Item Value="Id2"/>
          <Item Value="Id3"/>
          <Item Value="Id4"/>
          <Item Value="Latitude"/>
          <Item Value="Longitude"/>
          <Item Value="ProdName"/>
          <Item Value="ProductId"/>
          <Item Value="RegName"/>
          <Item Value="RegionId"/>
          <Item Value="ReorderPoint"/>
          <Item Value="State"/>
          <Item Value="WarehouseId"/>
          <Item Value="ZipCode"/>
        </AttrNames>
      </nodeDefinition>
    </tree>
    <tree IterBinding="SCustomerView1Iterator" id="SCustomerView1">
      <nodeDefinition DefName="model.SCustomerView" Name="SCustomerView10">
        <AttrNames>
          <Item Value="Address"/>
          <Item Value="City"/>
          <Item Value="CountryId"/>
          <Item Value="Id"/>
          <Item Value="Name"/>
          <Item Value="State"/>
          <Item Value="ZipCode"/>
        </AttrNames>
      </nodeDefinition>
    </tree>
    <tree IterBinding="SWarehouseView1Iterator" id="SWarehouseView1">
      <nodeDefinition DefName="model.SWarehouseView" Name="SWarehouseView10">
        <AttrNames>
          <Item Value="Address"/>
          <Item Value="City"/>
          <Item Value="CountryId"/>
          <Item Value="Id"/>
          <Item Value="Latitude"/>
          <Item Value="Longitude"/>
          <Item Value="ManagerId"/>
          <Item Value="Phone"/>
          <Item Value="ProductCount"/>
          <Item Value="State"/>
          <Item Value="ZipCode"/>
        </AttrNames>
      </nodeDefinition>
    </tree>
  </bindings>

The example below shows the code inserted in the JSF page for the example thematic map in Figure 41-19.

<dvt:thematicMap id="tm1" basemap="usa" animationOnDisplay="alphaFade"
                 summary="#{viewcontrollerBundle.THEMATIC_MAP_DISPLAYING_
                 WAREHOUSE_PRODUCT_INVENTORY_LEVELS}">
        <dvt:areaLayer layer="states" id="al1">
          <dvt:areaDataLayer id="dal1"
                             value="#{bindings.SWarehouseView1.collectionModel}"
                             var="row">
            <dvt:areaLocation name="#{row.State}" id="al2">
              <dvt:area id="a1" shortDesc="#{row.ProductCount} units">
                <dvt:attributeGroups id="ag1" type="color"
                                     value="#{row.ProductCount le 5 ? 'low' :
                                     (row.ProductCount le 8 ? 'med' : 'high')}"
                                     label="#{row.ProductCount le 5 ? 'Low Product
                                     Counts' : (row.ProductCount le 8 ? 'Good
                                     Product Counts' : 'Surplus Product
                                     Counts')}">
                  <dvt:attributeMatchRule id="amr1" group="low">
                    <f:attribute name="color" value="#DD1E2F"/>
                  </dvt:attributeMatchRule>
                  <dvt:attributeMatchRule id="amr2" group="med">
                    <f:attribute name="color" value="#EBB035"/>
                  </dvt:attributeMatchRule>
                  <dvt:attributeMatchRule id="amr3" group="high">
                    <f:attribute name="color" value="#218559"/>
                  </dvt:attributeMatchRule>
                </dvt:attributeGroups>
              </dvt:area>
            </dvt:areaLocation>
          </dvt:areaDataLayer>
        </dvt:areaLayer>
        <dvt:pointDataLayer id="dpl1"
                            value="#{bindings.SCustomerView1.collectionModel}"
                            var="row">
          <dvt:pointLocation type="pointName" pointName="#{row.State}_
                             #{fn:toUpperCase(fn:replace(row.City, ' ', '_'))}"
                             id="pl1">
            <dvt:marker id="m2" fillColor="#00000" opacity="1.0" shape="human"
                        scaleX="4.0" scaleY="4.0"
                        shortDesc="#{row.Name}">
              <f:attribute name="legendLabel" value="Customer Location"/>
            </dvt:marker>
          </dvt:pointLocation>
        </dvt:pointDataLayer>
        <dvt:pointDataLayer id="dpl2"
                            value="#{bindings.SWarehouseView1.collectionModel}"
                            var="row">
          <dvt:pointLocation type="pointXY" pointX="#{row.Longitude}"
                             pointY="#{row.Latitude}" id="pl2">
            <af:image id="img1" source="/images/normalHouse.gif"
                      shortDesc="#{row.Address}, #{row.City} #{row.ZipCode}">
              <f:attribute name="legendLabel" value="Warehouse Location"/>
            </af:image>
          </dvt:pointLocation>
        </dvt:pointDataLayer>
        <dvt:legend id="l1">
          <dvt:showLegendGroup id="slg1" label="Customer and Warehouse Locations">
            <dvt:legendSection source="dpl1:m2" id="ls2"/>
            <dvt:legendSection source="dpl2:img1" id="ls1"/>
          </dvt:showLegendGroup>
          <dvt:showLegendGroup id="slg2" label="Warehouse Product Levels">
            <dvt:legendSection source="al1:dal1:ag1" id="ls3"/>
          </dvt:showLegendGroup>
        </dvt:legend>
      </dvt:thematicMap>

Once you have created a data bound thematic map 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:

• Add additional map layers in the base map geographical hierarchy to the thematic map.

• Define a custom map layer in the geographical hierarchy of the base map, using lower level regions to aggregate the regions in the custom layer. For more information, see How to Define a Custom Map Layer.

• Add, edit, or delete area or point (global or map layer specific) data layers. For more information, see How to Add Data Layers to Thematic Maps.

• Add, edit, or delete stylized areas or markers. For more information, see Styling Areas, Markers, and Images to Display Data.

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 Developing Web User Interfaces with Oracle ADF Faces.

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.

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 Toronto, 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 Properties window.

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 41-37 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 41-37 Thematic Map Master and Detail Table View

Description of "Figure 41-37 Thematic Map Master and Detail Table 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.

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 41-38. 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 How to Configure Drilling in Thematic Maps.

Figure 41-38 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 Developing Web User Interfaces with Oracle ADF Faces.

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 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. 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 data bind 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 41-39 shows the completed Create Custom Layer dialog.

Figure 41-39 Create Custom Layer Dialog

Description of "Figure 41-39 Create Custom Layer Dialog"

Figure 41-40 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 How to Add Data Layers to Thematic Maps.

Figure 41-40 Custom Map Layer in Layer Browser

The example below shows the code inserted in the JSF page

<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 41-38, you will need to do the following:

• Configure the thematic map to support drilling. For more information, see How to Configure Drilling in Thematic Maps.

  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 without configuring data display for either layer.

• Add and configure an area data layer for the county data view. For more information, see How to Add Data Layers to Thematic Maps.

• Add and style area components to display the related data for each map layer. For more information, see Styling Areas, Markers, and Images to Display Data.

• Configure the thematic map legend. For more information, see Creating Databound Legends.

The example below shows sample code for using a custom layer in a thematic map.

<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>

1. In the Structure window, select the dvt:thematicMap component.
2. In the Properties window, 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:

   • Click 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, click the Edit icon to confirm binding to the data control.

   • In the Properties window, 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:

   • Click 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, click the Edit icon to confirm the styling of the area.

<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>

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 41-41 shows a legend with a disclosable section for map areas and a marker.

Figure 41-41 Legend with Disclosable Section and Marker

Description of "Figure 41-41 Legend 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 41-42 shows a legend with attribute groups for color, shape, fill pattern, opacity, and size with separators between each section.

Figure 41-42 Legend with Attribute Groups

Legends can be displayed in both Flash (default) and PNG image formats and both formats support locales with right-to-left display. 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. The example below 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.

<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. The example below 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.

<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.

<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 Developing Web User Interfaces with Oracle ADF Faces