@genesislcap/grid-pro v14.276.0

Genesis Foundation Grid Pro

The @genesislcap/grid-pro package provides a collection of grid-related components and utilities for Genesis applications.

API Documentation

For more detailed information on API and configurations, please refer to the API documentation in the docs/api directory.

Features

• Easy integration: Quick setup with modern JavaScript frameworks and libraries.
• Customizable: support for custom headers, mapping values, text formatting, custom cell-renderers and more (more on grid options later).
• Flexible: when it comes to working with data grid-pro makes it easy by supporting filtering, editing, sorting, pagination (depending on configuration).
• Events and callbacks: There is a large number of events and callbacks provided by the grid, you can find details here.
• Simple Data or Connected Data: There are two main use cases for our Grid Pro component
  • Simple Data: when you have your own data model and flow (JSON, external/custom REST APIs, etc) but still want to use a rich data grid component with all its features (filtering, sorting, custom cell renderers, etc).
  • Connected Data: when you have a Data Server or Request Server available and ready to use, and you don't want to worry about handling data transformations, updates, deletes and cell renderers in the grid.
• State persistence: ability to save and restore grid state.
• Row models: support for both client-side and server-side row models.

Project Structure

• src/: Source code for the package, including cell-editors, cell-renderers, datasources and utility functions.
  • cell/: The Grid Pro Cell element and template
  • cell-editors/: predefined custom cell-editors for common data types including date, number, string, select, multiselect
  • cell-renderers/: predefined custom cell-renderers.
  • **column/ for a given column.
  • datasource/: Genesis Datasource elements, responsible for fetching data for the Grid Pro element (multiple implementations available, for both client-side and server-side row models).
  • external/: External assets such as fonts and styles for themes.
  • state-persistence/: Classes related to saving and restoring grid state.
  • tooltips/: Tooltip for errors that happen while syncing data with server after inline editing.
  • utils/: Utility functions.

Getting Started

Installation

To enable this module in your application, follow the steps below.

1. Add @genesislcap/grid-pro as a dependency in your package.json file. Whenever you change the dependencies of your project, ensure you run the $ npm run bootstrap command again. You can find more information in the package.json basics page.

{
  "dependencies": {
    "@genesislcap/grid-pro": "latest"
  },
}

Setup

Make sure the required grid components are registered with your design system. Depending on how the app was created this might have been setup for you automatically (genx cli / create). The design system name might vary (you can create a custom one for your app), using rapid in this example.

import { provideDesignSystem, baseComponents } from '@genesislcap/rapid-design-system';
import { rapidGridComponents } from '@genesislcap/rapid-grid-pro';

provideDesignSystem().register(baseComponents, rapidGridComponents);

Attributes

There are many attributes that can be set on a datasource component.

Resource Attributes

Some resource related attributes are DATASERVER or REQUEST_SERVER specific while others can be used with both.

Attributes that are common between DATASERVER and REQUEST_SERVER

DATASERVER only attributes

REQUEST_SERVER only attributes

Component Attributes

There are additional attributes that can affect the behavior of a datasource component.

<grid-pro-client-side-datasource>

<grid-pro-server-side-datasource>

More details about our datasource implementations here.

Usage - Simple Data example

import { ColDef, GridOptions } from '@ag-grid-community/core';
import { GridPro } from '@genesislcap/grid-pro';
import { customElement, DOM, GenesisElement, html, observable, ref } from '@genesislcap/web-core';

@customElement({
  name: 'simple-grid-example',
  template: html`
    <rapid-grid-pro ${ref('grid')}></rapid-grid-pro>
  `,
})
export class SimpleGridExample extends GenesisElement {
  @observable
  public grid: GridPro;

  private columnDefs: ColDef[] = [
    { headerName: '#', colId: 'rowNum', valueGetter: 'node.id', width: 80, pinned: 'left' },
    { headerName: 'Athlete', field: 'athlete', width: 150, pinned: 'left' },
    { headerName: 'Age', field: 'age', width: 90, pinned: 'left' },
    { headerName: 'Country', field: 'country', width: 150 },
    { headerName: 'Year', field: 'year', width: 90 },
    {
      headerName: 'Date',
      field: 'date',
      width: 110,
      filter: 'agDateColumnFilter',
      filterParams: {
        buttons: ['apply', 'reset'],
        browserDatePicker: true,
        comparator: (filterLocalDateAtMidnight, cellValue) => {
          // Handling '29/08/2004' date format - adjust as need to match your date format
          // https://www.ag-grid.com/javascript-data-grid/filter-date/
          const dateAsString = cellValue;
          if (dateAsString == null) return -1;
          const dateParts = dateAsString.split('/');
          const cellDate = new Date(
            Number(dateParts[2]),
            Number(dateParts[1]) - 1,
            Number(dateParts[0]),
          );
          if (filterLocalDateAtMidnight.getTime() === cellDate.getTime()) {
            return 0;
          }
          if (cellDate < filterLocalDateAtMidnight) {
            return -1;
          }
          if (cellDate > filterLocalDateAtMidnight) {
            return 1;
          }
          return 0;
        },
      },
    },
    { headerName: 'Sport', field: 'sport', width: 150, editable: true },
    { headerName: 'Gold', field: 'gold', width: 100 },
    { headerName: 'Silver', field: 'silver', width: 100 },
    { headerName: 'Bronze', field: 'bronze', width: 100 },
    { headerName: 'Total', field: 'total', width: 100, pinned: 'right' },
  ];

  private rowData = [
    {
      athlete: 'Michael Phelps',
      age: 27,
      country: 'United States',
      year: 2012,
      date: '12/08/2012',
      sport: 'Swimming',
      gold: 4,
      silver: 2,
      bronze: 0,
      total: 6,
    },
    {
      athlete: 'Natalie Coughlin',
      age: 25,
      country: 'United States',
      year: 2008,
      date: '24/08/2008',
      sport: 'Swimming',
      gold: 1,
      silver: 2,
      bronze: 3,
      total: 6,
      isActionDisabled: true,
    },
    // ...
  ];

  private gridOptions: GridOptions = {
    defaultColDef: {
      resizable: true,
      filter: true,
    },
    columnDefs: this.columnDefs,
    rowData: this.rowData,
  };

  connectedCallback() {
    super.connectedCallback();
    DOM.queueUpdate(() => {
      this.grid.gridOptions = this.gridOptions;
    });
  }
}

Usage - Connected Data example (client-side datasource)

@customElement({
  name: 'connected-grid-client-side-example',
  template: html`
    <rapid-grid-pro enable-row-flashing enable-cell-flashing>
      <grid-pro-client-side-datasource
        resource-name="ALL_TRADES"
        criteria="INSTRUMENT_ID == 'TSLA'"
      ></grid-pro-client-side-datasource>
    </rapid-grid-pro>
  `,
})
export class ConnectedGridClientSideExample extends GenesisElement {}

Usage - connected data example (server-side datasource)

Note: if pagination is set to false the grid will be in infinite scroll mode.

@customElement({
  name: 'connected-grid-server-side-example',
  template: html`
    <rapid-grid-pro enable-row-flashing enable-cell-flashing>
      <grid-pro-server-side-datasource
        resource-name="ALL_TRADES"
        criteria="INSTRUMENT_ID == 'TSLA'"
      ></grid-pro-server-side-datasource>
    </rapid-grid-pro>
  `,
})
export class ConnectedGridServerSideExample extends GenesisElement {}

Genesis Datasource

This folder contains implementations of Genesis datasource components, responsible for fetching data for Genesis Grid Pro components.

This document outlines the available features of our two "Grid Pro" datasources: <grid-pro-client-side-datasource> and <grid-pro-server-side-datasource>.

\<grid-pro-client-side-datasource>

Client-Side Features

• Sorting: Order by any column, ASC or DESC.
• Filtering:
  • Filtering options are automatically generated, based on the resource's metadata.
  • String Filters:
    • contains
    • not contains
    • equals
    • not equals
    • starts with
    • ends with
    • blank
    • not blank
  • Number/Date Filters:
    • equals
    • less than
    • less than or equal
    • greater than
    • greater than or equal
    • in range
• Filter Combinations (Max 2 filters can be combined):
  • filter1 AND filter2
  • filter1 OR filter2

Client-Side Notes

• Works with both DATASERVER and REQUEST_SERVER resources.
• Operations like sorting and filtering are performed on the client-side.
• Suitable for datasets that are small to medium in size and can be entirely loaded into the client.

\<grid-pro-server-side-datasource>

Server-Side Features

• Sorting: Order by any INDEX column/field, ASC or DESC.
  • This is a server limitation. For each column that needs to have "sorting" the developer will need to have an INDEX for it. See more about Genesis database indexes.
  • By default, sorting is disabled on ALL columns… BUT if we detect valid '` indexes" from the metadata those column/fields will be setup to have sorting.
  • If the user attempts to force sortable we'll check if it's really ok to do that + warn in the logs about it + try to mention other available indexes.. if any at all.
• Filtering:
  • Filtering options are automatically generated, based on the resource's metadata.
  • String filters
    • blank
    • contains
    • equals
    • notBlank
    • notEqual
    • wordStartsWith
  • Number filters
    • equals
    • notEqual
    • greaterThan
    • greaterThanOrEqual
    • lessThan
    • lessThanOrEqual
    • inRange
    • blank
    • notBlank
  • Date filters
    • equals
    • lessThan
    • greaterThan
    • inRange
    • isToday
    • blank
    • notBlank

Server-Side Notes

• Operations like sorting and filtering are pushed to the backend.
  • Filtering uses CRITERIA_MATCH param
  • Sorting uses ORDERY_BY param
  • Both work the same way, once filtering/sorting is applied the datasource component "resets itself", basically starting a new stream with the updated params.
• LIMITATIONS
  • Sorting can only be applied to "index" fields/columns. Also mentioned here. More details here and here.
  • ROWS_COUNT doesn't reflect the correct amount when a CRITERIA_MATCH (filtering) is applied. Example: X resource has 100 records. A criteria is specified so it returns only 50 records… the rows count sent from the server is still 100. Because of that we have to manually/locally calculate that.
• Suitable for large datasets where only a subset of data is loaded into the client based on user interactions.

Supported Row Models

We support all of the AG's Row Models. More on JavaScript Grid: Row Models | AG Grid (ag-grid.com).

In the table below you can find a complete "feature list" of all the possibilities of client/server-side row models (and others too.. that can be manually enabled/integrated but we don't expose any components for those yet).

It's important to note that any client app can implement the other Row Models to their own needs. Our Grid Pro component is not tied to the datasource, it's the opossite.. so datasources can be as specialized/customized as possible.

Infinite and Viewport row models are also supported but not offered "out of the box" (devs will have to create their own component).

Summary

• Client-Side Datasource: Suitable for smaller datasets where all data can be loaded into the client. Operations like sorting and filtering are performed on the client-side.
• Server-Side Datasource: Ideal for large datasets, where operations are pushed to the backend to ensure performance and consistency. Data is fetched as needed based on user interactions.

Performance

DOM Virtualisation

DOM Virtualisation is a powerful technique that enhances the performance of grid components by only rendering the rows and columns that are currently visible in the viewport. This approach significantly reduces the memory footprint and improves the rendering speed, enabling all of our "grid components" to handle larger datasets more efficiently.

• How It Works: Instead of rendering all rows and columns, the grid dynamically generates the DOM elements for only the visible part of the dataset. As the user scrolls, rows and columns are created or destroyed on the fly, ensuring a smooth scrolling experience.
• Benefits:
  • Reduced memory usage since only a subset of rows and columns are in the DOM at any given time.
  • Faster initial rendering and improved responsiveness, even with large datasets.
  • Enhanced user experience with seamless scrolling and interaction.

For more details, visit the AG Grid DOM Virtualisation documentation (also available in Tabulator Virtual DOM)

Pagination Performance

Pagination is another effective technique to improve performance in AG Grid by breaking down large datasets into smaller, manageable chunks or pages. This allows the grid to load and render only a subset of data at a time, significantly reducing the load on the client.

• How It Works: Data is divided into pages, and only the data for the current page is loaded and rendered. Users can navigate through pages using pagination controls.
• Benefits:
  • Minimizes the amount of data loaded into the client at any given time, enhancing performance.
  • Provides a structured way to navigate large datasets, improving usability.
  • Reduces the risk of browser crashes and memory overflow issues.

Combined Approach

By leveraging both DOM Virtualisation and Pagination, our "grid components" can efficiently manage and display larger datasets on the client-side. Here's how these techniques work together:

• Initial Load: Only the data for the first page is loaded, minimizing the initial load time.
• Scrolling: As users scroll, DOM Virtualisation ensures only the visible rows and columns are rendered, maintaining performance.
• Page Navigation: Users can navigate through pages to access the full dataset without overwhelming the client.

Status Bar and Pagination

The Grid Pro component supports a comprehensive status bar system at the bottom of the grid, along with flexible pagination options. The status bar can be configured with various panels to display information like row counts, custom content, and action buttons.

Enterprise License Requirement

Important: Status bar functionality requires the AG Grid Enterprise module to be available. Status bar components will only be displayed if the Enterprise module is properly licensed and configured.

Basic Status Bar Usage

The status bar can be enabled using the datasource attributes and configured through the status-bar-config attribute:

<rapid-grid-pro>
  <grid-pro-client-side-datasource
    resource-name="ALL_TRADES"
    with-status-bar="true"
    status-bar-config='{"rows": true, "reload": true, "loadMore": true}'
  ></grid-pro-client-side-datasource>
</rapid-grid-pro>

Status Bar Configuration Interface

The status bar can be configured using the GridProStatusBarConfig interface:

interface GridProStatusBarConfig {
  rows?: boolean;                                    // Enable row count component (default: true)
  maxRows?: boolean;                                 // Enable max rows label-value component (default: false)
  loadMore?: boolean | GridProStatusBarLoadMoreConfig; // Enable/configure load more button
  reload?: boolean | GridProStatusBarReloadConfig;     // Enable/configure reload button
}

interface GridProStatusBarLoadMoreConfig {
  onLoadMore?: () => void;    // Custom callback function
  appearance?: string;        // Button appearance: 'accent', 'lightweight', 'neutral', 'outline', 'stealth'
  tooltip?: string;          // Custom tooltip text (default: 'Load More')
}

interface GridProStatusBarReloadConfig {
  onReload?: () => void;     // Custom callback function
  icon?: string;            // Custom icon name (default: 'refresh')
  tooltip?: string;         // Custom tooltip text (default: 'Reload')
}

Status Bar Configuration Examples

Basic Configuration

// Simple boolean configuration
const statusBarConfig = {
  rows: true,
  maxRows: true,
  loadMore: true,
  reload: true
};

Advanced Configuration with Custom Callbacks

// Advanced configuration with custom callbacks and styling
const statusBarConfig = {
  rows: true,
  maxRows: false,
  loadMore: {
    onLoadMore: () => {
      console.log('Custom load more logic');
      // Your custom load more implementation
    },
    appearance: 'accent',
    tooltip: 'Load 50 more records from server'
  },
  reload: {
    onReload: () => {
      console.log('Custom reload logic');
      // Your custom reload implementation
    },
    icon: 'refresh',
    tooltip: 'Refresh all data from server'
  }
};

TypeScript Usage in Component

import { GridProStatusBarConfig } from '@genesislcap/grid-pro';

@customElement({
  name: 'my-grid-component',
  template: html`
    <rapid-grid-pro with-status-bar>
      <grid-pro-client-side-datasource
        resource-name="ALL_TRADES"
        :status-bar-config=${(x) => x.statusBarConfig}
      ></grid-pro-client-side-datasource>
    </rapid-grid-pro>
  `
})
export class MyGridComponent extends GenesisElement {
  @observable statusBarConfig: GridProStatusBarConfig = {
    rows: true,
    maxRows: true,
    loadMore: {
      appearance: 'outline',
      tooltip: 'Load more trades from server'
    },
    reload: {
      tooltip: 'Refresh trade data'
    }
  };
}

Client-Side vs Server-Side Datasource Differences

Client-Side Datasource (<grid-pro-client-side-datasource>)

Available Status Bar Components:

• Row Count: Shows total and filtered row count (agTotalAndFilteredRowCountComponent)
• Max Rows: Shows the maximum rows limit
• Load More: Button to load additional rows from server
• Reload: Button to reload/refresh the datasource
• Pagination: Full pagination controls when pagination is enabled

Example:

<rapid-grid-pro with-status-bar>
  <grid-pro-client-side-datasource
    resource-name="ALL_TRADES"
    status-bar-config='{"rows": true, "maxRows": true, "loadMore": true, "reload": true}'
  ></grid-pro-client-side-datasource>
</rapid-grid-pro>

Server-Side Datasource (<grid-pro-server-side-datasource>)

Available Status Bar Components:

• Row Count: Shows total row count only (agTotalRowCountComponent)
• Max Rows: Shows the maximum rows limit
• Load More: NOT AVAILABLE - Server-side uses infinite scroll or pagination instead
• Reload: Button to reload/refresh the datasource
• Pagination: Full pagination controls when pagination is enabled

Important Notes:

• Load More button is automatically disabled for server-side datasources
• Server-side row model handles data loading through infinite scroll or pagination
• Row count component shows total rows (not filtered count due to server limitations)

Example:

<rapid-grid-pro with-status-bar>
  <grid-pro-server-side-datasource
    resource-name="ALL_TRADES"
    status-bar-config='{"rows": true, "maxRows": true, "reload": true}'
    pagination="true"
  ></grid-pro-server-side-datasource>
</rapid-grid-pro>

Pagination

Basic Pagination Setup

<!-- Client-side pagination -->
<rapid-grid-pro pagination="true" pagination-page-size="25" with-status-bar="true">
  <grid-pro-client-side-datasource
    resource-name="ALL_TRADES"
  ></grid-pro-client-side-datasource>
</rapid-grid-pro>

<!-- Server-side pagination -->
<rapid-grid-pro pagination="true" with-status-bar="true">
  <grid-pro-server-side-datasource
    resource-name="ALL_TRADES"
    max-rows="50"
  ></grid-pro-server-side-datasource>
</rapid-grid-pro>

Pagination with Custom Status Bar

When pagination is enabled, Grid Pro automatically:

• Adds pagination controls to the status bar
• Suppresses the default AG Grid pagination panel
• Positions pagination controls on the right side of the status bar

<rapid-grid-pro pagination="true" with-status-bar="true">
  <grid-pro-client-side-datasource
    resource-name="ALL_TRADES"
    status-bar-config='{"rows": true, "reload": true}'
  ></grid-pro-client-side-datasource>
</rapid-grid-pro>

Default Status Bar Layout with Pagination:

• Left: Row count component (agTotalAndFilteredRowCountComponent for client-side, agTotalRowCountComponent for server-side)
• Right: Pagination controls with navigation buttons and page information

Built-in AG Grid Status Bar Panels

Grid Pro supports all standard AG Grid status bar panels:

• agTotalRowCountComponent: Displays the total row count
• agTotalAndFilteredRowCountComponent: Displays the total and filtered row count
• agFilteredRowCountComponent: Displays the filtered row count
• agSelectedRowCountComponent: Displays the selected row count
• agAggregationComponent: Displays aggregations for the selected range

Custom Status Bar Components

Grid Pro provides several custom status bar components accessible through the GridProStatusBarTypes enum:

LabelValueStatusBarComponent

A flexible component that displays a label and value pair:

import { GridProStatusBarTypes } from '@genesislcap/grid-pro';

// In your grid options:
statusBar: {
  statusPanels: [
    { 
      statusPanel: GridProStatusBarTypes.labelValue,
      statusPanelParams: { 
        label: 'Max Rows', 
        value: 250,
        hide: false 
      },
      align: 'left',
    },
  ],
},

LoadMoreStatusBarComponent

A button component that allows users to load additional rows (client-side only):

import { GridProStatusBarTypes } from '@genesislcap/grid-pro';

// In your grid options:
statusBar: {
  statusPanels: [
    { 
      statusPanel: GridProStatusBarTypes.loadMore,
      statusPanelParams: {
        onLoadMore: () => console.log('Loading more data...'),
        appearance: 'outline',
        tooltip: 'Load more rows from server'
      },
      align: 'right',
    },
  ],
},

ReloadStatusBarComponent

A refresh button component that allows users to reload the grid data:

import { GridProStatusBarTypes } from '@genesislcap/grid-pro';

// In your grid options:
statusBar: {
  statusPanels: [
    { 
      statusPanel: GridProStatusBarTypes.reload,
      statusPanelParams: {
        onReload: () => console.log('Reloading data...'),
        icon: 'refresh',
        tooltip: 'Reload the datasource'
      },
      align: 'right',
    },
  ],
},

PaginationStatusBarComponent

A pagination control component that provides navigation buttons and page information:

import { GridProStatusBarTypes } from '@genesislcap/grid-pro';

// In your grid options:
statusBar: {
  statusPanels: [
    { statusPanel: 'agTotalAndFilteredRowCountComponent', align: 'left' },
    { statusPanel: GridProStatusBarTypes.pagination, align: 'right' },
  ],
},

Manual Status Bar Configuration

You can also manually configure the status bar using direct grid options:

import { GridProStatusBarTypes } from '@genesislcap/grid-pro';

const gridOptions = {
  statusBar: {
    statusPanels: [
      { statusPanel: 'agTotalAndFilteredRowCountComponent', align: 'left' },
      { 
        statusPanel: GridProStatusBarTypes.labelValue,
        statusPanelParams: { label: 'Active Records', value: 1250 },
        align: 'center'
      },
      { 
        statusPanel: GridProStatusBarTypes.reload,
        statusPanelParams: {
          tooltip: 'Refresh all data'
        },
        align: 'right' 
      },
    ],
  },
};

Complete Usage Examples

Client-Side with Full Status Bar

<rapid-grid-pro 
  pagination="true" 
  pagination-page-size="50" 
  with-status-bar="true">
  <grid-pro-client-side-datasource
    resource-name="ALL_TRADES"
    max-rows="500"
    status-bar-config='{
      "rows": true,
      "maxRows": true,
      "loadMore": {
        "appearance": "accent",
        "tooltip": "Load 50 more trades"
      },
      "reload": {
        "tooltip": "Refresh trade data"
      }
    }'
  ></grid-pro-client-side-datasource>
</rapid-grid-pro>

Server-Side with Pagination

<rapid-grid-pro 
  pagination="true" 
  with-status-bar="true">
  <grid-pro-server-side-datasource
    resource-name="ALL_TRADES"
    max-rows="100"
    status-bar-config='{
      "rows": true,
      "maxRows": true,
      "reload": true
    }'
  ></grid-pro-server-side-datasource>
</rapid-grid-pro>

Infinite Scroll with Minimal Status Bar

<rapid-grid-pro with-status-bar="true">
  <grid-pro-server-side-datasource
    resource-name="ALL_TRADES"
    max-rows="50"
    status-bar-config='{"rows": true, "reload": true}'
  ></grid-pro-server-side-datasource>
</rapid-grid-pro>

Accessibility Features

All status bar components include comprehensive accessibility support:

• ARIA labels and roles for screen readers
• Keyboard navigation support (Tab, Enter, Space)
• Focus management and visual indicators
• Semantic HTML structure with proper landmarks
• Tooltips and descriptions for interactive elements

Performance Considerations

• Status bar components are lightweight and optimized for performance
• Components are only rendered when enabled in configuration
• Event listeners are properly cleaned up when components are destroyed
• Status updates are debounced to prevent excessive re-renders

License

Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact Genesis Global for more details.

Licensed components

Genesis low-code platform