Grid widget

A grid widget displays cases or tasks from a dataset in a table (grid). You can include some or all of the dataset columns in the grid. You can also configure the grid to display additional details for the selected case and/or include options for users to perform activities on the cases or execute the tasks listed in the grid.

When you add a grid widget to a view you must select the dataset you want to use. If you only want to display cases that are related to the case currently being viewed (such as all order cases for the current customer), apply a current case filter to the dataset.

To configure the grid, select the grid widget and in the properties pane click grid to open the grid designer.

Note:

If your application uses legacy grids, some of the features described below will not be available. To convert all legacy grids included in views of a particular casetype to the latest grid design, open the casetype, click the hamburger menu, and select Convert grid (legacy) to grid. To enable or disable use of legacy grids in your Studio, open Settings > Platform settings and update the Use legacy grids option as required.

Display data from a dataset

All the columns from the selected dataset are available but they are hidden by default. To display a column in the grid, select Columns, then select the relevant column and turn the Hide toggle off.

The column heading is inherited from the dataset by default. To change the heading in the grid, edit the Title field. You can also use the individual column settings to give users the ability to search, re-order, hide, and resize each of the columns in the grid.

By default, items are listed in the grid according to the sort order of the dataset. To specify a different sort order, open the grid display options and use the Order column option to specify the column by which you want to order items in the grid. To control the number of items displayed on each page of the grid, configure the Pagination settings.

To change the order of columns in the grid, drag and drop the columns in the grid designer preview.

Tip:

If you add a column to a dataset, the column is not displayed in the grid widget automatically. To show the column, edit the grid column settings to change it from hidden to visible.

Date display format

For columns that contain either date or datetime values, you can use the Render style options to control how the data is displayed. Depending on the selection, the format may be adjusted according to the user's locale.

You can preview how dates and times are formatted and (where applicable) rendered in different locales from Moment.js:

• Date only - formatted with LL.
• Time only - formatted with LT.
• With seconds & ms - formatted with YYYY-MM-DD hh:mm:ss.SSS.
• Short date only - formatted with L.
• Short date-time - formatted with L LT.
• Relative time - formatted with fromNow().
• Calendar time - formatted with calendar().
• UTC date-time - formatted with LLL.

Picklist value display format

For columns that contain an attribute that is mapped to a picklist, the label of the selected picklist item is displayed. For example, the items in a picklist for a boolean attribute might have the labels Yes and No.

To display the stored value rather than the label (for example, true and false rather than Yes and No), change the Render style to Raw.

If the picklist is based on a dataset of cases, the label is rendered as a link to the relevant case by default.

• To display the label without a link, change the Render style to Picklist label.
• To display the case or task ID of the item without a link, change the Render style to Raw.

For more information about configuring the label for items in a picklist based on a dataset, see Picklists.

Tip:

If you change the sort order or filter the items in the grid based on a picklist column, the items are sorted or filtered based on the picklist value, rather than the label. You can apply filters and set the sort order when you configure the dataset. You can also set the sort order from the grid display options (using the Order column option). To allow users to sort or filter the grid by a particular column, enable Sortable and/or Searchable in the column settings.

Display column totals and other values

For each column in the grid you can display a count of the values. For example, in a grid listing Product cases, you might want to show the number of products with a value in the Description column.

For columns that contain numeric data, you can also display the sum, average, minimum, or maximum of the values. For example, in a grid listing Customer orders you might want to display the average of the values in the Order total column.

To display column values, open the Grid display options and select:

• Aggregation type and then select:
  • Current page to limit the aggregations to the items on the current page of the grid. This can be useful for large datasets when you have enabled pagination for the grid.
  • Full dataset to perform the aggregations on all items in the grid (regardless of pagination).
• Aggregation position to specify where the column values are displayed.

To add an aggregation for a particular column, open the individual column settings and select:

• Aggregation operator and choose the operation you want to perform. Sum, Min, Max, and Average should only be applied to columns containing numeric data. Select Static to display text without performing an aggregation.
• Modify aggregated text to configure the text displayed. Use ${value} as a placeholder for the aggregated value. For example, if you enter Average order value: ${value} and the average of a column with data type single currency money was €1024.64, then Average order value: €1024.64 would be displayed. If you do not configure any text, only the aggregated value is displayed (in this example, €1024.64).

Tip:

If you have allowed users to search or filter the items displayed in the grid, the aggregations update according to the rows that are currently included.

Display additional case details

You can give users access to additional information about a case listed in the grid or a related case. For example, in a grid listing Order cases, you might want to provide access to details of the related Customer case.

The following options are available:

• "Go to case" click action: Navigates to the default view of the relevant case when the user clicks a row (when configured from the row options) or a specific column (when configured from the individual column options). By default, the view of the selected case is opened. To navigate to the view of a related case, select the column containing the relevant case ID from Click action case-id column override.
• "Open view" click action: Display a view of the selected case in a popup. This option can only be configured from the grid row options. From View to open, select the casetype view that you want to display. This can be a view of the casetype displayed in the grid, a related casetype, or a page casetype. You can also style the modal using Modal custom classes If you select a view of a related casetype, select the column containing the relevant case ID from Click action case-id column override.
• Embed a subwidget in the grid: Display details of the current case or related cases using a subwidget embedded in the grid. This is useful if you want to display additional information without navigating users away from the current page or view. For more information, see Embed a subwidget below.

Tip:

If you do not want to use these built-in options, you can instead use a grid widget as the master widget for a casedata, plugin, template, or view widget or embed one of these widgets as a subwidget. When a user selects a case from the grid widget, the case ID provides the context for the second widget. To use either of these options, ensure the Click action in the row settings is set to None.

Include activity options

For grids displaying a dataset of cases, you can include options for users to create new cases or edit or close the existing cases. You can also add custom activities. Select Activities and then configure the options as described below.

You can make activities available as buttons on the grid toolbar or as inline options on each row. By default, the activity name is used as the title, and is either displayed on the toolbar button or as a tooltip on the icon for inline options. To change the text, edit the Title field. You can also change the icon as required.

You can enable the toolbar from the grid display options. If you are including multiple activities on the toolbar, use the Order field to control the order in which they are displayed. To display a vertical separator between toolbar buttons, enable Breaker after.

Tip:

If you do not want to use these built-in options, you can instead embed an activity widget as a subwidget or use a grid widget as the master widget for an activity widget. When a user selects a case from the grid widget, the case ID is used to populate the second widget. To use either of these options, ensure the Click action in the row settings is set to None.

Add activity

To allow users to add a new case of the type listed in the dataset, select the relevant casetype activity.

Select one of the following activity types as appropriate:

• Toolbar standalone activity: Include the activity button in the grid toolbar. When a user clicks the button to initiate the activity, a popup containing the activity form is displayed.
• Inline-Add standalone add/start activity: Allow users to create a new case by adding a new row to the grid.

Ensure Check rights is set to Check once. The activity button is only displayed if the user has permission to perform the activity.

To refresh the grid automatically once a user has added a new case, set the When done refresh type to Reload current grid only. Users can also refresh the grid manually (regardless of this setting) using the refresh button at the bottom of the grid. Note that the new case is only displayed in the grid if it matches the filter criteria applied to the dataset.

Edit or close case activity

To allow users to make changes to attributes of a case listed in the grid, open the Edit activity settings and select the relevant form activity. To allow users to close cases listed in the grid, open the Close activity settings and select the relevant close case activity.

You can either enable checkboxes on the grid and display a button to initiate the activity from the toolbar, or display a button to initiate the activity on each row. Ensure that checkbox selection is enabled from the grid display options.

Select one of the following activity types as appropriate:

Activity type	Suitable for	Button position	Form displayed (in popup)
Toolbar activity on single item	Edit or close	Toolbar	Yes
Toolbar activity on single item (Quick)	Close	Toolbar	No
Toolbar activity on multiple items (With form)	Edit* or close	Toolbar	Yes
Toolbar activity on multiple items (Quick)	Close	Toolbar	No
Inline activity on single item	Edit or close	Inline	Yes
Quick-Inline Inline without form	Close	Inline	No
Inline-Edit edit activity on single cell (With form)	Edit**	N/A	Yes

* When the Toolbar activity on multiple items (With form) activity type is selected, a single form is displayed for all cases being edited or closed. If mappings have been applied to the form on start, the data for the first selected case is displayed in the form. Any values included in the form when the user submits it are applied to all selected cases. Ensure mappings are configured correctly to avoid overwriting data in all selected cases with the values from the first case. The activities are performed in a single transaction. This means if the activity on one of the cases fails, all changes will be rolled back.

** The Inline-Edit activity type allows users to edit the attributes of each case by double-clicking the relevant cell in the grid. Cells are only editable if the dataset column and activity form field refer to the same attribute and the form field is not read-only. Computed attributes cannot be edited.

Ensure Check rights is set to Inline: Check every row. The activity button is only displayed if the user has permission to perform the activity.

To refresh the grid automatically once a user has edited or closed the case(s), set the When done refresh type to Reload current grid only. Users can also refresh the grid manually (regardless of this setting) using the refresh button at the bottom of the grid.

Tip:

Performing activities can change the items displayed in a grid. A case will be hidden if it not longer matches the filter criteria applied to the dataset. For example, if the dataset excludes closed cases, then any cases that have been closed will no longer be listed. Similarly, changing a value can change the order of items if the grid (or dataset) is sorted by the values in that column.

View and perform tasks

For grids displaying a dataset of tasks, you can allow users to perform the task or view the data that has been submitted by clicking the row or a specific column. Configure the Click action from the row options or the individual column properties as appropriate:

• Execute activity or task: You can use this option for datasets containing:
  • Mandatory tasks on the current case or the entire platform. Mandatory tasks are generated when an activity with Execute rights is triggered by another activity. This is useful if you want to list all current mandatory tasks, or a subset such as all overdue mandatory tasks.
  • Optional tasks on the current case. These are activities on which Request rights have been granted, which means a user can initiate them at any time. When a user initiates the activity, the task is generated.
• Show submitted values (task): You can use this option for datasets containing all open and closed tasks on the platform (optionally filtered to include only closed tasks).

Embed a subwidget

You can add a subwidget to a grid widget in order to display additional information about the selected case when a user selects a row in the grid. For example, in a grid widget that lists expense claims awaiting approval, you might want to embed an activity widget so that users can review and update the claim details without leaving the grid. Similarly, in a grid widget listing products, you might want to embed another grid widget or a tile widget to display details of the product variants.

To embed a subwidget in a grid widget:

1. Add a grid widget and configure it as normal, ensuring the Row options > Click action is set to none.
2. Return to the view designer, find the grid widget but do not select it, and then click Add subwidget.
3. From the Subwidget properties pane, select the type of widget you want to embed:
   • To allow users to perform an activity on the case in the selected row, use an activity widget and then select the relevant activity.
   • To display more information about the case in the selected row, use a form, template, plugin or view widget, and then specify the element you want to use.
   • To display details of other cases, use a grid or template widget and specify the dataset containing the cases you want to display. If you only want to display details of cases related to the case in the selected row (such as a customer's orders or an employee's expense claims), apply a current case filter to the dataset.
4. Configure the subwidget properties as required for the selected widget type. If you have embedded another grid, click grid to open the grid designer and configure the columns, rows, and other options. Note that permissions to view the subwidget are controlled by the rights on the parent widget. You cannot apply conditions to subwidgets.

Tip:

Once you have selected the subwidget type you cannot edit the selection. To embed a different subwidget, delete the subwidget and start again.

Grid styling

You can set the size of the grid, the row heights, and the column widths manually from the grid designer. You can also apply one ore more CSS classes to the grid widget, and then apply styling to these using a CSS template on the platform, casetype or view.

A number of CSS selectors are also available for you to reference from a CSS template:

• If you have enabled Add value to row class for a particular column, the value from that column is automatically added to the row as a CSS class. For example, you might have a column that lists the RAG (red, amber, green) status of Contract cases. By adding the column value as a CSS class to each row, you can use this to apply the appropriate background color (or other style) to each row.

• If you have enabled the Open view row click action, you can style the popup using the following CSS selector: div[data-popup-view="1yyyy:xxxxx"]. You can also add your own custom CSS classes to the modal using the Modal custom classes option.

• If you have included aggregations on columns, you may consider adding a variation of the following CSS:

  .ag-invisible {
    display: none !important;  /*Ensure better alignment*/
  }
  .ag-floating-bottom .ag-cell, .ag-floating-top .ag-cell {
    background-color:#f00;  /*Highlight the aggregated row*/
    color:#0f0;
  }

For more information about applying CSS, see Style your application.