Using the Relational Grid Widget

The relational grid enables you to replace Single and Multi-Relational field controls on custom state and transition forms with an embedded listing report that displays the related items and their fields (as opposed to viewing only the Value display format for related items). This enables users to view relevant information without having to navigate away from the form.

In a state form, users can view the list of related items and view specific fields on those items in a columnar format (depending on the fields that are defined in the report definition).

In a transition form, users can select an item using a radio button control for Single-Relational fields, or they can select multiple items using check boxes for Multi-Relational fields, which updates the underlying relational field when the transition is finished.

Because the results are displayed using a report that is defined in SBM Composer, you can choose which fields to display, what search filter to apply to limit candidate records, and query at runtime values that enable dynamic filtering of related items at runtime.

Setting up a Relational Grid

Before you begin, determine the application and table that are associated with the relational field that you want to display using the grid. You can find these details on the Options tab of the relational field.

To set up a relational grid:

Create a Report Definition in SBM Composer.
1. In the application you noted earlier, right-click on the associated table, and then select Create new Report Definition for this table.
2. Drag fields from the Report Palette to define the columns that you want to display, the sort order to apply, and create a search filter to limit the items that are returned in the report.
3. Optionally, use a query at runtime parameter in your search filter to dynamically filter the results at runtime.
Configure the relational grid widget.
1. Drag and drop a Relational Grid widget on to your form.
2. On the General tab, click Configure.
3. Select the relational field and report definition that you defined earlier. If the target table is in a different process app and the application has not been referenced, you must add an application reference to make the report available. For details, see Creating Application References.
4. Select Automatically bind compatible parameters to have SBM Composer attempt to map query at runtime parameters for you.
5. Click OK to finish.
Configure the report query to filter results.
1. Open the Query tab.
2. Select a project constraint to limit results to a particular project.
3. Map controls to the widget to enable dynamic filtering. You can add EditBox and Button controls to the form, and then map a query at runtime field in your report to the EditBox. This creates a search field that exposes the query at runtime capability. For example, if your report contains a search filter like:
```
Title contains '(Query at runtime)'
```
  Add an EditBox (named EscalatedIssue in this example), and then map it to the Title field:
4. Open the Refresh tab, select the button control that you added, and then select On click to refresh the widget when the button is clicked.

At runtime, when a user enters text in the search field and clicks the button, the results will be filtered by the text that is entered.

Using Selected Values in the Relational Grid

This section provides a brief example that demonstrates how you can use values in selected items in the grid.

In transition forms, you can map the value or values of selected records to populate other controls. For example, you can add a Text control that displays the currently selected Severity values in the target table.

On the Refresh tab of the Text control, type { in the Display text field, and then select the relational grid and field:

Select On data change to have the text field contents update whenever the search button is clicked.

For Single Relational fields, because the display text of the text control can contain multiple references, you can construct any string from the contents of the related fields.

If the relational grid is associated with a Multi-Relational field, {GridWidgetName.ColumnName} is replaced by a comma-separated list of the values from the referenced field.

Considerations for State Forms

On state forms, the relational grid displays records that are not selected in the relational field unless you filter the results in the grid to only display records that are referenced by the relational field.

You can accomplish this by creating a relational field in the child item that points back to the parent item. You can then create a report that displays only the selected records by using a query such as:

Title contains (Query at runtime)
AND
ParentItem in (Query at runtime)

In the widget's Query tab, add the parent's record ID to restrict the results:

ParentItem: {_RecordId}

This ensures that the relational grid displays only the records contained in the Multi-Relational field when it is used on a state form.

Using the Relational Grid Widget

Setting up a Relational Grid

Using Selected Values in the Relational Grid

Considerations for State Forms

Related Topics