Table

The Table widget provides the ability to display data in a table.

The Table widget also supports pagination. A paginated table is a table widget that displays data elements from the backend system on different pages in a table. A paginated table can be used when the number of elements are both known or unknown, and it can be defined by functional developers without having to develop a pagination operation for every table. One type of pagination operation corresponds to one specific scenario. Table pagination also supports the scenario in which the content of the first page has already been retrieved by an initial operation and the pagination operation should not be called when loading the table widget.

Implementation base

The Table widget is a Dojo-based widget:
  • com.ibm.btt.dijit.Grid

Properties

The properties described in Table 1 can be configured for the Table widget.
Table 1. Properties that can be configured for the Table widget
Property Description
id The id is the identifier for the widget.
dataName The dataName property specifies the name of the data element that is used to cache the record in the table that is submitted. For more information, please refer to Data binding.
dataNameForList The dataNameForList property specifies the name of the data, from a WebSphere® Multichannel Bank Transformation Toolkit context or a JSON string, that contains the records for the table. For more information, please refer to Data binding.
isPageable The isPageable property specifies whether the table is single page table or pageable table. The default value is false. If the value is true, Pagination tab would appear where the user could complete the configuration. Please refer to Table 3.
sortEnabled The sortEnabled property specifies whether the rows on the table can be sorted by a user.
Note: If sortEnabled is set true, invoking visibility=hidden would cause problems. Please do not apply the two fuctions at one time.
columnReordering The columnReordering property specifies whether the order in which the columns of the table are displayed can be changed by a user. The default value is false.
visibility The visibility property defines how a widget is displayed on a GUI. The following values can be specified for this property:
visible
The widget is displayed on a GUI and users are able to interact with the widget.
hidden
The widget is not displayed on a GUI, but it occupies space on the GUI.
gone
The widget is not displayed on a GUI, and it does not occupy space on the GUI.
hint The hint is a description of the widget that is displayed as a tooltip for a user. The hint property has multilingual support.
readOnly The readOnly property is an expert-level property, which means that it is available for use in the XUI editor only if the XUI editor is configured to display expert properties. If you select a value of true for the readOnly property, the widget is displayed on a GUI but a user cannot interact with it. If a widget has the value of its readOnly property set to true and the value of its disabled property set to false, the data of the widget is taken into account during form submission. The default value for the readOnly property is false.
Note: To ensure that the Table widget and all the widgets contained in the Table widget are read-only, you must both set the value of the readOnly property to true and select the Editable check box in the Details panel of the Columns tab, which is in the Table view of the Properties tab. If you do not select the Editable check box, the widgets that are contained in the Table widget can be edited by a user.
selectionMode The selectionMode property specifies the number of rows that can be selected by a user. Values that can be specified for the selectionMode property are none, single, and multiple.
selectionRequired The selectionRequired property specifies whether a user is required to select a record. If the selectionRequired property is set to true and the user does not select a record, an error message displays.
isActionable The isActionable property specifies whether to take the action when a row on the table is double-clicked on. The options for this property:
  • false default value: no action would be executed.
  • true: if there is an action, the action would be executed. Action tab would appear where the user could complete the configuration.
    Note: Generally, double-clicking a cell would enter the editing mode, instead of launching the action if the cell is editable and readOnly property is set false. Thus, it would only launch the action when the cell is not editable and readOnly property is set true.
disabled Disabled elements cannot have focus, do not receive or fire mouse events, cannot receive user input. If you select a value of true for the disabled property, the widget is displayed on a GUI but a user cannot interact with it. Data contained in a disabled widget is not processed when the form is submitted. The default value for the disabled property is false.
Note: When the table is disabled, the background is set to be gray, indicating that it is not allowed to do all the operations, such as row selection, column reordering, scrolling, sorting and editing.
styleClass The styleClass property specifies the name of the CSS style ( also known as CSS style class) associated with the widget. This property is set by selecting a style from the CSS styles table in the Style tab of the Properties view. If you do not configure the styleClass property, the default style is used instead. For more detailed information, refer to Setting CSS style to widgets.
width The width property specifies the width of the widget. This property is set in the Appearance tab of the Properties view.
height The height property specifies the height of the widget. This property is set in the Appearance tab of the Properties view.
Each column in a table has the properties described in Table 2.
Table 2. Properties of the columns in a Table widget
Property Description
text The text property specifies the text that is displayed as the header of the column.
dataName The dataName property is the name of the data element to which the column is bound. Currently we only support simple data and record(KColl).
width The width property specifies the width of the column.
alignment The alignment property specifies the alignment of the text in the cells of the table. Three values are available for the alignment property:
  • Left
  • Center
  • Right
The default value is Left.
visible The visible property specifies whether the column is visible or not. The default option is checked. If it is unchecked, the column would be hidden and
  • For auto-sized table, the table would get shrunk. If all columns are hidden, the table would completely disappear.
  • For fixed-sized table, the table would remain the original size and leave some blanket space on the right. If all columns are hidden, the table would show a blanket layout.
Note: For auto-sized table, the error icon would also disappear. So it is suggested to set fixed size for the table.
editable The editable property specifies whether the cells in the table can be edited by a user. If the property is setfalse, the cell is only for read, and cannot be edited. Its value decides the selection list of widget property.
widget The widget property is the widget to which the column is bound. Its selection list is depending on whether the editable property istrue or false. For details, please refer to Available widgets for selection.
If a value of true has been selected for the isPageable property, the properties described in Table 3 can be configured in the Pagination tab of the Properties view.
Table 3. Properties that can be configured for the paginated table widget
Property Description
operationNameForPagination The operationNameForPagination property specifies the technical operation name for the pagination table.
directPagination The directPagination property specifies whether the number of pagination table rows is known. The default value is false.
paginationType The paginationType property specifies the pagination type that is registered in the btt.xml file. Default value is default.
RowsPerPage The RowsPerPage property specifies the number of rows for each page in pagination table. The default value is 25.
timeout The timeout property specifies the length of time after which an AJAX request times out in a pagination table. Default is 500 milliseconds.
paginationWhenLoading The paginationWhenLoading property specifies pagination or not when first loading the page. The default value is false.
Note: When the value is true, it may cause problems to get focus of other widgets through ECA rules. So please do not set focus of other widgets on this condition.
initialInputMapping The initialInputMapping property specifies the initial page input mapping. This property is enabled when a value of true is specified for the paginationWhenLoading property.
nextInputMapping The nextInputMapping property specifies the next page input mapping. This property is enabled when a value of false is specified for the directPagination property.
previousInputMapping The previousInputMapping property specifies the previous page input mapping. This property is enabled when a value of false is specified for the directPagination property.
directInputMapping The directInputMapping property specifies the direct page input mapping. This property is enabled when a value of true is specified for the directPagination property.
normalOutputMapping The normalOutputMapping property specifies the normal response output mapping
errorOutputMapping The errorOutputMapping property specifies the error response output mapping.

Data binding

The data that is specified in the dataNameForList property must be an IndexedCollection from the WebSphere Multichannel Bank Transformation Toolkit context hierarchy.

For more detailed information about data binding, you can see: Binding data to a table widget

The inner data element can be either an IndexedCollection or a KeyedCollection. If the inner data element is a KeyedCollection, the values from each element that are contained in the KeyedCollection are displayed on a row of the table. If the inner data element is an IndexedCollection, the values of the elements that are contained in the IndexedCollection are displayed on a column.

The dataName property specifies the name of a data element that is retrieved from a WebSphere Multichannel Bank Transformation Toolkit context. Data that are entered into the rows of a table are submitted to the data element specified in the dataName property. The data element can be either an IndexedCollection or a KeyedCollection. If single is selected for the selectionMode property, the data element should be a KeyedCollection. If multiple is selected for the selectionMode property, the data element should be an IndexedCollection.

Sometimes, the application requires that the table widget be bound with special data items on each row. When the table data is downloaded from the server side, the special data items are loaded with other table data, and the special data items are sent back to the server side when the selected rows are submitted. The difference between the special data items and normal table data is that the special data items are not displayed on the table widget though it can be displayed on the table widget like normal table data; therefore, special data items are called "hidden columns" here. For example, the "hidden columns" may be the key identifier of the rows, which are not displayed on the view but are required for the identification of the selected rows. The data field that corresponds to a "hidden column" must meet the following three conditions:
  • The data field exists in the keyed collection or indexed collection that is specified in the dataName property.
  • The data field exists in the indexed collection that is specified in the dataNameForList property.
  • The data field is not a explicitly declared column.
The WebSphere Multichannel Bank Transformation Toolkit runtime will handle the data field as a "hidden column" for the table and send the field data to the table widget. The table widget retains the data and then posts it to the server with the selected rows.
For a paginated table, specify following data in the context of a pagination technical operation:
<kColl id="pageRetrieverData" dynamic="false">
		<field id="start" value="0"/>
		<field id="count" value="15"/>
		<field id="totalRowNumber" value="101"/>
		<field id="enableNext" value="true"/>
		<field id="enablePrevious" value="false"/>
		<field id="errMsg"/>
		<field id="sort"/>
		<field id="rowsPerPage" value="25"/>
		<field id="pageNumber" value="1"/>
		<field id="pageEvent"/>
		<kColl id="queryConditions" dynamic="false">
			<field id="aFilter" value="%"/>
			<field id="bFilter" value="0"/>
		</kColl>
		<refData refId="item"/>
		<iColl id="items">
			<refData refId="item"/>
		</iColl>
	</kColl>
<!—the inner data in KeyedCollection item are the data column for the pagination table.-->
<kColl id="item">
		<field id="index" value="1"/>
		<field id="gender" value="male"/>
		… 

</kColl>
You need to specify the related data for each pagination table in the business flow. All the data in the paginationData KeyedCollection should contain the ID of the paginated table as a prefix for the data name; for example, if a paginated table has table01 as its ID, table01_ should be used as a prefix as shown in the following code block:
<kColl id="paginationData">
		<field id="table01_totalRowNumber" value="100"/>
		<field id="table01_enableNext" value="true"/>
		<field id="table01_enablePrevious" value="true"/>
		<field id="table01_errMsg" value="no msg"/>
		<field id="table01_rowsPerPage" value="15"/>
		<field id="table01_pageEvent"/>
		<field id="table01_pageNumber" value="1"/>
</kColl>
The following six mappings are available for pagination data:
initialInputMapping
The initialInputMapping property specifies the initial page input mapping. This property is enabled when a true is specified for the paginationWhenLoading property. User needs to mapping the table data from flow to table technical operation.
nextInputMapping
The nextInputMapping property specifies the next page input mapping. This property is enabled when set false is specified for the directPagination property. User need to mapping the table data from flow to table technical operation. It is called when the Next button in a paginated table is clicked and the number of pages for the paginated table is unknown.
previousInputMapping
The previousInputMapping property specifies the previous page input mapping. This property is enabled when false is specified for the directPagination property. User need to mapping the table data from flow to table technical operation. It is called when the Preview button in a paginated table is clicked and the number of pages for the paginated table is unknown.
directInputMapping
The directInputMapping property specifies the direct page input mapping. This property is enabled when set true is specified for the directPagination property. User need to mapping the table data from flow to table technical operation. It will be called when a page number in a paginated table is clicked and when table page is known.
normalOutputMapping
The normalOutputMapping property specifies the normal response output mapping. User need to mapping the table data from table technical operation to flow.
errorOutputMapping
The errorOutputMapping property specifies the error response output mapping. User need to mapping the table data from table technical operation to flow.
After the XUI file with the table pagination definition is saved, table technical general pagination operation is automatically generated.

ECA editor support

The following events, properties, and functions can be configured for the Table widget with the ECA editor.
Note: ECA for Widgets in Table column is partially supported. For more information, please see ECA support for Widgets in Table column.
Table 4. Events that can be added to a Table widget by using the ECA editor.
Event Description
onClick Is fired when the left mouse button is clicked.
onFocus Is fired when the widget receives focus because the user moves the mouse pointer over the widget.
onBlur Is fired when the widget does not receive focus, or when the user clicks outside the widget, or when the widget is hidden.
onKeyDown Is fired when a keyboard key is pressed.
onKeyUp Is fired when a keyboard key is released.
onKeyPress Is fired when a keyboard key is pressed or held down.
onMouseDown Is fired when a mouse button is clicked.
onMouseUp Is fired when a mouse button is released
onMouseEnter Is fired when the mouse pointer moves over the widget.
onMouseLeave Is fired when the mouse pointer moves out of the widget.
onMouseMove Is fired when the mouse pointer moves over nodes that are contained in the widget.
onSelected Is fired when a row on the table is selected.
onRowClick Is fired when a row on the table is clicked on.
Note: Do not use onRowDblClick at the same time.
onRowDblClick Is fired when a row on the table is double-clicked on.
Note: Do not use onRowClick at the same time.
onCellEdit Is fired when the cell enters the edit state.
Table 5. Properties that can be configured for the Table widget by using the ECA editor.
Property Description
id The id is the identifier for the widget.
Note: This property can be used in the Condition part of ECA rule.
visibility This property defines how a widget is displayed on a GUI. The following values can be specified for this property:
visible
The widget is displayed on a GUI and users are able to interact with the widget.
hidden
The widget is not displayed on a GUI, but it occupies space on the GUI.
gone
The widget is not displayed on a GUI, and it does not occupy space on the GUI.
Note: This property can be used in the Condition and Actions part of ECA rule.
readOnly The readOnly property can be set to keep a user from changing the value. The default value for the readOnly property is false.
Note: This property can be used in the Condition and Actions part of ECA rule.
hint The hint is a description of the widget that is displayed as a tooltip for a user. The hint property has multilingual support.
Note: This property can be used in the Actions part of ECA rule.
styleClass
Note: This property can be used in the Actions part of ECA rule.
disabled Disabled elements cannot have focus, do not receive or fire mouse events, cannot receive user input. If you select a value of true for the disabled property, the widget is displayed on a GUI but a user cannot interact with it. Data contained in a disabled widget is not processed when the form is submitted. The default value for the disabled property is false.
Note: This property can be used in the Condition and Actions part of ECA rule.
columnIndex This property gets the column the user just clicked on.
Note: This property can be used in the Condition part of ECA rule.
rowIndex This property gets the row the user just clicked on.
Note: This property can be used in the Condition part of ECA rule.
Table 6. Functions that can be configured for the Table widget by using the ECA editor.
Function Description
focusOn() Enables a table to receive focus. The last cell of the table will receive focus.
Note: This function can be used in the Actions part of ECA rule.
getValueInFirstSelectedItem(attName) Retrieves the value of a column from the data element that is specified in the dataName property.
Note: This function can be used in the Condition and Actions part of ECA rule.
getValueInSelectedItem(itemId) Retrieves the value of a cell on a selected row.
Note: This function is not supported for WebSphere Multichannel Bank Transformation Toolkit V7.1.
Note: This function can be used in the Condition and Actions part of ECA rule.
getLengthSelectedRows() Retrieves the value of a row from the data element that is specified in the dataName property.
Note: This function can be used in the Condition and Actions part of ECA rule.
isFocusable Returns a value of true if a widget can be focused and a value of false if it cannot be focused.
Note: This function can be used in the Condition part of ECA rule.
showColumn(index) Shows the column that is set hidden by its index parameter.
Note: This function can be used in the Actions part of ECA rule.
hideColumn(index) Hides the column that is set visible by its index parameter.
Note: This function can be used in the Actions part of ECA rule.
isColumnVisible(index) Returns true if the column is visible or false if the column is hidden.
Note: This function can be used in the Condition part of ECA rule.
setCellValueByIndex Sets value of the specified table cell by Index.
Note: This function can be used in the Actions part of ECA rule.
setCellValueByName Sets value of the specified table cell by Name.
Note: This function can be used in the Actions part of ECA rule.
getCellValueByIndex Gets value of the specified table cell when it is from other Widgets in Table column by Index.
Note: To get the value of the cell when it is selected, use Value property.
Note: This function can be used in the Condition part of ECA rule.
getCellValueByName Gets value of the cell when it is from other Widgets in Table column by Name.
Note: This function can be used in the Condition part of ECA rule.