Overview

The ItemsGrid component displays the fields of an item source, such as a report, as columns in a table. Each row in the ItemsGrid represents a record in the item source. The ItemsGrid allows users to select individual items, page through large sets of items, and sort items by column. Each column of the ItemsGrid component is an individual ItemsColumn component.

defaultRoot and rootItemID are the two key attributes that determine the top-level item that can be navigated to in the ItemsGrid component. For more information, see How do I customize the root, or top level item in an ItemsGrid or Path control? The defaultRoot attribute is used to specify the root node of the hierarchy of items in the ItemsGrid component. The value this property is set to will create an upper limit on where the user can navigate to within the hierarchy of BusinessObjects Enterprise items. The possible values are fields of the com.businessobjects.jsf.sdk.properties.DefaultRootType class:

• None

The root of the ItemsGrid component is set to the default root of the folder tree within the BusinessObjects Enterprise system.

• Custom

A custom root, specified by the rootItemID attribute, is used as the root of the ItemsGrid component. Set the rootItemID attribute to the identifier of the folder that will be the root item in the grid.

To position the ItemsGrid component on the page, set the horizontalAlign attribute to the desired value. The showHeader, showImages, and showDrillUpLink attributes can be used to customize general display aspects of the ItemsGrid component. By default, the showHeader attribute is set to true, which shows a header text label at the top of each column of the grid. The showImages attribute must be set to fields of the com.businessobjects.jsf.sdk.properties.Image class. By default, the attribute is set to None, however, it can be modified to display either an Icon or Thumbnail representation alongside each item in the grid. For more information on displaying icons, see How do I display images in the ItemsGrid component?.

The showDrillUpLink attribute indicates whether to display a link that allows the user to navigate up the hierarchy of items. This attribute is set to true by default.

There are also many attributes you can use to customize how information within the ItemsGrid component is displayed. By default, the allowSorting attribute is set to false, preventing the user from sorting items. Set this attribute to true to display a sorting link that allows the user to sort the list of items (rows) in the grid. Only certain fields (columns) are optimized and recommended for sorting:

• SI_ID
• SI_CUID
• SI_NAME
• SI_PARENTID
• SI_OWNERID
• SI_UPDATE_TS
• SI_SCHEDULEINFO

For the user to easily distinguish between rows and columns, you can specify what type of grid lines are displayed using the showGridLines attribute. This attribute must be set to fields of the com.businessobjects.jsf.sdk.properties.GridLines class. By default, this property is set to Both; set it to Horizontal to display lines that separate rows, Vertical to separate columns, or None to hide all lines. In addition, the allowDrillDown attribute controls the behavior of items in the grid, and causes the grid to dynamically drill down into an items contents when the user clicks on that item. This property is set to true by default.

Individual columns of the grid can also be customized by selecting an ItemsColumn subcomponent and setting attribute values. See Tag Attributes (itemsColumn) for details on the ItemsColumn attributes.

Note:    Only those fields specified by the fields property of the EnterpriseItem or EnterpriseItems bean should be set using the fields attribute of the ItemsColumn component. This information must be queried for from BusinessObjects Enterprise so that the ItemsGrid component can populate the appropriate column. For more information on fields, see EnterpriseItem bean.

In addition to the general attributes of the component, there are attributes that must be set to property classes.

• alerts attribute

The alerts attribute accesses instances of the AlertProps class, which contains properties to specify when and how alert items are displayed in the ItemsGrid component. By default, the visible property is set to true and the ItemsGrid component displays alerts. Set this property to false to suppress alerts. When an alert occurs, an image is shown to the user to indicate this occurrence. Set the imageUrl property to the location of the image to be displayed. By default, the showAlertMessage and showAlertTime subproperties are both set to true, which displays an accompanying description and time of when the alert occurred, respectively. Set these properties to false to hide this information.

Note:    If alerts are turned on, you must return the processing information for the items represented by the EnterpriseItems bean data bound to this control. This is accomplished by selecting SI_PROCESSINGINFO as the value of the fields property of the bean.

Note:    For more information on property classes, see How do I use property classes in combination with JavaServer Faces Components for BusinessObjects Enterprise?

To customize the appearance of the ItemsGrid component, set the style attributes of the different parts of the control.

Style Attribute	Description	Style Class
alternatingItemStyle	The style of every other item (alternating items).	The string name of the style class defined in a style sheet and linked to from a JSP page or specified directly in a JSP page.
headerStyle	The style of the header at the beginning of the list (if any).	The string name of the style class defined in a style sheet and linked to from a JSP page or specified directly in a JSP page.
itemStyle	The style of individual items.	The string name of the style class defined in a style sheet and linked to from a JSP page or specified directly in a JSP page.
pagerStyle	The style of the page selection UI.	PagerProps

Event Handling

To enable the automatic event handling capabilities of the ItemsGrid component, set the autoHandleEvents property to true. When set to true, this property implements default behavior on action events that are triggered when the user interacts with the component. For example:

Event	Default Behavior
AlertClicked	When an alert item is clicked, the contents of that alert item are displayed. The allowDrillDown attribute must be set to true.
DrillUpClicked	When the Up-one-level hyperlink is clicked, the ItemsGrid component navigates up one hierarchical level and displays the parent items.
ItemClicked	When an item is clicked, the contents of that item are displayed and the contents are sorted by the field specified by the sortField property and according to the sort direction specified by the sortDirection property of the itemSource. The allowDrillDown property of the ItemsGrid component must be set to true.
PagerClicked	When the next page, previous page, next page range, or previous page range button is clicked, the page index is changed and the current page is set and displayed appropriately.
SortClicked	When a field (column) heading is clicked, the items (rows) in the ItemsGrid component are sorted according to that field. When that field is clicked again, the sort order is reversed.

If the autoHandleEvents property is set to false, these events will not be handled automatically. If you set autoHandleEvents to false, you may write your own event handlers.

Data Binding

The ItemsGrid component supports data binding to an EnterpriseItem bean or an EnterpriseItems bean. These beans provide the source for the item or items to be displayed in the rows of the ItemsGrid component. Use the itemSource attribute to bind the component to the desired bean.