Creating a tabular view of record instances by using a record grid

• Displays the record instances in a tabular format on the user interface of the deployed application.
• Displays the fields of the associated record definition on the user interface of the deployed application.
• Enables users to sort the rows in a grid.
• Enables users to add styling for a field in the Record grid, such as font size, bold, italics, text color, background color, and to change specific cell styling.
• Enables users to add row actions to the grid cells and provides them with the ability to right-click a row row action to open the view in a new window
• Enables users to filter the values in the grid and display only the rows that match the filter condition.
• Enables users to create predefined filter options for a column.
• Enables users to filter rows by cell selection.
• Enables users to set a typeahead keystroke count for the named list fields to facilitate data entry.
• Enables users to edit multiple records at a time.
• Switches to the card layout when the width of the grid is smaller than the configured card layout width.

• Downloads attachments if the record grid has a column bound to an attachment field. Download the attachment by clicking on the file name.

  Warning

  Important

  You cannot download attachments from external records.

The following image shows a sample record grid in a browser:

To add a record grid to a view definition

1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
2. Select the application to which you want to add a record grid.
3. On the Views tab, click the name of the view definition to which you want to add a record grid.
4. From Palette, drag the Record grid element to the canvas.

5. In Properties, click Component Properties , and complete the fields in different sections as described in the following table:

   Field	Actions	Example
   Mode	Select a mode in which you want the record definition to be displayed. You can select one of the following options: Record Association
   Record definition name	Select a record definition that you want to display in the view definition. This option is displayed only after you select Record option from the Mode field.
   Record definition to show	Select a record definition that must be displayed in the view definition. This option is displayed only after you select Association option from the Mode field.
   Association to use	Select an association (relationship) with the record definition. This option is displayed only after you select Association option from the Mode field.
   Associated record ID	Specify the ID of the record that you associate. This option is displayed only after you select Association option from the Mode field.
   (Optional) Associated role name	Specify the role name of the record in an association. When you provide the role name, the view component displays the associated record instances that match the role name. Otherwise, the view component displays all the associated record instances. This option is displayed only after you select Association option from the Mode field. Important: The Associated role name field is displayed only when you select a many-to-many association in the Association to use field.
   Get data for hidden columns	Turn on the toggle key to retrieve data for all the columns. Turn off the toggle key to retrieve data only for visible columns or those hidden columns that are referenced in the expressions. If you add a new visible column, the grid is refreshed.
   Show data for all locales	Turn on the toggle key if you want to display data for all locales in the grid at runtime.
   Show distinct records	Turn on the toggle key to display unique records in the grid. To check if the records are unique, all the grid's columns, including hidden or invisible columns, are considered. Important: If any of the following conditions are true, you see duplicate records in the record grid: A record grid uses the External record in the view definition. You don't have permission to view some columns that are displayed as blanks in the record grid.

6. (Optional) You can add the action buttons to the record grid. To add an action button, drag the Action button component on the record grid and enter the properties for the action button.
7. (Optional) You can build an expression, such as the view component properties, keywords, view input parameters, or static values. To build an expression, from the Initial Filters list, click Expression > Click to build an expression. From the list of available values, select the values that you require and then click OK. For more information, see Using the Expression Editor.
8. Save the view definition.
   To verify the record grid, preview the view definition.

Back to top

To edit the grid columns and the column properties for the fields

1. Add a record grid to a view definition.
   For a detailed step-by-step procedure to add a record grid, see To add a record grid to a view definition.
   The default columns are displayed on the grid.
2. To add or remove the columns on the record grid, click Edit grid columns.
3. In the Edit grid columns window, from the Available columns list, select the columns you want to display on the grid, and click Save.

4. To edit the column properties, click  edit for the respective column and modify the following column properties:

   Property	Description	Example
   Column header	Specifies the header of the column. By default, the field name is displayed as the column header. If required, modify the column header.
   Visible	Displays the column on the view by default.
   Sortable	Enables sorting of the columns.
   Searchable	Enables search in the columns.
   Wrap text	Enables text wrapping.
   Filterable	Enables filtering of the columns.  You can select from the following options: Always In advanced filter mode only In basic filter mode only Never
   Alignment	Enables text content to be aligned to the left, to the right, or centered.
   Width	Enables you to define the column width based on the content displayed in the column. You can use the following options: pixel—Define the column width in pixels. The value defined in pixels is absolute. Minimum value is 1. percent—Define the column width by percentage. Minimum value is 1. Maximum value is 100.  The value defined by percentage is relative and is related to the width of the table. For example, if you define the column width as 25%, the column will be 25% of the entire table.
   Named list	Enables you to assign a named list to the grid column if the field is not associated with one, or override the field’s default named list. If a named list is not selected, the default named list will be used. Important: A named list can be assigned to a column only if its field type is Text. To assign a named list to a grid column, the column’s Filterable property must be set to one of the following: Always In advanced filter mode only In basic filter mode only For more information, see To Add a named list to filterable grid columns in a record grid.
   Typeahead keystroke count	Enables you to set the number of keystrokes you want the users to type to load the filtered list of values.  You can set a value between 0 and 5. 0—If you set the value as 0, the first 50 entries are displayed when the input focus is on the field or when the user clicks in the named list field. 1-5—If you set the value between 1 and 5, the user must enter those many characters to view the filtered list. For example, if you set the value as 2, the user must enter at least two characters to view the filtered list containing those two characters. The default value is 1. Important: This option is available only for named list fields. For more information, see Example: To set the Typeahead keystroke count for named list fields.
   Additional named list filter	Enables additional filtering on a grid column associated with a named list by applying a logical expression. The option is displayed only if a named list is assigned to a filterable grid column.​​​​​ For more information, see Expression Editor.
   Edit cell display properties	Enables you to apply multiple display properties to grid cells.  To add display properties to grid cells, click Edit cell display properties. In the Edit cell display properties window, click Add cell display properties, and provide the details, such as the condition to apply the display properties to the text, badge color, icon, icon position, text color, and font size. For more information, see Example 7: To add dynamic text styling and icons to grid cells.
   Edit named filter options	Enables you to build and name custom filtering options by using expressions. To add a custom filtering option, click Edit named filter options. In the Edit named filter options window, click Add named filter option, and provide the filter name and the condition to filter the data in the column to display only the records that match the filter condition during runtime. For multiple filtering options, you can define the order in which the filters can run, by placing them in a sequence.
   Edit actions	Configures the column value as an action button. To add an action, click Edit actions and add the actions. In the Edit actions window, select the actions according to your requirements. For multiple actions, you can set the order in which actions will run by placing actions in a sequence. You can configure one or more of the following actions: Open an URL or start a process Open a view Associate, disassociate, delete records Edit multiple records Set properties for the action button Save, cancel, or refresh the task Launch Process designer

5. Click Save.

Back to top

To define a row action to the grid row

1. Add a record grid to a view definition.
   For a detailed step-by-step procedure to add a record grid, see To add a record grid to a view definition.
2. To create a new action, click Settings , from the General tab, click Edit row actions.

3. In the Edit row actions window, click Add row action, and provide the following details:

   Property	Description	Example
   Label	Enter the name for the new row action.
   Icon	Select the icon for the action button.
   Security record definition name	The row action is hidden if you have no access to the selected record definition.
   Security field name	The row action is hidden if you have no access to the selected field, or the row action is disabled if you have View permission for the selected field.
   Security record instance	Define the expression to select the record instance where the row action is hidden if you have no access to the selected field instance. Click Click to build an expression to create the expression.
   Disabled	Define the expression based on which you can disable the action for the particular row. Click Click to build an expression to create the expression.
   Hidden	Define the expression based on which you can hide the action for the particular row. Click Click to build an expression to create the expression.
   Available on devices	Select the device options on which the row action should be visible. You can select from the following options: Desktop Mobile Tablet By default, all three options are selected.
   Edit actions	Define the actions that you want to perform. To add an action, click Edit actions. In the Edit actions window, select the actions according to your requirements.

    

4. Click Save.

After you configure the row action, an Action column is added to the Record grid that displays the action for the grid cells. For more information, see Example 6: To add row actions to the grid cells.

Back to top

To enable filters in a record grid

1. Add a record grid to a view definition.
   For a detailed step-by-step procedure to add a record grid, see To add a record grid to a view definition.
   The default columns are displayed on the grid.

2. To define the enable filters for a record grid, click Settings , from the Filters tab specify the properties:

   Property	Description	Example
   Enable filtering	Turn on the toggle key to enable column filtering within the record on the application.
   Enable advanced filtering	Turn on the toggle key to allow end users to apply complex filter expressions at runtime by using advanced operators (AND/OR/NOT/LIKE/NULL), calculations, and keywords. The Enable Filtering toggle key must be turned on before enabling advanced filtering.  When switching between basic and advanced filtering modes, the system behaves as follows:  If you switch from basic to advanced mode, the system automatically converts the basic filters into an advanced expression. If you change the advanced filter and switch back to basic mode, the system displays a warning message, notifying you that it will clear the advanced filter expression. If you do not make changes in advanced mode, the system converts the expression back to basic mode without showing a warning. For more information, see Example: To create advanced filters.  Important: Enabling advanced filtering disables the Enable filter presets option.
   Field order	Click Edit to customize the order in which the fields are displayed in the filters on the record grid.This customization allows the end users to access them quickly.  In the Edit filter field order window, customize the field order based on the following options:  (Default) By name—Displays the fields alphabetically by name in the filters. You cannot reorder the fields. By column—Displays the fields based on the column order in the record grid. The visible fields appear first, followed by the hidden fields. You cannot reorder the fields. Custom—Displays the fields in a customized order. You can reorder the fields.
   Required number of filters	Select the required number of filters that you must apply to display data on the grid at runtime. The values in the list ranges from None to 5. None—No filters are required to display data on the grid. 1-5—Number of filters required to display data on the grid at runtime. If you select the number of filters as 1, and no filters are applied, the following warning message is displayed: You must apply a filter or perform a search to display data. If you select the number of filters between 2 and 5, and no filters are applied, the following warning message is displayed: You must apply at least <required number of filters> filters or perform a search to display data. Important: If no filters are applied and you perform a search, the data is displayed on the grid.
   Initial filters	Select from the following options to provide the filters that are applied to the application at runtime to display only those record fields that match the filter condition. You can select one of the following options: Basic—You can select values from the list of available filters to create a filter condition.  Expression—You can build an expression, such as the view component properties, keywords, view input parameters, or static values to create a filter condition.
   Enable filter presets	Turn on the toggle key to enable filter presets. Important: You cannot enable the filter preset if you have not turned on Enable filtering. Enabling filter presets disables the Enable advanced filtering option.
   Filter presets	Select a predefined set of record grid filters that users can apply.  Click Edit filter presets to select the predefined presets. In the Edit filter presets window, click Add filter preset, and provide the following details: Filter preset name—Enter the name for the new filter preset. Filter—Define the filter condition.
   Default filter preset	Select a filter preset to apply to the record grid when the user opens the view for the first time.

    

3. Click Save.

Back to top

To define the presentation for the record grid

1. Add a record grid to a view definition.
   For a detailed step-by-step procedure to add a record grid, see To add a record grid to a view definition.
   The default columns are displayed on the grid.

2. To define the presentation for a record grid, click Settings , from the Presentation tab specify the properties:

   Property	Description	Example
   Card layout width	Defines the width of the record grid view component at which the column layout switches to card layout.
   Initial sort column	Specifies the column with which the record instances will be sorted initially before the application is deployed. You can select the column and whether you want to sort the column in an ascending or descending order. By default, no column is selected. For example, if you select the Display ID column and set the sorting in ascending order, at runtime the records in the Display ID columns are sorted and will be displayed in ascending order.
   Enable row selection	Turn on the toggle key if you want to want to enable users to select single or multiple rows in the application user interface.
   Fit columns	Turn off the toggle to display a horizontal scrollbar in the record grid. You use the horizontal scrollbar to scroll the record grid to view additional columns.  If you turn on the toggle, the grid fits all the columns in the allocated width.
   Show border lines	Turn on the toggle key to show border lines for the grid columns.
   Show striped rows	Turn on the toggle key to apply shading to alternate grid rows.
   Available on devices	From the following device options, select the devices on which the components should be visible: Desktop Mobile Tablet By default, all three options are selected.

    

3. Click Save.

Back to top

To use the View preset selector in a record grid

1. Add a record grid to a view definition.
   For a detailed step-by-step procedure to add a record grid, see To add a record grid to a view definition.
2. In Properties, click Settings , and from the View preset selector list, select the view preset selector that you created in the view.
3. For more information, see Adding-a-View-preset-selector-to-a-view.
4. To configure the predefined view presets, click Edit view presets.

5. To edit the view preset condition, in the Edit view presets window, select the view preset, and update the following fields:

   Field	Description	Example
   Edit grid columns	Select the Visible checkbox to display the columns on the record grid when you select a view preset.
   Initial column sort	Specify the column with which the record instances will be sorted initially when you select a view preset. You can select the column and whether you want to sort the column in ascending or descending order.  For example, if you select Display ID and set the sorting in ascending order, at runtime when you select the view  preset, the records in the Display ID columns are sorted and will be displayed in ascending order. By default, no column is selected.
   Filter	Define the filters that you want to apply to your view preset, and click Apply filters. For example, you want to create a filter so that the record grid displays only those records that are assigned to users whose names end with son.

6. Click Save.

Back to top

To export rows from the record grid

You can download all or only selected records displayed in the grid to a CSV file. The downloaded CSV file includes all the columns that are currently selected or visible on the grid. 

1. Log in to your BMC Helix Innovation Studio application.
2. Select the view with the record grid.

   • To export all the grid rows, select Export > Export all rows.
     

     Warning

     Important

     For the Export all rows option, the maximum number of rows exported to the CSV file is 2000.

   • To export selected rows, select the rows you want to export, and select Export > Export selected rows.
     

The exported data is downloaded as a CSV file. 

Back to top

Example: To create initial basic filters

Example:To create advanced filters

Example: To configure the column value as an action button to open a new view

Example: To add actions to the grid cells

Example: To add dynamic text styling and icons to grid cells

Example: To set the Typeahead keystroke count for a named list field

Example: To add a named list to filterable grid columns

Example

1. Add a record grid to a view definition.
   For a detailed step-by-step procedure to add a record grid, see To add a record grid to a view definition.
   The default columns are displayed on the grid.
2. To add a named list column on the record grid, click Edit grid columns.
   To know how to create and use the named list field, see Facilitating-data-entry-through-named-lists.
3. In the Edit grid columns window, from the Available columns list, select the named list field you want to display on the grid.
4. From the Filterable list, select one of the following options: 
   • Always
   • In advanced filter mode only
   • In basic filter mode only
5. Use the Named list field to assign or override the named list associated with the column. If no selection is made, the field’s default named list will apply. 
6. In Typeahead keystroke count, from the list, select the number of characters that the users need to type to load the filtered values at runtime. You can set a value between 0 and 5.
7. (Optional​​​​​​) Click on the Additional named list filter to build a logical expression for additional filtering on the named list. For more information, see Expression-Editor. 
8. Click Save.

The following images show how the named list values are filtered at runtime: 

Image	Description
	In this example, the default named list for the column is All restaurants. However, you can override it by selecting another named list, such as Top rated restaurants. If no named list is selected in the list, the default named list All restaurants is used.
	In this example, the Restaurant column in the grid uses the All Restaurants named list, and the Typeahead Keystroke Count is set to 1. Suggestions are displayed once the user inputs a minimum of one character in the field.

Where to go from here

To define filter presets to search for records, see Defining-filter-presets-to-search-records.