Grid Control

Note | In this article, "grid" refers to the MRI Dreamscape Grid (DataTable) control.

About grid controls

A grid, like a data list, is a web control bound to a data object that renders each data object row in an HTML table. The topic Grid versus Data List Control highlights the main differences between grids and data lists.

Tip If your grid displays jumbled DATETIME fields in Design Preview, check the locale setting on the MRI Dreamscape menu bar; for example, .

Appearance properties

Use the Appearance properties to customise the fonts, colours, borders, grid lines, title, header and footer of a grid. You can change the appearance of alternate rows in the Alternate section.

Populating grids

Grids may be populated in these ways:

From a data object, when the page loads.
Using a workflow.

The FSI JavaScript API provides a method, fsi.refreshGrid(), to refresh the data.

Populating a grid from a data object

You can bind a grid directly to a data object; the grid is automatically populated when the page loads.

In the Data properties for the grid you select the data object from the Display Table list.

With the Auto Generate property disabled, you specify each column you want displayed with the Header name and the corresponding data object Column.

With the Auto Generate property enabled, every column is included for display, but you can use Delete to remove any that you don't want.

Because data editing by the user is possible, each column has an Error section to impose formatting rules. See Column format rules below.

Populating a grid from workflow output

Using this method, the workflow output is directed to the grid; the grid columns and headings are set automatically by the workflow. The Display Table property in the Data section should be left empty.

For a simple implementation using the system defaults for appearance, filters, formatting and so on, there is no other configuration needed for the grid.

Setting the workflow output

A grid (and a data list) expects a JSON string from a workflow output.

You can trigger the workflow in a number of ways; from a button, when the page loads, or from the FSI JavaScript API. The important point is to set the workflow Output Parameter to bind to the grid control.

When the workflow is executed by a button, the button Behaviour properties will include an Output Parameters section where you specify the control that workflow output will be directed to:

Similarly, when the workflow is executed by a page event (for example, Page Load), the event Behaviour properties will include an Output Parameters section where you specify the control that workflow output will be directed to. This example shows a workflow with no inputs which is executed when the page loads.

Data properties

Display Table sets the data object to populate the grid when the page loads.

Sort By and Sort Order: Use these properties to sort the initial grid display; you can sort by a column that isn't being displayed.

Page Document and Document Label: If the data object is used for storing document links, you can display a column showing the number of documents in each link. Page Document must be set to Show, and the additional column takes it's name from Document Label. See also: Document Linker Control.

Behaviour properties

Use the Type and On Click properties to run a workflow, JavaScript function, or web service when a user clicks any row in the grid.

Use Redirect URL to redirect to another page in the web application or to an external URL . The redirect is triggered in one of two ways:

When parameter Edit Row is Off, the redirect occurs when the user selects a row in the grid.
When parameter Edit Row is On, the redirect occurs when a row is selected in the grid, and the Redirect link at the top right of the grid is clicked.

When redirect is to a another page in the web application (Internal URL), the SystemId of the selected grid row will be available in the new page, and may be returned using fsi.getDataKey() in the page JavaScript. If the new page is bound to the same data object in the page Layout, then the data in the selected row will be available to controls in the new page.

These Behaviour properties add interactive features to the grid when enabled:

Grid Behaviour UI Properties

Show Check Box: Displays check boxes to allow selection of one or more rows, for example, for multiple row delete operations.

Column Filter: Displays the column names as Search fields and filters rows with matching text in the particular column.

Edit Row, Create Row, Delete Row: These add icons to the grid UI so that users can perform the appropriate function. When Edit Row is enabled, and a Redirect URL has been configured, the redirect is only triggered when a row is selected and the Redirect link is clicked; this allows rows to be selected for edit and delete functions. When Edit Row is not enabled, a redirect is triggered immediately when a row is selected, and therefore edit and delete functions can't be performed.

Search Box: Adds a Search box that filters rows with matching text anywhere in the row.

Reorder: When enabled, allows a user to drag-and-drop columns into a new order.

Show Column: Displays a pop-up where you can remove selected columns from the grid display. This feature is incompatible with Column Filter.

Show Paging: Enables pagination control in the grid. You can set Paging Type to server-side or client-side, and Paging Size to the default number of rows to display on each page.

Sortable: Add ascending and descending Sort controls to each column.

Select Rows: Options available:

Off - Data in the Grid cannot be selected
Single Row - Only a Single Row can be selected at a given time (default setting)
Multiple Row - Allow User to select multiple rows across pages

Filters

You apply a filter to a grid based on the value of a particular Column. The Condition parameter specifies the comparison operator; greater than, equals to, and so on.

A Control, for example a text box, is selected to provide the filter value, and you can optionally set the initial value using the Static Value parameter.

In use, when you change the filter value in the control and then click anywhere outside the control, the grid automatically refreshes to show the new filter results.

Formatting

Formatting can be applied to a column to change a cell's appearance based on its value. This formatting example displays cells in the column Years Service in red when the value is greater than 2 years.

Column format rules

Because data editing by the user is possible, each column has an Error section to impose formatting rules when a column is being edited.

The properties in the Error section are described below.

When a rule is broken during editing, an appropriate system error message is displayed. When Message has been set, the system messages are replaced by the contents of the Message field.

You can add a regex (regular expression) string to the Pattern property for pattern matching against the input field contents.

Required: Enable this to force input so that the column cannot be null.

The Min Value and Max Value properties set the minimum and maximum number of characters allowed for the column entry.

Pattern: Type a regex (regular expression) string for pattern matching against the input field contents. For example, the string below would enforce input of 1, or 2, or 3 numbers followed by '-' followed by 4 capital alpha characters.

[0-9]{1,3}-[A-Z]{4}

Images

When you display a data object VARBINARY column containing an image, a grid displays a thumbnail of the image.