Location Intelligence Component

(1)

Location Intelligence

Component

version 1.0

for Business Objects™ XI 3.0

(2)

permission of Pitney Bowes Software Inc., One Global View, Troy, New York 12180-8399.

Americas: Phone: (518) 285-6000 Fax: (518) 285-6070 Sales: (800) 327-8627 Government Sales: (800) 619-2333 Technical Support: (518) 285-7283 Technical Support Fax: (518) 285-6080 www.mapinfo.com UK and EMEA: Phone: 44 1753 848200 Fax: 44 1753 621140 Technical Support: 44 1753 848229 www.mapinfo.co.uk Asia Pacific: Phone: 1 800 648 899 Fax: 61.2.9439.1773 Technical Support: 61 7 3844 7744 www.mapinfo.com.au

Contact information for all Pitney Bowes MapInfo offices is located at: http://www.mapinfo.com/contactus.

Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark.

(3)

Part 1: Getting Started . . . 7

Chapter 1: Getting Started With the Location Intelligence Component . . . 9

Overview . . . .10

Customizing the LIC For Your Business Needs. . . .10

Configuring Locale Settings . . . .10

Configuring the Drill Tool . . . .11

Using Sample Data . . . .11

Configuring User Groups for Mapping Reports . . . .12

Configuring your Application Server for Optimal Performance . . . .13

Setting Default JVM Heap Sizes . . . .13

Typographical Conventions . . . .15

Terminology. . . .15

Chapter 2: Map Displays on Dashboards . . . 17

Web Page Analytics . . . .18

Creating a Web Page Analytic . . . .19

Understanding the Report URL Parameters . . . .22

Understanding Map Display Positioning and Sizing. . . .23

Understanding Anti-Aliasing. . . .24

Sample Report URLs for Web Page Analytic Maps . . . .25

Optional Configurations for Map Displays . . . .26

Part 2: Configuring Reports and Maps Using Managed Beans . 31

Chapter 3: Data Binding and Theming Managed Beans . . . 33

Overview of the bifaces-config File . . . .34

About the Syntax . . . .36

Internal Operations Managed Beans . . . .37

Data Binding Managed Beans . . . .38

(4)

Internal Match Managed Beans . . . 50

Geographic External Bind Managed Beans. . . 51

Theming Managed Beans. . . 54

Ranged Theme Managed Beans . . . 54

Fixed Range Theme Managed Beans . . . 57

Individual Value Managed Beans . . . 60

Charting Managed Beans . . . 62

Pie Chart Theme Managed Beans. . . 63

Stacked Bar Chart Theme Managed Beans . . . 64

Side-by-Side Bar Chart Theme Managed Beans. . . 64

Zoom Distance Managed Beans . . . 65

Chapter 4: Customizing Data Binding and Theming. . . 67

Understanding Binding . . . 68

Creating Universes . . . 69

Binding Internal Data . . . 70

Binding External Data. . . 73

Additional Binding Customizations . . . 77

Overriding the Drill Hierarchy. . . 77

Defining the Zoom Range on Labels . . . 80

Customizing the Default Zoom Levels on Labels. . . 82

Customizing Generic Report Styles for Layers . . . 83

Understanding Custom Thematics . . . 83

Theme Types . . . 87

Applying Colors to Themes . . . 89

Disabling Auto-Theming on Maps . . . 90

Creating Ranged, Fixed Range and Individual Value Themes . . . 91

Creating Individual Value Themes . . . 91

Creating Ranged Themes . . . 94

Creating Fixed Range Themes . . . 96

Creating Themes Using Named Styles . . . 98

Associating Legend Swatch Shapes With Themes . . . 103

Creating Pie and Bar Chart Themes . . . 105

Combining Multiple Types of Themes . . . 112

Chapter 5: Global Map Settings and Managed Beans. . . 117

Overview of the mapxtreme-mapping-faces-config File . . . 118

Beans that Handle Basic Mapping Settings . . . 118

About the Syntax . . . 119

(5)

Chapter 6: Customizing Global Map Settings and Defaults . . . 133

Organizing Your Mapping Layers . . . .134

Setting a Custom Map Size . . . .136

Customizing the Image Format . . . .137

Customizing the Default Theme. . . .138

Creating a Custom Layer . . . .140

Customizing the Default Legend . . . .142

Customizing the Default Legend Format . . . .142

Understanding Legend Swatch Shapes. . . .143

Customizing the Default Legend Swatch Shape . . . .144

Customizing the Selection Tools. . . .145

Customizing Zoom Distances on Maps . . . .149

Customizing the Click Tolerance on Map Tools. . . .152

Customizing the Info Tool . . . .153

Exposing Basemap Layer Data . . . .153

Configuring Printers . . . .154

Index of Managed Beans . . . 156

(6)

(7)

(8)

(9)

Getting Started With the

Location Intelligence

Component

This part of the Location Intelligence Component Administration Guide gives an overview of the Location Intelligence Component (LIC). It also provides details on configuring the LIC and your application server for optimal performance with Business Objects.

In this chapter:

Overview . . . .10

Customizing the LIC For Your Business Needs . . . .10

Configuring your Application Server for Optimal Performance .13

Typographical Conventions . . . .15

Terminology . . . .15

(10)

Overview

The Location Intelligence Component (LIC) for Business Objects provides a interface between Business Objects and MapXtreme Java. The result is a visual, geographic representation of a Business Objects report using an interactive mapping page and tools to manipulate the map. LIC uses two configuration files to present data on maps:

• mapxtreme-mapping-faces-config • bifaces-config

These two XML files both use a JSF configuration structure. The mapxtreme-mapping-faces-config file defines general mapping parameters such as map size and width, mapping tool properties and default theming. The bifaces-config file is primarily a sample file that allows you to define custom data binding and custom themes between MapInfo and Business Objects.

Customizing the LIC For Your Business Needs

This section includes the following information on processes that significantly improve the performance of the LIC:

• Configuring Locale Settings on page 10

• Configuring the Drill Tool on page 11

• Using Sample Data on page 11

• Configuring User Groups for Mapping Reports on page 12

Configuring Locale Settings

The LIC for Business Objects supports the following 8-bit languages for language and number format settings: • Dutch • English • French • German • Italian • Simplified Chinese • Spanish • Swedish

Note The accompanying LIC documentation is only available in English. Business Objects locale preferences can be set in a variety of ways: • Through the server’s operating system

• Through each workstation’s operating system

• Through the Business Objects User Preferences, where a language is specified

• Through the Business Objects User Preferences, where Infoview is directed to accept the browser’s locale

(11)

The LIC supports Business Objects locale settings using the localeProvider managed bean in the bifaces-config file. Locale and language settings are inherited from the InfoView Preferences. Since the settings draw the browser’s locale language and number settings, the LIC automatically applies the browser’s locale language and number settings to the mapping interface.

While no changes are necessary for language support to be applied, your users can select a specific language on their InfoView Preferences from the list of supported locales; just as Business Objects is updated to reflect the selected language, so also the LIC interface automatically reflects a supported language selection.

Configuring the Drill Tool

The LIC toolbar offers a Drill tool that functions similarly (but not identically) to Business Objects's native drilling tool. Using an external match bean in the bifaces-config file, you can override drill paths or you can set the tool to drill to specific custom reports, if desired.

To custom define drilling for your users’ reports, configure the drillPath property and the drillReport property, found by default in the regionNamesExternalMatch managed bean. This is an optional configuration, where you can update one or both properties, as desired.

For more information on configuring this bean and its properties for drilling, see the section

Overriding the Drill Hierarchy on page 77.

Using Sample Data

The LIC CD provides a Data directory of sample data for the purpose of simulating reporting and mapping in Business Objects immediately after product installation. This Data directory contains basic data on US state, county and Zip code boundaries, as well as some city-level data. This data is meant to be used to validate the installation against the Business Objects tutorial data sample configurations in the default bifaces-config file and is used by the default named layers and basemap installed in your /resources directory. The bifaces-config file also contains a sample universe called eFashion, which includes basic data bindings on Store Name, City and Postal Code dimensions.

Testing the reporting and mapping capabilities allows you to confirm that the installation was successful and lets you practice using the LIC tools before you begin working with real Business Objects data.

Once you have tested your newly installed product against the sample data, you can either delete the Data directory or you can retain these files for future use. You can use this sample data three ways:

• Familiarize yourself with creating additional named resources using Map Manager • Configure a custom basemap or layers using the mapxtreme-mapping-faces-config file • Configure additional bindings and themes using the bifaces-config file

If you decide to continue using the sample data to test against your company’s configurations, there are a variety of suggested implementations provided in this guide. For information on testing your installation against the sample data, see the Installation Guide.

(12)

Configuring User Groups for Mapping Reports

By default, the LIC allows all users to view report data in a table format as well as geographically on a map. However, some companies require restrictions on this functionality, where only those users included in a defined User Group can map reports. This section explains how to configure an existing Business Objects User Group. Once the User Group is configured in the LIC, only users included in this group have access to the mapping capability; all other users are excluded. In this case, the interface offered to excluded users displays disabled Map mode and Map & Report mode buttons. You can configure multiple User Groups for mapping, if required.

Note The User Group must exist in Business Objects before you can configure it for mapping. To configure an existing User Group for mapping reports:

1. Shut down your application server.

2. Open the lic.properties file in a text editor (for example, Notepad). This file is found in <domain-directory>\configs

3. Replace the default value Mapping with the name of an existing User Group, where users whom you want to provide the mapping functionality are defined:

mappingGroupList=AcmeMapping

4. If you want to define multiple User Groups, separate each group with a pipe character: mappingGroupList=AcmeMapping|AcmeAdmin

5. Save the lic.properties file and close it.

6. Restart your application server to recognize the changes.

The LIC offers the mapping feature only to users defined in this User Group; the mapping menu commands are disabled on an excluded user’s Business Objects toolbar, as illustrated below.

(13)

Configuring your Application Server for Optimal Performance

Setting Default JVM Heap Sizes

The Java Virtual Machine (JVM) uses multiple predefined memory spaces for various types of memory management. The main space used by the LIC is heap size. You should set the default size for this space to optimize your LIC performance. For most installations, configure your application server to use 512 MB of heap space.

This section provides instructions for updating the recommended values for each of the supported application servers. For more information on setting default JVM heap sizes, visit the following web sites:

For information on Tomcat application servers, visit

http://tomcat.apache.org/faq/performance.html For information on WebSphere application servers, visit

http://www.redbooks.ibm.com/abstracts/SG246392.html For information on WebLogic application servers, visit

(14)

For Tomcat application servers

To increase the heap size for a Tomcat application server:

1. Open the catalina.bat file or the catalina.sh file to set the heap size, found at Tomcat/bin/catalina.bat

2. Add one of the following lines near the top of the catalina script of Tomcat that runs the LIC. For UNIX environments:

CATALINA_OPTS=" -Xms512m -Xmx1024m" For Windows environments:

set CATALINA_OPTS=-Xms512m -Xmx1024m 3. Restart Tomcat for the changes to take effect.

For WebLogic application servers

To increase the heap size for a WebLogic application server:

1. Update the heap size to Xmx512m in the startWeblogic.cmd script on Windows or startWeblogic.sh script on UNIX.

This file is located in the following directory, where <WebLogic_home> is the directory where WebLogic is installed:

<WebLogic_home>\weblogic92\<server name>\domains\wl_server\bin 2. Edit your custom domain’s startup script (that is, the MEM_ARGS setting) as follows:

set MEM_ARGS= -Xmx1024m

3. Restart WebLogic for the change to take effect.

For WebSphere application servers

1. Start and log on to the WebSphere administrator console. The default URL is http://<host>:9090/admin

2. Expand the Servers item on the left-hand pane and select the server hosting the LIC. 3. Scroll down the Additional Properties menu under the Application Server page and select

Process Definition.

4. Scroll down the Additional Properties menu under the Process Definition page and select

Java Virtual Machine.

5. On the Java Virtual Machine page, set the Maximum Heap Size property to 1024. 6. Apply and save all changes.

(15)

Typographical Conventions

This guide uses the following typographical conventions.

Terminology

The following table provides definitions for all abbreviations, acronyms, and definitions of common location intelligence terminology used in this guide.

Text Formatting Meaning

<angle brackets> Angle brackets are used for text that acts as a placeholder for information you provide. For example, <string@string> represents an email address. You should replace string@string with the actual email address.

Italics Italicized formatting is used for book titles (for

example, User Guide).

Courier Courier font is used for text that you type (for example, a directory path or a URL).

Bold Bold formatting to indicate an instruction (for

example, clicking a button, selecting an option or pressing a key). Bold is also used to differentiate a directory from a file, in directory structure illustrations.

Term Definition

bifaces-config XML-based configuration file where business intelligence-related settings are defined. These settings are defined via JSF managed beans.

binding The combination of grid data and a spatial datasource to display report information on a map. Binding can be internal (that is, all data for the bind is found within a single report) or external (where the

datasource—for example, a TAB file—is separate from the report). external binding

external match internal match internal binding

Defines how to perform a binding between a report and a spatial data source.

(16)

JavaServer Faces (JSF)

A specification that defines an SDK/framework for building Java-based web applications. JSF is a component of the J2EE specification as of version 1.4.

label A text annotation of an object on a map, such as the name of a street. layer The basic building blocks of maps in MapInfo products. A map typically

consists of several superimposed layers (for example, a layer of street data superimposed over a layer of county or ZIP code boundaries). Each layer contains uniquely specific data, and they can be viewed, hidden, and rearranged as needed depending on the desired view. legend Describes the different graphic styles or colors used to show data in a

thematic map display, such as different colors to show different populations per State.

managed bean A Java class with getters and setters by JSF to simplify configuring a web application via the faces-config.xml file.

theme

thematic display thematic mapping

The process of shading a map according to a particular theme. The theme is usually based on a specific element of data. Thematic mapping allows visualization and trend highlighting in report data that would be less clear visually through a table, graph, or chart.

The most common example of a thematic map is a weather map, where areas shaded red are hot and areas shaded blue are cool or cold.

Themed data displays range from colored areas, pattern-filled areas, or various symbols.

(17)

Map Displays on

Dashboards

In addition to being able to view maps in a desktop environment, your users can also view maps on a single dashboard or in a web page analytic. This chapter provides details on customizing map displays in the dashboard environment.

In this chapter:

Web Page Analytics . . . .18

Understanding the Report URL Parameters . . . .22

Understanding Map Display Positioning and Sizing. . . .23

Understanding Anti-Aliasing . . . .24

Sample Report URLs for Web Page Analytic Maps. . . .25

Optional Configurations for Map Displays . . . .26

(18)

Web Page Analytics

The Location Intelligence Component (LIC) lets you present your mapped report data in dashboard panes called Web Page Analytics. Unlike regular Business Objects dashboard map presentations, an LIC Web Page Analytic provides a map view only; the report view remains hidden.

The LIC’s Web Page Analytics are based on a URL. You can construct a URL to create three distinct mapping pane presentations:

• A basic map

(19)

• A legend

The type of pane presentation is drawn from the appropriate JSF page. For a basic map, your URL uses the MapImage.jsf; for a map with controls you include the miDashboard.jsf; legends reference the LegendImage.jsf.

The next section provides details on how to create an LIC Web Page Analytic. For more details on the URL parameters, see the section Understanding the Report URL Parameters on page 22.

Creating a Web Page Analytic

To create an LIC Web Page Analytic:

1. Open the dashboard on which you want to create your new Web Page Analytic.

2. Click the Edit Dashboard button. The Analytic Toolbox opens.

(20)

3. Drag the Web Page Analytic option onto the dashboard.

4. Move your mouse over the Web Page Analytic title bar, then click the Edit button . The Edit Contents window appears.

(21)

5. On the Content tab, enter the URL to the report, with any required formatting parameters, in the

Enter the web page URL field.

For a list of valid parameters and their uses, see the table Report URL Parameters on page 22. 6. Click OK.

7. Your new map appears on the dashboard.

8. Resize the image as follows:

• Resize the map using the URL parameters on the Content tab.

• Resize the Web Page Analytic pane using the Layout, Snap to Grid, and Grid Size tools. 9. When you are satisfied with your map, click Save, then click OK to confirm.

10. Click the Exit Edit Mode button.

(22)

Understanding the Report URL Parameters

Every Business Objects report displayed in a Web Page Analytic has a report URL. Associated maps are dependent on the parameters in the report URL. Using the report URL parameters, you can customize the map positioning, which mapping theme to use and whether to apply anti-aliasing. The table below provides a description for all valid parameters in a report URL. The sections following the table offer more details on how to use the parameters, both individually and in combinations.

To view sample URLs, see the section Sample Report URLs for Web Page Analytic Maps on page 25.

Report URL Parameters

Parameters Description

reportID The unique identifier for a Business Objects report. This parameter is required and is automatically generated by Business Objects; all other parameters are optional. To access the reportID parameter, click the report Properties link on the InfoView list of reports and view the properties—this parameter is named the Document ID.

mapID The unique map identifier used to bind a report to a map and a map to a legend. Valid values are 1 and greater.

antialias The rendering quality of the map. This parameter only applies when MapXtreme is used to render map images. By default, the parameter is set to true; to deactivate, set the parameter to false.

column Identifies the column in the report against which to apply a theme on the map. Valid values are columns representing attributes and custom themes.

mapHeight The height of the map image in pixels. This parameter is defined in combination with the mapWidth parameter. mapWidth The width of the map image in pixels. This parameter is

(23)

Understanding Map Display Positioning and Sizing

You can impose a variety of positioning parameters on your users’ map displays, depending on your company’s requirements. Most positioning parameters are defined as part of a paired combination. There are several possible configuration options for positioning the map display:

• Use the default mapHeight and mapWidth • Define a custom mapHeight and mapWidth • Define a map position parameter

By default, maps present all geographic objects identified in the report.

Note Once you have your map positioned and sized in the dashboard, we recommend you test how the report and map wraps in PDF. This is especially important if your users do not have report editing rights.

center The geographic centroid for map display, defined in the

format <longitude> <latitude> <coordsys> (for example, &center=90.1805 33.806563 epsg:4326).

position A shortcut parameter that combines a zoom and a center

variable, defined in the format <center>@<zoom> (for example,

&position =90.1805 33.806563 epsg:[email protected] mi)

Note The LIC does not currently recognize the zoom variable in this parameter.

Report URL Parameters(continued)

(24)

Understanding Anti-Aliasing

Anti-aliasing is a graphics filter operation that smooths out jagged lines and label images on maps, improving their appearance on the web. The process uses graduated shading in the pixellation, rather than the stark black to white shading. For example, the map on the left does not use anti-aliasing. On the right is the same map, with anti-aliasing applied. Notice how the roadways and the labels are softened, making them easier to view and read, and therefore more visually appealing.

Anti-aliasing is most effective when used with map images that contain many curved lines, irregular region areas and text objects. There are several benefits to anti-aliasing:

• Smoother fonts

• More rounded edges in maps • Text appears more like printed type

Anti-aliasing requires a slightly longer processing time, so the antialias property is set to false by default. To take advantage of anti-aliasing on your users’ maps, include the antialias parameter in the report URL, as described in the Report URL Parameters table.

(25)

Sample Report URLs for Web Page Analytic Maps

This section provides a series of sample report URLs using combinations of the parameters listed in the Report URL Parameters table. A unique mapID, mapWidth and mapHeight parameters are defined for most of the samples here. The sizing parameters produce compact maps and are useful if you have more than one pane on your dashboard; for a single map, you can refine the parameter settings to suit the particular map. Typically, a base URL would include a unique mapID and sizing parameters.

Default mapID

This sample demonstrates a mapID that uses the reportID value, by default.

/AnalyticalReporting/AnalyticalReporting/jsp/MapImage.jsf?reportID=2654

&mapWidth=300&mapHeight=300

Defining a Unique mapID

This sample demonstrates a user-defined mapID value.

/AnalyticalReporting/jsp/MapImage.jsf?reportID=2654&mapID=01&mapWidth=300 &mapHeight=300

Adding a Toolbar

This sample demonstrates a map bind that adds the mapping toolbar to the panel. /AnalyticalReporting/jsp/miDashboard.jsf?reportID=2654&mapID=16 &mapWidth=300&mapHeight=300

Defining a Map Center

This sample demonstrates a map center tied to a latitude/longitude location.

/AnalyticalReporting/jsp/MapImage.jsf?reportID=16794&mapID=3333 &mapWidth=300&mapHeight=300&center=-70.1805 33.806563 epsg:4326

Defining a Map Location

This sample demonstrates a simplified version of the sample above, using the location parameter rather than the zoom and center parameters.

Note The LIC does not currently recognize the zoom variable in this parameter. /AnalyticalReporting/jsp/MapImage.jsf?reportID=16794&mapID=3332

(26)

Defining a Theme on a Column of Report Data

This sample returns a map image using a default theme on the Revenue column of report data. /AnalyticalReporting/jsp/MapImage.jsf?reportID=2654&column=Revenue

&mapWidth=300&mapHeight=300

Including a Map Legend

This sample returns a map in one pane and its associated legend in a second pane. You must identify the map with which the legend is associated. In addition, since legends are always associated with themed maps, you must identify the report column on which you want the theme. /AnalyticalReporting/jsp/MapImage.jsf?reportID=2654&column=Revenue &mapWidth=300&mapHeight=300

/AnalyticalReporting/jsp/LegendImage.jsf?reportID=2654&mapID=22 &column=Revenue&mapWidth=300&mapHeight=300

Applying Anti-Aliasing

This sample returns a map image with anti-aliasing applied.

/AnalyticalReporting/jsp/MapImage.jsf?reportID=26548&mapWidth=300 &mapHeight=300&antialias=true

Optional Configurations for Map Displays

You can use several parameters to further define your map image in your report. The default theme is defined in the mapxtreme-mapping-faces-config file, while custom themes are defined in the bifaces-config file. You may also want to change the image format (the default mimetype is GIF) to see if this improves your image quality. However, this is a global change and affects all images, so you should test other images to confirm that you have not introduced a more serious problem with this change. See the section Customizing the Image Format on page 137 for more information about this configuration.

Finally, you can use Map Manager to create custom styles for your map images, using the styles provided in the directory /resources/customstyles. For information on custom styles, see the Location Intelligence Component Map Manager Guide.

(27)

Advanced Theme Properties

In this section, tables of advanced theme properties are provided for customizing your maps. You can customize range colors, styles, distribution types, and the number and size of your theme ranges using these properties. For example, the following example defines an Equal Range theme with four ranges using a yellow to blue color scheme.

/AnalyticalReporting/jsp/MapImage.jsf?reportID=5207&mapWidth=400

&mapHeight=300&beginColor=Yellow&endColor=Blue&distributionType=EqualRange &numRanges=4

For more information on any of these themes or their properties, see the section Theming Managed Beans on page 54.

Ranged Theme Properties

Property Description

baseStyle The name of a style to be used as the base style for all theme ranges.

beginColor The color to use for the first range. The color must be a java.awt.Color constant (for example: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white, or yellow).

beginStyle The named style you want to use for the first range.

distributionType The type of distribution you want to use in your theme (Equal Count, Equal Ranges, Natural Break, Standard Deviation or Custom Ranges).

endColor The color to use for the last range. The color must be a java.awt.Color constant (for example: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white, or yellow).

endStyle The named style you want to use for the last range.

(28)

Fixed Range Theme Properties

baseStyle The name of a style to be used as the base style for all theme ranges.

colorN The color to use for range N, where N is a 0-based number

(for example: color0=blue, color1=red).

The color must be a java.awt.Color constant (for example: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white, or yellow).

rangeN The upper-bound breakpoint you want to use for range N,

where N is a 0-based number (for example: range0=10000, range1=20000).

styleN The named style you want to use for range N, where N is a

0-based number.

Individual Value Theme Properties

baseStyle The name of a style to be used as the base style for all theme values.

colorN The color to use for value N, where N is a 0-based number

(for example: color0=blue, color1=red).

The color must be a java.awt.Color constant (for example: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white, or yellow).

styleN The named style you want to use for value N, where N is a 0-based number.

valueN The specific value from the column you are creating a theme on for which you want to create a custom style, where N is a 0-based number.

(29)

Legend Properties

Parameter Description

width The width in pixels for your legend image.

height The height in pixels for your legend image.

format The file format (mime-type) to use to render the legend (png, jpg, or jpeg).

(30)

(31)

Part 2: Configuring Reports and Maps

Using Managed Beans

(32)

(33)

Data Binding and

Theming Managed Beans

This chapter identifies all managed beans involved with data binding between the LIC and Business Objects, and all defined and sample managed beans useful for theming. The binding and theming beans are defined in the bifaces-config file, in a prescribed order. However, this chapter provides details on these two types of beans separately, for clarity. As a result, this chapter is divided as follows:

Data Binding

Internal Operations Managed Beans . . . .37

Data Binding Managed Beans. . . .38

Internal Match Managed Beans. . . .50

External Match Managed Beans . . . .42

Geographic External Bind Managed Beans. . . .51

Theming

Theming Managed Beans . . . .54

Ranged Theme Managed Beans . . . .54

Fixed Range Theme Managed Beans . . . .57

Individual Value Managed Beans . . . .60

Charting Managed Beans . . . .62

Pie Chart Theme Managed Beans. . . .63

Stacked Bar Chart Theme Managed Beans . . . .64

Side-by-Side Bar Chart Theme Managed Beans . . . .64

(34)

Overview of the bifaces-config File

The bifaces-config file is a skeletal xml file. This file contains two required managed beans and a subset of sample beans on which you can build your customizations. These beans define the information needed to map Business Objects reports to geographic data. Several sample beans are included in this guide which are not defined in the bifaces-config file; you can add any of these beans to the file, in any order. We recommend you maintain a logical order, where the binding beans and the theming beans are separated but all associated elements remain together.

Note This file contains paths that must match the local installation of the Location Intelligence Component (LIC).

(35)

Understanding the Managed Bean Hierarchy

The following illustration demonstrates the nesting of managed beans in the sample bifaces-config file, provided with the LIC. A plus symbol (+) indicates the bean contains a pointer to another bean; a minus symbol (-) indicates no further pointers.

The biTool managed bean and the universesBean managed bean are required for data binding. The biTool bean contains a pointer to the universesBean bean, which you can build from the sample provided. The universesBean bean contains pointers to external and internal match beans, which in turn contain pointers to managed beans involving such details as geographic data and theming. With these beans, you can define any number of internal binding and external bindings.

Within the file, the theme beans should be organized within the associated match or binding beans, but all associated themes should remain together, for simplicity.

The instances, naming conventions, and hierarchy of your managed beans will vary depending on the customizations performed. - localeProvider + biTool universes + universesBean + XtremeSampleUniverse (sample) externalMatches + countriesExternalMatch (sample) geoContent - countriesGeoParams (sample) + regionsExternalMatch (sample) geoContent - regionsGeoParams (sample) + postalcodesExternalMatch (sample) geoContent - postalcodesGeoParams (sample) + eFashion (sample) externalMatches + storesExternalMatch (sample) geoContent - storesGeoParams (sample) + citiesExternalMatch (sample) geoContent - citiesGeoParams (sample) + regionNamesExternalMatch (sample) geoContent - regionsGeoParams (sample) themes - salesStateTheme1 (sample) - salesStateTheme2 (sample) + salesStateTheme3 (sample) - sales1Bin (sample) - sales2Bin (sample) - sales3Bin (sample) internalMatches - LatLongInternalMatch (sample)

(36)

The rest of this chapter contains information on all of the managed beans found in the bifaces-config file. Each section includes a description of a single managed bean. All associated classes, inheritance, properties and some sample code are also included for each bean.

About the Syntax

Use the following guidelines when customizing the bifaces-config file:

• All changes should be made using a proper text editor, where classes, properties and values are color-coded. Errors are much easier to spot and debug.

• Order of elements is set. Do not change the order unless you are reordering a list of property values. For example, the order of the value elements listed below is a matter of personal preference, not a syntax requirement.

<list-entries>

<value>Europe</value> <value>Post Codes</value> </list-entries>

On the other hand, if you rearrange any of the following lines of code, the bean no longer recognizes the reordered element.

<managed-bean> <managed-bean-name>LatLongInternalMatch</managed-bean-name> <managed-bean-class> com.mapinfo.jsf.controls.bi.InternalMatchBean </managed-bean-class> <managed-bean-scope>none</managed-bean-scope> <managed-property> <property-name>name</property-name> <value>Locations</value> </managed-property>

• Beans and bean properties both can be either required or optional. Each section in this chapter identifies a bean’s required status immediately following the bean description. If the Required status is Yes, the bean must be defined. The required status for all bean properties are identified in the tables using square brackets: if a property is named within square brackets (for example,

[labelColumn]), defining the property is optional. If no brackets are used (for example, name), the property is required when the bean is defined. Do not include the brackets when specifying optional elements.

(37)

• Values (<value></value>) are strings. Elements in angle brackets may be any of the types found in the table below.

Internal Operations Managed Beans

Value Type Description

boolean Valid values are true and false. If the bean is

defined, this value must be set.

const Value must be all capitals, optionally

separated by _ (for example, MAXSIZE, USER_ID).

float Any number, including zero and negative

numbers.

integer Any positive number.

string Common English text. Sometimes the string is

a URL to a directory installed with the LIC, and sometimes the string is text displayed on the interface to users.

localeProvider

Description Identifies to the LIC which locale data to implement. Locale data is defined on the user’s Preferences settings.

This bean must not be removed or modified.

Required Yes

Class com.mapinfo.jsf.bo.BOLocaleProvider

Scope session

reportManager

Description Provides a session-level cache of the BOBIToolBean. This bean must not be removed or modified.

Required Yes

(38)

Data Binding Managed Beans

For sample code and assistance in doing external and internal binds, see the next chapter, Customizing Data Binding and Theming on page 67.

Scope session

Parent biTool

reportManager (continued)

reportFactory

Description Responsible for getting the correct MIReport from the reportManager bean. This bean must not be removed or modified.

Required Yes

Class com.mapinfo.jsf.bo.MIBOReportManager

Scope session

Parent biTool

biTool

Description The top level bean. This bean holds all necessary information for creating the bindings for all reports.

Required Yes

Class com.mapinfo.jsf.bo.BOBIToolBean

Scope request

Sample

Children XtremeSampleUniverseeFashion

Derived from the property universes.

Properties [autoThemeFirstMetric]

Themes automatically on the first attribute in a report. The biTool checks for custom theming on the first attribute before applying the default theme.

(39)

[addInternalLayerTool]

Defines the class used for an internal bind, as follows:

com.mapinfo.jsf.bo.mapxtreme.BOMapXtremeAddInternalLayerTool This property should not be modified.

[addExternalLayerTool]

Defines the class used for an external bind, as follows:

com.mapinfo.jsf.bo.mapxtreme.BOMapXtremeAddExternalLayerTool This property should not be modified.

[reportStyle]

Defines the default or base report style for layers created in the map. This default path is taken from the <domain-directory>/resources directory. If you need to update this parameter, refer to the Location Intelligence Component Map Manager Guide for information on named resources.

Sample Default: /customstyles/bi/report Type: string

[universeName]

The name of the universe. This property is a placeholder only and should not be modified. Sample Default: Xtreme Sample Universe Type: string

[universes]

Contains the value universesBean.universes, which references the universesBean managed bean. The universesBean contains a list of all user-defined Business Objects universes.

biTool (continued)

universesBean

Description A list of universes you have defined for use with your LIC. This bean should not be modified.

Required Yes. In addition, at least one universe must be defined in the universes property.

Class com.mapinfo.jsf.controls.bi.UniverseBean

Scope application

(40)

Sample Children

XtremeSampleUniverse eFashion

Both derived from the property universes.

Properties universes

Identifies all defined Business Objects universes. This property contains the two sample universes XtremeSampleUniverse and eFashion. All your universes must be identified in this property to be recognized by the LIC.

universesBean (continued)

XtremeSampleUniverse

Description A sample universe, containing a list of the objects from Business Objects that identify where geographic data and details are stored.

Required No, but at least one universe must be defined.

Class com.mapinfo.jsf.controls.bi.UniverseBean Scope application Parent universesBean Sample Children countriesExternalMatch regionsExternalMatch postalcodesExternalMatch

All derived from the property externalMatches LatLongInternalMatch

Derived from the property internalMatches

Properties internalMatches

Creates a list of any internal matches that need to be configured for any of the objects that must be mapped using internal Business Objects spatial data. Internal matches are records that have embedded coordinates for locations, such as latitude and longitude. The coordinates for each record in the report, along with the primary key, must be included in the report. You cannot drill on this data. This property contains the class com.mapinfo.jsf.controls.bi.InternalMatchBean and the sample nested bean LatLongInternalMatch.

(41)

externalMatches

Creates a list of any external matches that need to be configured for any geographic objects that need external spatial data to bind to. The geographic data comes from an external table with a common key and usually come from TAB files. The criteria used to bind the report data with the geographic data must be defined in this configuration file. The criteria used should result in a strict one-to-one relationship between the report data and the geographic data to avoid multiple (and therefore ambiguous) or no geographic objects for a corresponding Business Objects object being returned. This property contains the class com.mapinfo.jsf.controls.bi.ExternalMatchBean and the sample nested beans countriesExternalMatch, regionsExternalMatch and postalcodesExternalMatch.

In the case where a report fits multiple match definitions, the following rules exist: • First, all internal matches are considered, in the order defined.

• After all internal matches are considered, all external matches are considered, in the order defined.

• The first match encountered using the order defined above and that fits the report is used.

XtremeSampleUniverse (continued)

eFashion

Description A sample universe, containing a list of the objects from Business Objects that identify where geographic data and details are stored.

Class com.mapinfo.jsf.controls.bi.UniverseBean

Scope application

Parent universesBean

Sample

Children storesExternalMatchcitiesExternalMatch regionNamesExternalMatch

(42)

External Match Managed Beans

This section includes a series of sample external managed beans (countriesExternalMatch, regionsExternalMatch, postalcodesExternalMatch, storesExternalMatch, citiesExternalMatch and regionNamesExternalMatch). It also includes two sample managed beans that can be associated with any external match bean, but which are not included in the bifaces-config file by default. There two beans are regionsLabelMinZoom and regionsLabelMaxZoom.

Properties externalMatches

Creates a list of any external matches that need to be configured for any geographic objects that need external spatial data to bind to. The geographic data comes from an external table with a common key and usually come from TAB files. The criteria used to bind the report data with the geographic data must be defined in this configuration file. The criteria used should result in a strict one-to-one relationship between the report data and the geographic data to avoid multiple (and therefore ambiguous) or no geographic objects for a corresponding Business Objects object being returned. This property contains the class com.mapinfo.jsf.controls.bi.ExternalMatchBean and the sample nested beans storesExternalMatch, citiesExternalMatch and regionNamesExternalMatch.

In the case where a report fits multiple match definitions, the following rules exist: • First, all internal matches are considered, in the order defined.

• After all internal matches are considered, all external matches are considered, in the order defined.

• The first match encountered using the order defined above and that fits the report is used.

eFashion (continued)

countriesExternalMatch

Description A sample external match, containing all the information necessary to map a Business Objects attribute to an external geographic data source (in this case the World Countries object value.)

Class com.mapinfo.jsf.controls.bi.ExternalMatchBean

Scope none

Sample Parent

XtremeSampleUniverse

Sample Child countriesGeoParams

(43)

Properties name

Defines the name for the external match. This value is also used for the name of the spatial data layer that is created in the map. Therefore, this name appears in the Layer Control pane.

Sample Default: World Countries Type: string

[dataBindColumns]

The name of the Business Objects object that binds to the geographic column in the geographic data.

Sample Default: Country Type: string

[geoBindColumns]

Specifies the name of the bind column in the geographic table that is matched with the dataBind column.

Sample Default: Country Type:string

[geoContent]

The geographic data reference for the geoParamsBean. This property calls the bean countriesGeoParams.

[labelColumn]

Specifies which column from any report with the currently-defined object to use as the label column on the map. If set to true, the layer is initially auto-labelled.

Sample Default:Country Type: string

[labelled]

This property has been deprecated.

[labelStyle]

The path to the named style to use for labels on the layer. Sample Default: customstyles/bi/labels/world Type: string

countriesExternalMatch (continued)

regionsExternalMatch

Description A sample external match, containing all required information to map a Business Objects object to an external geographic data source.

Required No, but if defined, at least one external match is required.

(44)

Sample Parent

Sample Child regionsGeoParams

Derived from the property geoContent.

Properties name

Defines the name for the external match. This value is also used for the name of the spatial data layer that is created in the map. Therefore, this the name appears in the Layer Control pane.

Sample Default: States Type: string

The name of the Business Objects object that binds to the column in the geographic data. Sample Default: State Type: string

Sample Default:STATE Type: string

[geoContent]

The geographic data reference for the geoParams key. This property calls the sample bean regionsGeoParams.

[labelColumn]

Sample Default: State Type: string

[labelStyle]

The path to the named style to use for labels on the layer. Sample Default: customstyles/bi/labels/regions Type: string

regionsExternalMatch (continued)

postalcodesExternalMatch

(45)

Scope none

Sample Child postalcodesGeoParams

Properties name

Sample Default: Postal Codes Type: string

Sample Default: Postal Code Type: string

Sample Default:ZIP Type: string

[geoContent]

The geographic data reference for the geoParams key. This property calls the sample bean postalcodesGeoParams.

[labelColumn]

Sample Default: Postal Code Type: string

[labelStyle]

The path to the named style to use for labels on the layer. Sample Default: customstyles/bi/labels/postal Type: string

(46)

regionNamesExternalMatch

Scope none

eFashion

Sample Child regionsGeoParams

Properties name

Sample Default: States Type: string

Sample Default:STATE_NAME Type: string

[geoContent]

The geographic data reference for the geoParams key. This property calls the sample bean regionsGeoParams.

[labelColumn]

[labelStyle]

(47)

[drillPath]

Sets the level in the Business Objects system hierarchy that this defined dimension should drill to if the user clicks on the map using the drill tool. If a drill path is not specified, the drill tool travels one level down into the system’s drill hierarchy. Sample Default: Store name Type: string

[drillReport]

Defines which report to drill for values used in selecting geographic content for a bind. The drill report can be used to define a specific report to display upon drilling to the next level. This is useful for either overriding the default drill path or for providing a

specifically-formatted report for the target drill level.

The value specified in this property is the reportID (also known as the Document ID in InfoView), which can be obtained by viewing the report’s properties.

The target report must contain the same attribute as the attribute in the source report being drilled from. So, if you are drilling from State to County level and the starting report contains an attribute State, the target report must also contain State. If the target report is prompted, then the prompt must also be on State.

Sample Default: 10587 Type: string

[themes]

Consists of a list of themes that apply to this dimension. For each entry in the map, the key is the name of the theme (which is also displayed to the user in a drop-down menu when this binding is used), and the value is a reference to one of the available

ThemeBean implementations: RangedThemeBean, FixedRangeThemeBean, IndividualValueThemeBean, PieChartThemeBean, StackedBarChartThemeBean, or SideBySideBarChartThemeBean.

This property contains the class

com.mapinfo.jsf.controls.mapping.ThemeBean and the sample nested beans salesStateTheme1, salesStateTheme2 and salesStateTheme3.

(48)

citiesExternalMatch

Scope none

eFashion

Sample Child citiesGeoParams

Properties name

Sample Default: Cities Type: string

Sample Default: City Type: string

Sample Default:City Type: string

[geoContent]

The geographic data reference for the geoParams key. This property calls the sample bean citiesGeoParams.

(49)

[labelColumn]

Sample Default: City Type: string

[labelStyle]

citiesExternalMatch (continued)

storesExternalMatch

Scope none

Sample Parent

eFashion

Sample Child storesGeoParams

Sample Default: Stores Type: string

Sample Default: Store name Type: string

(50)

Internal Match Managed Beans

This section includes a single sample internal match bean: the LatLongInternalMatch managed bean.

[geoContent]

The geographic data reference for the geoParams key. This property calls the sample bean storesGeoParams.

[labelColumn]

Sample Default: Store name Type: string

[labelStyle]

storesExternalMatch (continued)

LatLongInternalMatch

Description A sample internal match, containing all the information necessary to map internal latitude and longitude values.

Required No, but if defined, at least one internal match is required.

Class com.mapinfo.jsf.controls.bi.InternalMatchBean Scope none Sample Parent XtremeSampleUniverse Properties name

Defines the name for the match. This value is also used for the name of the spatial data layer that is created in the map. Therefore, this name appears in the Layer Control pane. Sample Default: Locations Type: string

keyColumns

Any key attribute used in every report that contains a longitude and latitude value. Sample Default: IDcolumn Type: string

[labelColumn]

Specifies which column from any report with the currently-defined dimension to use as the label column on the map.

(51)

Geographic External Bind Managed Beans

This section includes several sample external match beans that have been used to define specific geographies.

[labelStyle]

The path to the named style to use for labels on the layer. Sample Default: Type: string

[latitudeColumn]

The column header designating the Business Objects dimension containing the latitude value for mapping the location on the map.

Sample Default: Latitude Type: float

[longitudeColumn]

The column header designating the Business Objects dimension containing the longitude value for mapping the location on the map.

Sample Default: Longitude Type: float

[srsName]

Tells the mapping engine what spatial referencing system the longitude and latitude values use.

Sample Default: EPSG:4269 Type: string

LatLongInternalMatch (continued)

countriesGeoParams

Description A sample geographic parameter bean, which allows binding report data to a spatial data source. You must define a bean for each spatial data source.

Required No

Class com.mapinfo.jsf.control.soleng.util.jsf.GeoParamsBean

Scope none

Sample

(52)

Properties layerName

The name of the named layer. Sample Default: World Type: string

[layerPath]

The relative path from your resources directory to the geographic layer for the data bind. If you upgrade this file, refer to the Location Intelligence Component Map Manager Guide for information on named resources.

Sample Default: customlayers/bi/botutorial Type: string

countriesGeoParams (continued)

regionsGeoParams

Required No Class com.mapinfo.soleng.util.jsf.GeoParamsBean Scope none Sample Parents regionsExternalMatch regionNamesExternalMatch Properties layerName

Defines the name of the geographic layer for the data bind. Sample Default: States Type: string

layerPath

The relative path from your resources directory to the geographic layer for the data bind. If you decide to upgrade this file, refer to the Location Intelligence Component Map Manager Guide for information on named resources.

postalcodesGeoParams

Required No

(53)

Scope none

Sample Parent

postalcodesExternalMatch

Defines the name of the geographic layer for the data bind. Sample Default: ZipCodes Type: string

layerPath

postalcodesGeoParams (continued)

storesGeoParams

Required No

Class com.mapinfo.jsf.soleng.util.jsf.GeoParamsBean

Scope none

Defines the name of the geographic layer for the data bind. Sample Default: Stores Type: string

layerPath

(54)

Theming Managed Beans

This section contains a variety of sample theming beans. The LIC offers Ranged themes, Fixed Range themes, and Individual Value themes.

Ranged Theme Managed Beans

The bifaces-config file includes two theme beans (the salesState1Theme bean and the

salesState2Theme bean) as sample Ranged theme beans. The salesState1Theme bean demonstrates how to define a theme based on default solid colors; salesState2Theme bean demonstrates how to define a theme based on translucent styles. All styles identified here are provided in the customstyles directory.

citiesGeoParams

Required No Class com.mapinfo.jsf.control.soleng.util.jsf.GeoParamsBean Scope none Sample Parent citiesExternalMatch Properties layerName

The name of the named layer. Sample Default: Cities Type: string

[layerPath]

salesState1Theme

Description A sample ranged theme bean, containing all the properties of a regular

RangedThemeBean plus any child beans useful in defining a multivariate color theme.

Required No

(55)

Scope none

regionNamesExternalMatch Derived from the property themes.

Properties name

Defines the name for the thematic. This property is displayed to the user in the Theme Control pane.

Sample Default: Theme1 Low Sales in Red Type: string

attribute

Defines what attribute in the report to perform the thematic analysis on. Therefore this thematic is loaded if the user creates a report on States that contains the Sales Revenue attribute in it.

Sample Default: Sales revenue Type: string

[beginColor]

Defines the color for the starting range value for this theme. The value must be a java.awt.Color constant. Valid values are black, blue, cyan, gray, darkGray, lightgray, green, magenta, orange, pink, red, white or yellow.

If you have defined a named style you prefer to reference, you can also use the beginStyle property instead.

Sample Default: red Type: const

[endColor]

The color for the ending range value for this theme. The value must be a java.awt.Color constant. Valid values are black, blue, cyan, gray, darkGray, lightgray, green, magenta, orange, pink, red, white or yellow.

If you have defined a named style you prefer to reference, you can also use the endStyle property instead.

Sample Default: green Type: const

[distributionType]

The distribution type for the theme. This value determines the methodology for grouping the attribute values into common ranges. Valid values are Equal Count, Equal Ranges, Standard Deviation, Natural Break and Custom Ranges.

Sample Default: Equal Count Type: string

[numRanges]

How many ranges into which the attribute data is grouped. Sample Default: 4 Type: float

(56)

salesState2Theme

Description A sample ranged theme bean, containing all the properties of a regular

RangedThemeBean plus any child beans useful in defining a multivariate translucent color theme. Required No Class com.mapinfo.jsf.controls.mapping.RangedThemeBean Scope none Sample Parent regionNamesExternalMatch Derived from the property themes.

Defines the name for the thematic. This property is displayed to the user in a drop-down menu for this pre-defined thematic on the regionNames external match layers.

Sample Default: Theme2 translucent style Type: string

attribute

Defines what attribute in the report to perform the thematic analysis on. Therefore this thematic is loaded if the user creates a report on States that contains the Sales Revenue attribute in it.

[beginColor]

Defines the color for the starting range value for this theme. The value must be a java.awt.Color constant. Valid values are black, blue, cyan, gray, darkGray, lightgray, green, magenta, orange, pink, red, white or yellow.

If you have defined a named style you prefer to reference, you can also use the beginStyle property instead.

Sample Default: LRed_opac50 Type: const

[endColor]

The color for the ending range value for this theme. The value must be a java.awt.Color constant. Valid values are black, blue, cyan, gray, darkGray, lightgray, green, magenta, orange, pink, red, white or yellow.

If you have defined a named style you prefer to reference, you can also use the endStyle property instead.

Sample Default: Purple_opac50 Type: const

(57)

Fixed Range Theme Managed Beans

The bifaces-config file includes the salesState3Theme managed bean as a sample Fixed Range theme bean. Also included in this section are samples of the three associated sample beans, sales1Bin - sales3Bin.

The distribution type for the theme. This value determines the methodology for grouping the attribute values into common ranges. Valid values are Equal Count, Equal Ranges, Standard Deviation, Natural Break and Custom Ranges.

Sample Default: Equal Count Type: string

[numRanges]

How many ranges into which the attribute data is grouped. Sample Default: 3 Type: float

salesState2Theme (continued)

salesState3Theme

Description A sample theme bean, working in conjunction with the regionNamesExternalMatch bean to produce the multivariate shading thematic map.

Required No Class com.mapinfo.jsf.controls.mapping.FixedRangeThemeBean Scope none Sample Parent regionNamesExternalMatch Sample Children sales1Bin - sales3Bin

All derived from the property rangeBins.

Properties name

Defines the name for the thematic. This property is displayed to the user in a drop-down menu for this pre-defined thematic on the regionNames external match layers.

(58)

attribute

Defines what attribute in the report to perform the thematic analysis on. This thematic is loaded if the user creates a report on States that contains the Sales Revenue attribute in it.

rangeBins

States that attribute grouping is going to be controlled by this configuration file explicitly by the nested beans sales1Bin, sales2Bin and sales3Bin. This differs from the other theme definitions because range bins are being defined. The other beans used the distributionType and numRanges properties to define the theme. This property defines a way to control explicitly what values go into what grouping. This property contains the class com.mapinfo.jsf.controls.mapping.ThemeAttributeBean and the nested beans sales1Bin, sales2Bin, and sales3Bin.

salesState3Theme (continued)

sales1Bin

Description A sample theme bean, defining the properties for a single bin for the group of bins defined for a range thematic. There are three sample sales<x>Bin managed beans provided in the sam