- This line was added.
- This line was removed.
- Formatting was changed.
|Table of Contents|
The data table widget provides a feature rich and versatile way to present data on the frontend.
At its core, the data table provides a table where rows represent object instances in the provided collection source and columns represent attributes and concatenations of attributes.
Row actions are buttons that can be used to act upon a specific row and thus object instance in the data table. They require a value to be specified for the
action attribute. This represents a function that can be used for navigation or any other application logic. In addition the object representing the selected row can be bound to a unit variable.
For each row in the table, the row actions are grouped together in a column with no column heading:
A confirm popup can also be displayed when a row action is selected. This is achieved using the
<confirm> child element of
The example below shows a confirm popup for the row action labelled "Remove" as this can be a dangerous operation and might have negative consequences if performed by accident.
<rowAction label="button.remove" action="removeUser"> <binding variable="farmer" /> <confirm subject="confirm_subject.removing_user" body="confirm_body.removing_user" /> </rowAction>
Note that although row actions are mostly used to act upon the object instance representing the selected row, this is not required and no binding needs to be provided. In this case the row action will simply execute the specified action.
Visibility bindings can also be specified for data table row actions. In order to make use of a visibility binding the above example can be updated as follows:
<rowAction label="button.remove" action="removeUser"> <binding variable="farmer" /> <confirm subject="confirm_subject.removing_user" body="confirm_body.removing_user" /> <visible function="showRemoveFarmerRowAction"/> </rowAction>
Note that, in the example above, it is assumed that the backing unit/presenter has a function with name
showRemoveFarmerRowAction that returns a boolean value.
For large data sets the data table widget provides a paging mechanism. When a view with a data table is loaded the default behaviour will be to display at most 10 rows per page. This can, however, be adjusted by selecting the page size in the middle of the data table footer area.
The page size options available start at 10 rows and is incremented by 10 all the way to a maximum of 100 records per page. Note that if the total number of records from the collection source is less that 100 and not a multiple of 10, the total number of rows will also be shown as an option. Also note that the page size option will only be visible when the number of records from the collection source exceeds 10.
By default a table is sorted on it's first column in ascending order. To change the default sort column and direction the
defaultSortDirection attributes can be used.
The value for
defaultSortColumn is the column index and starts at 0. It is required that a valid integer value be specified when using this attribute.
The only values for
ascending which is also the default bahaviour and
Basic Searching and Filtering
A basic search feature is included for tables. This features takes the provided search text and attempts to perform a "starts with" search on values for all rows and columns. This is only applicable to text and enum fields. In the case of enums a match will be attempted on both the translated enum values and the enum values as declared in the data model. The search box used for this features is located at the top left corner of the data table.
Advanced Searching and Filtering
An advanced searching and filtering feature is also provided. This allows for column specific criteria to be specified. The column specific criteria can either be a "begins with", "contains", "between" or "equals" comparison and is determined based on the type of the column. For string columns, for example, a "starts with" filter is applicable whereas for an integer column a "betweens" and "equals" comparison is applicable.
In addition to criteria for individual columns, it can also be specified whether a row should be displayed when only one of the criteria is met or all of the criteria and whether the column specific criteria should match of not match.
The screenshots below demonstrates some of the features mentioned above.
By default, and if not removed manually, filters on a data table will persist throughout the user's session. As of Helium 1.25 this behaviour can be overridden by means of a new boolean attribute on the data table, namely
<table title="table_heading.historic_messages" resetFilters="true"> </table>
By default the value for
For a value of
true, the filters will be reset each time the view is reloaded, including when navigating from the view to itself. The filters will not be reset as a result of paging or initiating a CSV export on the data table.
The currently filtered records being displayed in a data table can be bound to a collection in a presenter using the
<table title="table_heading.historic_messages"> <collectionSource function="getMessages"/> <column heading="column_heading.sent"> <attributeName>sentTstamp</attributeName> </column> <filterDestination variable="MyPresenter:filteredMessages"/> </table>
By default CSV exporting is enabled for all data table widgets on the web and can be triggered by clicking the "Download CSV" icon on the bottom left of the widget. Only the columns represented in the table will be exported. The file name will be constructed using the title of the table, if it has been specified, and the current date/time. For certain tables, however, such as tables acting as custom menus, CSV export can be disabled as shown in the code snipped below:
<table csvExport="disabled"> <collectionSource variable="uMenuItems"/> <column heading="column_heading.name"> <attributeName>name</attributeName> </column> <rowAction label="button.select" action="select"> <binding variable="uMenuItem"/> </rowAction> </table>
The header line can be excluded using the csvColumnHeader attribute of a table and setting it to false (it defaults to true).
<table csvColumnHeader="false"> </table>
Specific columns can be excluded from the export by using the csvIgnore attribute of a column and setting it to true (it defaults to false).
<column heading="column_heading.name" csvIgnore="true"> <attributeName>name</attributeName> </column>
The data table widget allows a time interval between 30 and 1800 seconds to be specified at which point the contents of the table is refreshed without the need for any user intervention. This is specified using the
<table title="table_heading.historic_messages" refreshIntervalSeconds="30"> . . . </table>