This documentation supports the 22.1 version of BMC Helix Innovation Studio.

To view an earlier version, select the version from the Product version menu.

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

A Record grid is a built-in view component available in the View designer. You can add a record grid while creating a view or while editing an existing view definition.

The record grid component provides the following capabilities:

  • 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.
  • 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 define an additional query for the columns associated with named lists to filter the results at runtime.
  • 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.

    Important

    You cannot download attachments from external records.

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

Sample record grid using column layout:

Sample record grid using card layout:


Important

Application business analysts can customize the objects developed in their own applications and that are marked customizable by the administrator, but cannot customize the objects developed in com.bmc.arsys in Best Practice Customization mode. For example, objects in core BMC applications, such as Foundation, Approval, and Assignment cannot be customized in Best Practice Customization mode. For more information, see Customization layer


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 Settings , and complete the fields in different sections as described in the following table:

    FieldActionsExample
    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. 

  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:

    PropertyDescriptionExample
    Column headerSpecifies 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.
    SortableEnables sorting of the columns.
    FilterableEnables filtering of the columns.
    SearchableEnables search in the columns.
    Wrap textEnables text wrapping.
    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.
    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 you to build an additional query for the named list, which is used to filter the list at runtime.

    Click Click to build an expression to create an additional query. For more information about creating an expression, see Expression Editor.

    Important: This option is available only if the column is associated with a named list and the column is filterable.

    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 actionsConfigures 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:

    PropertyDescriptionExample
    LabelEnter the name for the new row action.

    IconSelect the icon for the action button. 
    Security record definition nameThe row action is hidden if you have no access to the selected record definition. 
    Security field nameThe 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 instanceDefine 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.
    DisabledDefine the expression based on which you can disable the action for the particular row. Click Click to build an expression to create the expression.
    HiddenDefine 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:

    PropertyDescriptionExample
    Enable filtering

    Turn on the toggle key to enable column filtering within the record on the application.


    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.

    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:

    PropertyDescriptionExample
    Card layout widthDefines 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 selectionTurn on the toggle key if you want to want to enable users to select single or multiple rows in the application user interface.
    Show border linesTurn on the toggle key to show border lines for the grid columns.
    Show striped rowsTurn on the toggle key to apply shading to alternate grid rows.
    Show data for all localesTurn on the toggle key if you want to display data for all locales in the grid at runtime.
    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:

    FieldDescriptionExample
    Edit grid columnsSelect 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.

      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

Create initial basic filters to display only the records that match the filter condition during runtime. For a detailed step-by-step procedure, see To add a record grid to a view definition.

Use this example to create an initial basic filter to display records assigned only to particular users. However, these filters can be used to filter any record type.

  1. In Properties, click and then click Filter.
  2. In Available Filters, expand Assignee, type in the assignee name, and press Enter.
    For example, type Smith and %son. By using the % wildcard, you can filter all the records that fully or partially match the text string entered by you.

    To add multiple assignee names, press Enter and type the name of the assignee.
  3. Click Apply.
    The basic filter for the grid is now set.
  4. To view the record grid with the filtered rows, click Preview.
    The record grid displays only those records that are assigned to the users named Smith and the users whose names end with son.

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

You can configure the record grid values to be clickable to open a new view.
  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 the Properties section, edit the column properties for the fields by using the edit option  on the fields. 
  3. To configure the column value as an action button, select Edit actions.
  4. In the Edit actions window, select Open View as shown in the following image:
  5. In the Selected Actions > Open View section, enter the following details:

    FieldsAction
    ViewSelect the view that you want to display in the deployed application.
    PresentationSelect the Full Width option.
    Launch Behavior

    Select the option to open the target view you selected. This field is displayed only if you select the Full Width option in the Presentation field. The Launch Behavior field provides the following options:

    • Open in same window

    • Open in new window

    (Version 20.08.01 and later) Important: If you set the Launch Behavior to Open in same window option, and if the user uses the Ctrl+click action or right-click and select Open in a new tab. The link in the record grid cell opens the view in a new window.

  6. Click Save.

Example: To add actions to the grid cells

The following example shows the steps to apply row actions to delete Closed tickets.

  1. Create a record definition and data that you can use in the Record Grid component.
    For a detailed step-by-step procedure to create a record definition, see
    Creating or modifying regular record definitions.
  2. 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.
  3. Click Edit row actions
  4. In the Edit row actions window, click Add row action.
  5. In the Label field, provide an appropriate label for the action; for example; Delete
  6.  In the Icon field, click Browse, search for a Trash icon, and click Select.
  7. To display the Delete action only for the rows with Closed status, and to disable the action for all other statuses in the Disabled field, click Click to build an expression.
    For example, p
    rovide the following expression:
    Status!=Closed
  8. To define the actions after you click the Delete option, click Edit actions.
  9. In the Edit actions window, select Delete records.
    1. In the Records field, select Display ID.
    2. From the Record definition list, select the appropriate record definition. 
  10. To refresh the grid after the delete operation, select the Refresh action, and then in the View/Component field, select the view or component that you want to refresh. 
  11. Click Save.
    The row action is now applied to the grid cells.
  12. To view the record grid, click Preview.

The following image displays the record grid with the configured row actions:

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

The following example shows the steps to apply styling to the grid cells in the Status column based on the status values:  

  1. Create a record definition and data that you can use in the Record Grid component.
    For a detailed step-by-step procedure to create a record definition, see
    Creating or modifying regular record definitions.
  2. 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.
  3. Click Edit grid columns and select the Status column, or click the edit option for the Status column. 
  4. In the Edit grid columns window, select the Status column, and click Edit cell display properties.
  5. In the Edit cell display properties for Status window, click Add cell display properties.

  6. In the Field value condition, click Click to build an expression.

  7. In Edit Expression window, build an expression for the status marked as New; for example Status=0.

  8. Select Display as badge.

  9. From the Badge color list, select Success

  10. In the Edit cell display properties for Status window, to add a new text styling, click Add cell display properties.

  11. In the Field value condition, click Click to build an expression.

  12. In Edit Expression window, build an expression for the status marked as Closed; for example Status= 4.

  13. Select Display as badge.

  14. From the Badge color list, select Danger

  15. Click Save.
    The text styling is now applied to the grid cells.
  16. To view the record grid, click Preview.

The following image displays the record grid with the text styling for the Status column:

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

  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. Select the Filterable and Searchable check boxes if not selected.

  5. 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.

    • 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.
      The following image shows an example of a named list field with the Typeahead keystroke count set to 2. 

  6. Click Save.

The following images show how the named list values are filtered at runtime based on the value set in the Typeahead keystroke count field:

ImageDescription

In this example, the Typeahead keystroke count is set to 0. On the Applied filters window, when the input focus is on the named list field or when the user clicks in the field, all the values in the named list are displayed.

When there are many values, the first 50 values are displayed.

In this example, the Typeahead keystroke count is set to 1. The user must enter at least one character to see the filtered list. 

The user types "m" and the values containing the character "m" are displayed.

Was this page helpful? Yes No Submitting... Thank you

Comments