Web Dynpro Table API - IWDTable (SAP Library

Web Dynpro Table API - IWDTable

Definition

The Table UI element allows the two-dimensional display of data in cells arranged into rows and columns. The UI element consists of a header area, context text area, and footer area. The lead selection of a row is highlighted in color when displayed on the screen. The Table UI element can contain any number of TableColumn elements. The following graphic shows how the UI element is displayed.

Display of a Table

This graphic is explained in the accompanying text

Pushbuttons provided in the footer of the table allow navigation. The following scroll bar functions are available:

First page	Page up	Line up
Last page	Page down	Line down

onFilter Action

The display of rows in a table can be restricted using the onFilter action. This can improve the overview of the information contained in a table.

The Table UI element and the TableColumn element provide the application developer with an interface to display a so-called filter row. The filter row is displayed right below the column header area and does not change position when the user browses.

The filtering of table entries requires:

1. ^The option to specify a criterion for each table column to restrict the result list

2. The option to start the filter process

Restricting the size of the result list

Each table column enables you to bind its filterValue property to a context attribute that defines the value to be filtered. Due to the binding of this property to a context attribute, an input element, which can be used to enter the value to be filtered, is displayed in the column below the column header area. At runtime, the filter input of the user is located in the context attribute to which the property is bound.

Starting the filter process

The Table UI element provides the onFilter property, which is associated with an action. Due to the association with an action, the filter row is displayed in the table. The filter row contains the button This graphic is explained in the accompanying text as the first element on the left side. When the user chooses this button, the associated action is executed.

The logic of the filter process is not implemented in Web Dynpro. The application developer must implement the action to be executed.

Description of the UI Element Properties

accessibilityDescription
When accessibility is activated, the assigned text is added to the tooltip. This description provides semantic details of the UI element and is only read by the screen reader if the user focuses the complete Ul element.
dataSource
You use this property to determine the data source. You can use it to specify the path to the context node providing the data.
design
Describes the appearance of the table in abstract terms.
The design property can be filled with the following values and is represented by the enumeration type WDTableDesign.

alternating	The table rows are displayed alternately in a different color.
standard	The table background has one color. The individual table rows are displayed with grid net lines.
transparent	The table background is transparent. The individual table rows are displayed without grid net lines.

firstVisibleRow
Specifies which row of the table is to be displayed as the first row.
footerVisible
Specifies whether or not a footer is displayed.
readOnly
Specifies whether or not the table can be edited. If the value is true, the data in the table cannot be edited.
selectionMode
Specifies in which way the table rows can be selected.
In general, the selection of table rows is specified by the definition of the context node selection. However, you can change the selection using the selectionMode property. The selectionMode property can be filled with the following values and is represented by the enumeration type WDTableSelectionMode.

auto	The selection of the table is specified by the selection of the context node.
multi	Multiple table rows can be selected if the context node allwos multiple selection.
single	Only one row can be selected at a time.

Note
If you assign the single value to the selectionMode property, you can only select one row at a time, even if multiple is defined for the context node.

visibleRowCount
Specifies the number of rows of a table which is to be displayed without leaves. The value -1 does not restrict the number of rows and displays all table rows without leaves.
width
Specifies the width of the table and can be specified in relative CSS units like em, ex, or percentage.

Overview of Inherited and Additional Properties

Name	Interface	Type	Initial Value	Bindable	Value Required
accessibilityDescription	IWDTable	String (Translatable Text)		bindable	No
dataSource	IWDTable	Object		bindable_mandatory	Yes
Design	IWDTable	WDTableDesign	standard	bindable	No
enabled	IWDUIElement	boolean	true	bindable	No
firstVisibleRow	IWDTable	int	0	bindable	No
footerVisible	IWDTable	boolean	true	bindable	No
readOnly	IWDTable	boolean	false	bindable	No
selectionMode	IWDTable	WDTableSelectionMode	Auto	not_bindable	No
tooltip	IWDUIElement	String (TranslatableText)		bindable	No
visible	IWDUIElement	WDVisibility	visible	bindable	No
visibleRowCount	IWDTable	int	5	bindable	No
width	IWDTable	String (CSS size)		bindable	No

Events

· onFilter
This property contains the action that is executed when the user selects the filter function – that is, the icon This graphic is explained in the accompanying text in the first table column. See a detailed description of this function further above under Definition.

· onLeadSelect
This property contains the action that is executed when the lead selection of the table changes. The event parameters are the ID of the column and the row number (starting at 0).

Event Parameter	Type
col	String
row	int

For further information, refer to Structure link Parameter Mapping.

Associated Interfaces

IWDTableColumn

IWDTreeByNestingTableColumn

Data Binding

A table receives its data from a context node – that is, the table property dataSource must be bound to a multiple context node.

At runtime, each node element of the node collection is a table row.

The number of table rows is identical to the number of node elements. The selected table rows correspond to the node selection. If the selection of the context node changes, the selected table rows also change. The lead selection plays an important role for the table cell that can be edited, because it is predefined by the lead selection of the context node. A table cell can only be edited if the lead selection corresponds to this cell and its table cell editor allows the editing of the cell content.

The table columns correspond to the context attributes and are described by the aggregation of TableColumn objects. They specify the number and order of columns as well as the headers and the width of the columns.

The content of a table cell to be displayed is specified by the table cell editor of the column. The table cell editor can only display the content in a table cell, so it does not make any difference if the content cannot be edited. You can use one of the following table cell editors:

· Button UI element, LinkToAction UI element, LinkToURL: UI element:
UI elements that can be used to trigger events.

· Caption UI element, Image UI element, TextView UI element:
UI elements that can be used to display texts or graphics.

· CheckBox UI element, RadioButton UI element, DropDownByKey UI element:
UI elements that can be used to select elements of a specific value set.

· DropDownByIndex UI element

· InputField UI element:
This UI element allows the editing of a cell content.

The content to be displayed in a table does not have to be identical to the data source of the table. For example, two columns can display the same context attribute or two context attributes can be displayed in the same column.

For further information, refer to Data Binding of a Table.

Mobile Characteristics

The UI element Table supports the development of mobile applications for pocket PCs and BlackBerry wireless handhelds (see Mobile Web Dynpro).

However, several properties supported in the desktop browser cannot be used. These include:

Variances of the properties

Properties	Pocket PC	BlackBerry wireless handheld
design	ignored	ignored
enabled	ignored	ignored
readOnly	ignored	ignored
tooltip	ignored	ignored
width	ignored	ignored

Note

For BlackBerry wireless handhelds, the multiple selection is not supported. The contents of the first column of a table are rendered as links in BlackBerry wireless handhelds. You can only use the UI elements LinkToAction, LinkToURL, and TextView as table cell editors.

Methods in the Web Dynpro IWDTable API

Method Name	Parameter	Return Value	Description
addColumn	(IWDTableColumn column)		Adds a column element at the end of the column elements list.
addColumn	(IWDTableColumn column, int index)		Adds a column element at the specified index position of the column elements list.
bindAccessibilityDescription	(String path)		Binds the accessibilityDescription property to the context node specified by a path.
bindDataSource	(String path)		Binds the dataSource property to the context node specified by a path.
bindDesign	(String path)		Binds the value of the design property to the context element specified by the path.
bindFirstVisibleRow	(String path)		Binds the firstVisibleRow property to the context node specified by a path.
bindFooterVisible	(String path)		Binds the footerVisible property to the context node specified by a path.
bindingOfAccessibilityDescription		String	Returns the path of the context element to which the accessibilityDescription property is bound. Returns NULL if no binding exists.
bindingOfDataSource		String	Returns the path of the context element to which the dataSource property is bound. Returns NULL if no binding exists.
bindingOfDesign		String	Returns the path of the context element to which the design property is bound. Returns NULL if no binding exists.
bindingOfFirstVisibleRow		String	Returns the path of the context element to which the firstVisibleRow property is bound. Returns NULL if no binding exists.
bindingOfFooterVisible		String	Returns the path of the context element to which the footerVisible property is bound. Returns NULL if no binding exists.
bindingOfReadOnly		String	Returns the path of the context element to which the readOnly property is bound. Returns NULL if no binding exists.
bindingOfVisibleRowCount		String	Returns the path of the context element to which the visibleRowCount property is bound. Returns NULL if no binding exists.
bindingOfWidth		String	Returns the path of the context element to which the width property is bound. Returns NULL if no binding exists.
bindReadOnly	(String path)		Binds the readOnly property to the context node specified by a path.
bindVisibleRowCount	(String path)		Binds the visibleRowCount property to the context node specified by a path.
bindWidth	(String path)		Binds the value of the width property to the context element specified by the path.
destroyAllColumns			Removes all column elements. These are destroyed and no longer exist, so that the associated IDs can be used for new elements.
destroyHeader			Removes and deletes the headers for this table element.
destroyMasterColumn			Removes and deletes the MasterColumn for this table element.
destroyToolBar			Removes and deletes the ToolBar for this table element.
getAccessibilityDescription		String	Returns the value of the accessibilityDescription property.
getColumns		IWDTableColumn[]	Returns an array of the column elements.
getDesign		WDTableDesign	Returns the value of the design property.
getFirstVisibleRow		int	Returns the value of the firstVisibleRow property.
getFooterVisible		boolean	Returns the value of the footerVisible property.
getHeader		IWDCaption	Returns the header for this table element.
getMasterColumn		IWDAbstractMasterTableColumn	Returns the MasterColumn for this table element.
getOnFilter		IWDAction	Returns the action that is executed when the onFilter event is triggered.
getOnLeadSelect		IWDAction	Returns the action that is executed when the onLeadSelect event is triggered.
getReadOnly		boolean	Returns the value of the readOnly property.
getSelectionMode		WDTableSelectionMode	Returns the value of the selectionMode property.
getToolBar		IWDToolBar	Returns the ToolBar for this table element.
getVisibleRowCount		int	Returns the value of the visibleRowCount property.
getWidth		String	Returns the value of the width property.
hasColumns		boolean	Checks whether or not column elements exist in this table element.
iterateColumns		Iterator	Returns an iterator about all column elements in this table element.
mappingOfOnFilter		IWDParameterMapping	Returns the parameter mapping for the onFilter action.
mappingOfOnLeadSelect		IWDParameterMapping	Returns the parameter mapping for the onLeadSelect action.
numberOfColumns		int	Returns the number of the column elements.
removeAllColumns			Removes all column elements. They remain and can be added to this table element.
removeColumn	(int index)	IWDTableColumn	Removes the column element at the specified index position.
removeColumn	(String id)	IWDTableColumn	Removes the column element with the specified ID.
setAccessibilityDescription	(String accessibilityDescription)		Sets the value of the accessibilityDescription property.
setDesign	(WDTableDesign design)		Sets the value of the design property.
setFirstVisibleRow	(int firstVisibleRow)		Sets the value of the firstVisibleRow property.
setFooterVisible	(boolean footerVisible)		Sets the value of the footerVisible property.
setHeader	(IWDCaption header)		Sets the header for this table element.
setMasterColumn	(IWDAbstractMasterTableColumn masterColumn)		Sets the MasterColumn for this table element.
setOnFilter	(IWDAction action)		Sets the action that is executed when the onFilter event is triggered.
setOnLeadSelect	(IWDAction action)		Sets the action that is executed when the onLeadSelect event is triggered.
setReadOnly	(boolean readOnly)		Sets the value of the readOnly property.
setSelectionMode	(WDTableSelectionMode selectionMode)		Sets the value of the selectionMode property.
setToolBar	(IWDToolBar toolBar)		Sets the ToolBar for this table element.
setVisibleRowCount	(int visibleRowCount)		Sets the value of the visibleRowCount property.
setWidth	(String width)		Sets the value of the width property.

Additional methods described in the following APIs are available using inheritance: IWDUIElement, IWDViewElement.