Data Grid

Overview

Responsive UI offers three approaches for displaying table data (i.e. data in rows and columns):

• Responsive table: Used for simple table data, with limited functionality
• Data grid: Used for complex table data, with more sophisticated functionality for interacting with the data
• Tree grid: Used for hierarchical table data

This document describes the data grid. Use a data grid when you need to display a complex set of data in rows and columns. Each column of the data contains a specific data field and each row contains a specific data object or record.

If the number of rows in the full data set is unbounded, use paging to display the data one “page” at a time.

Many grid cells are left-aligned, but it’s best to right-align currency and numeric values so the decimal points and commas line up, helping the user compare numeric values across rows.

The data grid includes several built-in behaviors including sorting, filtering, grouping, etc, that all work on the data set currently in your controller.

This built-in behavior works well with smaller data sets that can be managed all at once in the client. But with larger data sets, it isn’t feasible to manage the entire set of data in the client all at once. In this case you need to display only one “page” of the data in the client — typically a specific number of rows of data — but perform operations like sorting, filtering, etc across the entire data set on the server. In this case the data grid component is only used to house the current page of data; its built-in logic for sorting, filtering, etc is often not used in this case because those only operate on the rows currently in the data grid component. However, you will still use the data grid component’s headers for triggering the external sort, overriding the default internal sort logic to use server-based sorting logic.

To support smaller devices, wrap the data grid in a container that offers horizontal scrolling. That way the user can at least scroll to see all of the data. Also, include fewer columns than you would on larger devices if possible.

Grid Filters

Filtering allows the user to reduce the data set to only include rows that meet specific criteria. To filter a grid, the user enters specific search criteria using filter inputs at the top of the grid. The grid then hides all rows that don’t meet the specified filter criteria.

The grid and tree grid components support 5 different types of filters:

• Simple Text Filter: The user enters filter text into a simple text input. The grid only shows rows that contain that value in the filtered column. The user must manually clear the filter input’s content to remove the filter.
• Search Text Filter: The user enters filter text into a search text input. The grid only shows rows that contain that value in the filtered column. To remove the filter, the user can either press the Escape key or press an “X” button that displays within the input. This is an easier experience for the user, so we recommend using search text filters instead of text box filters.
• Select filter: The user selects a filter value from a dropdown list (i.e. an HTML “select” element). The grid only shows rows that contain that value in the filtered column. This dropdown must include an “all values” option to allow the user to remove the filter.
• p-dropdown filter: The user selects a filter value from a p-dropdown, which is a dropdown component that can display templated (formatted) values. The grid only shows rows that contain that value in the filtered column. This dropdown must include an “all values” option to allow the user to remove the filter.
• p-multiSelect filter: The user selects one or more filter values from a p-multiSelect, which is a dropdown component that allows the user to select multiple values. The grid only shows rows that contain any of the selected values in the filtered column. The user must clear the selected values in the multiselect to remove the filter.

Grid Buttons

Use the grid button component if you need to include one or more buttons in a data grid cell. It uses minimal, lightweight formatting that fits well into a data grid cell.

Development

Web component development

Component reference

p-table

ag-Grid

rui-grid-expand-collapse-button

Styling the Grid

Add the rui-grid-minimal CSS class to the grid component to get the proper styling.

Most grid cells are left-aligned, but it’s best to right-align currency and numeric values so the decimal points and commas line up, helping the user compare numeric values across rows.

Also, it can be helpful to wrap a grid within a div that has overflow-x:auto so that horizontal scrollbars display at smaller screen widths, since the data in your grid may not fit into the available width.

PrimeNG p-table

We use the PrimeNG p-table (previously known as “TurboTable”) as our open-source data grid component for Angular. Our theming adds appropriate colors for the currently selected theme color.

See https://primeng.org/table to download this component and for all information and tutorials on this component.

Expandable Grid Rows in p-table

Begin by importing the rui-buttons module into your application.

// import into app.module
import '@jkhy/responsive-ui-wc/components/rui-buttons/rui-buttons-imports';

The p-table supports expand/collapse functionality for grid rows. Given the following template with its let-user let-expanded="expanded" definitions:

<ng-template pTemplate="body" let-user let-expanded="expanded">

You should use the following HTML for the column within that template that contains the expand/collapse button:

<td>
    <a href="#" [pRowToggler]="user">
        <rui-grid-expand-collapse-button [isExpanded]="expanded"></rui-grid-expand-collapse-button>
    </a>
</td>

ag-Grid

If you need even more functionality than the PrimeNG grid provides, we also provide theming for the Community version of the ag-Grid. You can find more information about this component at https://www.ag-grid.com/.

If you’re adding ag-Grid to your solution for the first time, you will need to add the following CSS files to your bundle to ensure styling and theming are correct. You will also need to add class="ag-theme-balham" to your ag-grid-wc component.

• @ag-grid-community/all-modules/dist/styles/ag-grid.min.css
• @ag-grid-community/all-modules/dist/styles/ag-theme-balham.min.css

Angular component development

Component reference

p-table

ag-Grid

jha-grid-expand-collapse-button

Styling the Grid

Whether you’re using the p-table, p-treetable, or the ag-grid component (all described below), add the jha-grid-minimal CSS class to the grid component to get the proper styling.

Most grid cells are left-aligned, but it’s best to right-align currency and numeric values so the decimal points and commas line up, helping the user compare numeric values across rows.

Also, it can be helpful to wrap a grid within a div that has overflow-x:auto so that horizontal scrollbars display at smaller screen widths, since the data in your grid may not fit into the available width.

PrimeNG p-table

We use the PrimeNG p-table (previously known as “TurboTable”) as our open-source data grid component for Angular. Our theming adds appropriate colors for the currently selected theme color.

See https://primeng.org/table to download this component and for all information and tutorials on this component.

Expandable Grid Rows in p-table

Begin by importing the JhaButtonsModule module into your application.

// import into app.module
import { JhaButtonsModule } from '@jkhy/responsive-ui-angular/jha-buttons';

@NgModule({
    imports: [
        ...
        JhaButtonsModule,
        ...
    ]
})

export class AppModule(){}

The p-table supports expand/collapse functionality for grid rows. Given the following template with its let-user let-expanded="expanded" definitions:

<ng-template pTemplate="body" let-user let-expanded="expanded">

You should use the following HTML for the column within that template that contains the expand/collapse button:

<td class="jha-grid-expand-icon">
    <a href="#" [pRowToggler]="user">
        <jha-grid-expand-collapse-button [jhaIsExpanded]="expanded"></jha-grid-expand-collapse-button>
    </a>
</td>

ag-Grid

If you need even more functionality than the PrimeNG grid provides, we also provide theming for the Community version of the ag-Grid. You can find more information about this component at https://www.ag-grid.com/.

If you’re adding ag-Grid to your solution for the first time, you will need to add the following CSS files to your bundle to ensure styling and theming are correct. You will also need to add class="ag-theme-balham" to your ag-grid-wc component.

• @ag-grid-community/all-modules/dist/styles/ag-grid.min.css
• @ag-grid-community/all-modules/dist/styles/ag-theme-balham.min.css

Design

Figma design

• For the header row:
  • Add a grid row component as the header background. Set its Appearance property value to “Min w/o Separator”.
  • For each column header:
    • For each sortable column, add a column sort button (with appropriate sort direction) as a header for each column.
    • For each non-sortable column — for example columns that only display grid buttons — add a text element for the column header, apply the “rui-semibold” text style and the “rui-pacific/text-regular” color style.
  • Add a checkbox in the far-left column if your use case allows the user to select grid rows.
• For data rows:
  • Add a grid row component as the row background.
    • Set the component’s Appearance property value to** Min w/o Separator** if this is the first data row in the table. This state hides the top border line in the component (something we only want to display for subsequent data rows). Otherwise set its Appearance property value to Min with Separator.
    • Switch on the component’s Contains Input property if any cell in this row contains an input or button group component. This sets the row height to a value large enough to contain the input or button group.
  • If the row is expandable:
    • If the row is shown collapsed, add a grid row Expand-Collapse button in the far left column and switch off its Expanded property.
    • If the row is shown expanded, add a grid row Expand-Collapse button in the far left column and switch on its Expanded property.
  • Add a text element for each column. Apply the “rui-regular” text style and the “rui-pacific/text-regular” color style to the text element.
• For a selected data row:
  • Add a grid row component and set its Appearance property to “Selected”, as the background for the selected row.
  • If the row is expandable:
    • If the row is shown collapsed, add a grid row Expand-Collapse button in the far left column and switch off its Expanded property.
    • If the row is shown expanded, add a grid row Expand-Collapse button in the far left column and switch on its Expanded property.
  • Add a text element for each column. Apply the “rui-regular” text style and the “rui-pacific/text-regular” color style to the text element.

Adobe XD design

• For the header row:
  • Add a grid row component with the “Header” state as the background for the header row.
  • For each column header:
    • For each sortable column, add a sort button (with appropriate sort direction) to a header for each column.
    • For each non-sortable column — for example columns that include grid buttons — add a text element for the column header, apply the “JHA / Text / Regular” character style, then add Semibold styling for the text.
  • Add a checkbox in the far-left column if your use case allows the user to select grid rows.
• For the filter row (optional):
  • Add a grid row component with the “Filter” state as the background for the filter row.
  • Add a grid Filter Box component for each column. Size it to fit the width of the column.
• For data rows:
  • Add a grid row component as the background for the data row.
    • Set the component’s state to First Data Row if this is the first data row in the grid. This state hides the top border line in the component (something we only want to display for subsequent data rows).
    • Set the component’s state to Contains Input if any cell in this row contains an input or button group component. This sets the row height to a value large enough to contain the input or button group.
    • Set the component’s state to First Data Row Contains Input if this is the first data row in the grid and any cell in this row contains an input or button group component. This sets the proper height and hides the top line border.
    • Leave the component’s state as Default State otherwise.
  • If the row is expandable:
    • If the row is shown collapsed, add a grid row expand button in the far left column.
    • If the row is shown expanded, add a grid row collapse button in the far left column.
  • Add a text element for each data column. Apply the “JHA / Text / Regular” character style to the text element.
• For a selected data row:
  • Add a grid row component with the “Selected” state as the background for the selected row.
  • If the row is expandable:
    • If the row is shown collapsed, add a grid row expand button in the far left column.
    • If the row is shown expanded, add a grid row collapse button in the far left column.
    • Set the component’s state to “Selected”.
  • If the row is expandable and is shown collapsed, add a grid row expand button in the far left column. If the row is expandable and is shown expanded, add a grid row collapse button in the far left column.
  • Add a text element for each column. First apply the “JHA / Text / Regular” character style to the text element, then select the “JHA / Color / Btn / Primary / Fg” color asset to set the appropriate text color.
  • If you’re adding a grid “more” button to a column in a selected row, set “Selected Row” as the button’s state.
  • If you’re adding a grid icon button to a column in a selected row, first select the “Grid Button” state for the icon element, then select the “JHA / Color / Btn / Primary / Fg” color asset to set the appropriate color for the icon.
• It can be very helpful to nest all rows in the grid within a group, then turn that group into a vertical stack with 0 pixels spacing between each row. This helps keep the grid layout updated if you later add or delete rows in the grid.