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 including action, actions-menu, boolean, editable, text, text-field, status-pill, select
  • column/: Column configuration and management
  • 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.
  • grid-pro-genesis-datasource/: Client-side datasource implementation (CSRM-compatible)
  • state-persistence/: Classes related to saving and restoring grid state.
  • status-bar-components/: Status bar components including load-more, pagination, label-value, reload (requires AG Grid Enterprise)
  • tooltips/: Tooltip for errors that happen while syncing data with server after inline editing.
  • utils/: Utility functions for array manipulation, string processing, logging, and more.

Enterprise Features and Licensing

Important: Some Grid Pro features require AG Grid Enterprise licensing and module registration:

• Status Bar Components: All status bar functionality (with-status-bar, statusBarConfig) requires AG Grid Enterprise
• Server-Side Row Model: Server-side datasource requires @ag-grid-enterprise/server-side-row-model
• Advanced Filtering: Some advanced filtering features may require Enterprise modules
• Excel Export: Excel export functionality requires AG Grid Enterprise

For production use, you must obtain appropriate AG Grid Enterprise licenses. Contact AG Grid for licensing information.

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);

Enterprise Module Registration

REQUIRED for Status Bar and Server-Side Datasource Features

If you plan to use Status Bar components (with-status-bar) or Server-Side datasource (<grid-pro-server-side-datasource>), you MUST register the appropriate AG Grid Enterprise modules:

import { ModuleRegistry } from '@ag-grid-community/core';

// Required for Status Bar components (with-status-bar, statusBarConfig)
import { StatusBarModule } from '@ag-grid-enterprise/status-bar';

// Required for Server-Side datasource (<grid-pro-server-side-datasource>)
import { ServerSideRowModelModule } from '@ag-grid-enterprise/server-side-row-model';

// Register the enterprise modules you need
ModuleRegistry.registerModules([
  StatusBarModule,          // Required for: with-status-bar, statusBarConfig
  ServerSideRowModelModule, // Required for: <grid-pro-server-side-datasource>
]);

Note: These modules require a valid AG Grid Enterprise license for production use.

Grid Pro Element Attributes

The <grid-pro> element supports the following attributes and properties:

Grid Attributes

|Name|Type|Default|Description| |----|----|-------|-----------| | add-index | number | 0 | Index position for new rows when using applyTransaction or applyTransactionAsync. | | async-add | boolean | false | Use applyTransactionAsync for add transactions (better performance for large datasets). | | async-remove | boolean | false | Use applyTransactionAsync for remove transactions (better performance for large datasets). | | async-update | boolean | true | Use applyTransactionAsync for update transactions (enabled by default for performance). | | auto-cell-renderer-by-type | boolean | false | Genesis-specific: Enable automatic cell renderer selection by data type. | | column-component-name | string | grid-pro-column | Internal: Name of the column component to use. | | enable-cell-flashing | boolean | false | Enable cell flashing animations when cell values change. | | enable-row-flashing | boolean | false | Enable row flashing animations for add transactions. | | enabled-row-flashing | boolean | false | @deprecated - Use enable-row-flashing instead. | | grid-autosizing | boolean | false | Important: Controls automatic column sizing on interaction. Disables manual column widths and local storage persistence of widths. | | header-case-type | GridProCaseType | CONSTANT_CASE | Transform header names: camelCase, capitalCase, dotCase, headerCase, noCase, paramCase, pascalCase, pathCase, sentenceCase, snakeCase. | | header-height | number | - | Custom header height in pixels. Overrides theme defaults. | | only-template-col-defs | boolean | false | Genesis-specific: Use only template-defined column definitions, ignore metadata. | | pagination | boolean | false | Enables pagination. Basic pagination works with AG Grid Community edition. Enterprise features like custom pagination components require AG Grid Enterprise. Works with both client-side and server-side datasources. | | pagination-page-size | number | 25 | Number of rows per page when pagination is enabled. | | persist-column-state-key | string | - | Key for persisting column state in local browser or KV storage. Essential for maintaining user preferences. | | persist-filter-model-key | string | - | Key for persisting filter model in local browser or KV storage. Maintains filter state across sessions. | | row-height | number | - | Custom row height in pixels. Overrides theme defaults. | | size-columns-to-content | boolean | false | Auto-size columns: Automatically sizes columns to fit their content using AG Grid's autoSizeAllColumns() method. When both size-columns-to-fit and size-columns-to-content are enabled, intelligent sizing automatically chooses the best approach based on content width vs available space. | | size-columns-to-fit | boolean | false | Fit columns to viewport: Automatically sizes columns to fit the available horizontal space using AG Grid's sizeColumnsToFit() method. When both size-columns-to-content and size-columns-to-fit are enabled, intelligent sizing automatically chooses the best approach based on content width vs available space. | | theme | string | alpine | AG Grid theme name. Available: alpine, alpine-dark, balham, balham-dark, material. | | with-status-bar | boolean | false | Enterprise Feature: Enables status bar at bottom of grid. Requires AG Grid Enterprise module. | | :customErrorHandlerTemplate | (prefix: string, gridErrorItems: GridProErrorItem<any>[]) => ViewTemplate | - | Custom error handling: Function that returns a custom template for displaying datasource errors. If not provided, uses the default error dialog. | | :eventsAndCallbacks | GridProEventsAndCallbacks | - | AG Grid events: Object containing AG Grid event handlers and callbacks. | | :gridComponents | {[componentName: string]: any} | - | Custom components: Object containing custom AG Grid components (cell renderers, editors, filters). | | :gridFontFace | string | defaultAgGridFontFace | Font configuration: Font face configuration for AG Grid themes. | | :rowData | any[] | - | Manual data: Array of row data for scenarios where you set data manually without using datasource components. | | :statusBarConfig | GridProStatusBarConfig | DEFAULT_STATUS_BAR_CONFIG | Enterprise Feature: Configuration for status bar components. Must use binding syntax with observable property. |

Custom Error Handling

Custom Error Handler Template: Grid Pro allows you to provide a custom template for displaying datasource errors using the customErrorHandlerTemplate attribute. This gives you full control over the error display UI.

Custom Error Handler Configuration

The customErrorHandlerTemplate property accepts a function that receives:

• prefix: Design system prefix (e.g., 'rapid', 'foundation')
• gridErrorItems: Array of error items with detail and type properties

interface GridProErrorItem<T = any> {
  detail: T;    // Error details (message, object, etc.)
  type: string; // Error type ('datasource', etc.)
}

Available Utility Functions:

Grid Pro exports an extractErrorMessage utility function that can help extract user-friendly error messages from error details:

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

// Usage in custom error templates
const message = extractErrorMessage(error.detail);

This utility handles various error detail formats and provides consistent message extraction.

Usage Examples

1. Simple Custom Error Dialog:

<grid-pro 
  :customErrorHandlerTemplate="${() => myCustomErrorTemplate}">
  <grid-pro-client-side-datasource
    resource-name="ALL_TRADES">
  </grid-pro-client-side-datasource>
</grid-pro>

Custom Error Template Implementation:

import { html, when } from '@microsoft/fast-element';
import { GridProErrorItem } from '@genesislcap/grid-pro';

const customErrorTemplate = (prefix: string, errors: GridProErrorItem<any>[]) => html`
  ${when(() => errors.length > 0, html`
    <div class="custom-error-overlay">
      <${prefix}-card class="error-card">
        <h3>⚠️ Connection Error</h3>
        <p>Unable to load data. Please check your connection.</p>
        <${prefix}-button @click=${(x) => x.querySelector('grid-pro').hideDatasourceError()}>
          Dismiss
        </${prefix}-button>
      </${prefix}-card>
    </div>
  `)}
`;

2. Advanced Custom Error Handler with Details:

<grid-pro 
  :customErrorHandlerTemplate="${() => advancedErrorHandlerTemplate}">
  <grid-pro-server-side-datasource
    resource-name="ALL_POSITIONS">
  </grid-pro-server-side-datasource>
</grid-pro>

Advanced Error Template Implementation:

import { html, when, repeat } from '@microsoft/fast-element';
import { extractErrorMessage } from '@genesislcap/grid-pro';

const advancedErrorHandlerTemplate = (prefix: string, errors: GridProErrorItem<any>[]) => html`
  ${when(() => errors.length > 0, html`
    <div class="error-overlay">
      <${prefix}-dialog class="custom-error-dialog" open>
        <h2 slot="header">Data Loading Failed</h2>
        <div class="error-content">
          <p>Failed to load grid data:</p>
          <ul class="error-list">
            ${repeat(errors, html`
              <li>${(error) => extractErrorMessage(error.detail)}</li>
            `)}
          </ul>
        </div>
        <div slot="footer">
          <${prefix}-button 
            appearance="accent" 
            @click=${(x) => {
              const grid = x.querySelector('grid-pro');
              grid.hideDatasourceError();
              grid.querySelector('grid-pro-server-side-datasource')?.restart();
            }}>
            Reload Data
          </${prefix}-button>
          <${prefix}-button 
            appearance="lightweight" 
            @click=${(x) => x.querySelector('grid-pro').hideDatasourceError()}>
            Dismiss
          </${prefix}-button>
        </div>
      </${prefix}-dialog>
    </div>
  `)}
`;

Status Bar Configuration

Enterprise License Required: Status bar functionality requires the AG Grid Enterprise license and the StatusBarModule to be registered (see Enterprise Module Registration above). Status bar components will only be displayed if the Enterprise module is properly licensed and configured.

Important Datasource Behavior:

• Client-side datasources: All status bar components are available (rows, maxRows, loadMore, reload, aggregation)
• Server-side datasources: loadMore component is automatically disabled and will not be shown, even if configured

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

interface GridProStatusBarLoadMoreConfig {
  onLoadMore?: () => void;    // Custom callback function (defaults to datasource.loadMore())
  appearance?: string;        // Button appearance: 'accent', 'lightweight', 'neutral', 'outline', 'stealth'
  tooltip?: string;          // Custom tooltip text
}

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

Status Bar Component Availability by Datasource Type:

| Component | Client-Side Datasource | Server-Side Datasource | Description | |-----------|------------------------|-------------------------|-------------| | rows | Available | Available | Shows row count information | | maxRows | Available | Available | Shows maximum rows limit | | loadMore | Available | Disabled | Load more button (infinite scroll alternative) | | reload | Available | Available | Reload/refresh button | | aggregation | Available | Available | Shows aggregation values for selected columns |

Complete Usage Examples:

1. Client-Side Grid with All Status Bar Components:

@customElement({
  name: 'client-side-grid-example',
  template: html`
    <grid-pro 
      pagination
      pagination-page-size="50"
      with-status-bar
      :statusBarConfig="${(x) => x.clientStatusBarConfig}"
      persist-column-state-key="client-grid-columns"
      persist-filter-model-key="client-grid-filters"
      enable-row-flashing
      enable-cell-flashing
      header-case-type="headerCase"
      theme="alpine-dark"
      async-update
      auto-cell-renderer-by-type>
      <grid-pro-client-side-datasource
        resource-name="ALL_TRADES"
        max-rows="1000"
      ></grid-pro-client-side-datasource>
    </grid-pro>
  `
})
export class ClientSideGridExample extends GenesisElement {
  // Client-side datasource: ALL status bar components available
  @observable clientStatusBarConfig: GridProStatusBarConfig = {
    rows: true,              // Available
    maxRows: true,           // Available  
    loadMore: {              // Available - shows load more button
      appearance: 'accent',
      tooltip: 'Load more trades from server'
    },
    reload: {                // Available
      tooltip: 'Refresh all trade data'
    },
    aggregation: true        // Available - shows aggregation values
  };
}

2. Server-Side Grid (loadMore Automatically Disabled):

@customElement({
  name: 'server-side-grid-example',
  template: html`
    <grid-pro 
      pagination
      pagination-page-size="100"
      with-status-bar
      :statusBarConfig="${(x) => x.serverStatusBarConfig}"
      persist-column-state-key="server-grid-columns"
      enable-row-flashing
      theme="balham">
      <grid-pro-server-side-datasource
        resource-name="ALL_TRADES"
        max-rows="500"
      ></grid-pro-server-side-datasource>
    </grid-pro>
  `
})
export class ServerSideGridExample extends GenesisElement {
  // Server-side datasource: loadMore automatically disabled
  @observable serverStatusBarConfig: GridProStatusBarConfig = {
    rows: true,              // Available - shows row counts
    maxRows: true,           // Available - shows max rows info
    loadMore: true,          // DISABLED - even if true, will not show (by design when it is a server-side datasource)
    reload: {                // Available - shows reload button
      tooltip: 'Refresh trade data from server'
    },
    aggregation: true        // Available - shows aggregation values
  };
}

3. Manual Data Grid with Custom Components:

@customElement({
  name: 'manual-data-grid',
  template: html`
    <grid-pro 
      :rowData="${(x) => x.rowData}"
      :gridComponents="${(x) => x.gridComponents}"
      :eventsAndCallbacks="${(x) => x.eventsAndCallbacks}"
      theme="balham"
      header-height="50"
      persist-column-state-key="manual-grid-state"
      enable-cell-flashing>
    </grid-pro>
  `
})
export class ManualDataGrid extends GenesisElement {
  @observable rowData = [
    { id: 1, name: 'John Doe', age: 30, department: 'Engineering' },
    { id: 2, name: 'Jane Smith', age: 25, department: 'Marketing' },
    // ... more data
  ];

  @observable gridComponents = {
    customRenderer: CustomCellRenderer,
    customEditor: CustomCellEditor,
    customFilter: CustomFilter
  };

  @observable eventsAndCallbacks = {
    onCellValueChanged: (event) => {
      console.log('Cell value changed:', event);
      // Handle cell value changes
    },
    onRowSelected: (event) => {
      console.log('Row selected:', event);
      // Handle row selection
    },
    onGridReady: (event) => {
      console.log('Grid ready:', event);
      // Grid initialization complete
    }
  };
}

4. Grid with Auto-Size Columns:

@customElement({
  name: 'auto-size-columns-grid',
  template: html`
    <grid-pro 
      size-columns-to-content
      theme="alpine"
      persist-column-state-key="auto-size-grid-state">
      <grid-pro-client-side-datasource
        resource-name="ALL_TRADES"
      ></grid-pro-client-side-datasource>
    </grid-pro>
  `
})
export class AutoSizeColumnsGrid extends GenesisElement {
  // The size-columns-to-content attribute will automatically adjust column widths
  // based on content when data is loaded or updated
}

5. Grid with Intelligent Column Sizing (Both Attributes Enabled):

@customElement({
  name: 'intelligent-sizing-grid',
  template: html`
    <grid-pro 
      grid-autosizing
      size-columns-to-content
      theme="alpine"
      persist-column-state-key="intelligent-grid-state">
      <grid-pro-client-side-datasource
        resource-name="ALL_TRADES"
      ></grid-pro-client-side-datasource>
    </grid-pro>
  `
})
export class IntelligentSizingGrid extends GenesisElement {
  // When both grid-autosizing and size-columns-to-content are enabled:
  // - If content width <= available width: uses sizeColumnsToContent (natural content width)
  // - If content width > available width: uses sizeColumnsToFit (fits to viewport)
  // This provides optimal user experience by avoiding horizontal scrollbars when possible
}

4. Theme and Font Customization:

@customElement({
  name: 'themed-grid',
  template: html`
    <grid-pro 
      theme="material"
      :gridFontFace="${(x) => x.customFontFace}"
      header-height="48"
      row-height="42"
      header-case-type="sentenceCase">
      <grid-pro-server-side-datasource
        resource-name="ALL_POSITIONS"
      ></grid-pro-server-side-datasource>
    </grid-pro>
  `
})
export class ThemedGrid extends GenesisElement {
  @observable customFontFace = `
    @font-face {
      font-family: 'CustomGridFont';
      src: url('path/to/custom-font.woff2') format('woff2');
    }
  `;
}

Datasource 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

|Name|Type|Default|Description| |----|----|-------|-----------| | resource-name | string | - | Required. The name of the target Data Server query or Request Server requestReply. | | is-snapshot | boolean | false | Request a snapshot from the server. | | criteria |string| - |Clients can send a Groovy expression to perform filters on the query server; these remain active for the life of the subscription.| | max-rows | number | 250 | Maximum number of rows to be returned as part of the initial message, and as part of any additional MORE_ROWS messages. This will not affect the number of rows displayed| | order-by | string | - | This option can be used to select a Data Server index (defined in the Data Server query), which is especially useful if you want the data to be sorted in a specific way. For REQUEST_SERVER scenarios, you can use as FIELD_A ASC FIELD_B DESC. By default, rows are returned in order of creation (from oldest database record to newest).| | view-number | number | - | The desired view/page you want data from. |

DATASERVER only attributes

|Name|Type|Default|Description| |----|----|-------|-----------| | fields | string | - | This optional parameter allows you to select a subset of fields from the query if the client is not interested in receiving all of them. | | max-view | number | 1000 | Maximum number of rows to track as part of a client "view" | | moving-view | boolean | false | If true, when the maximum number of rows defined in max-view is reached, the Data Server will start discarding the oldest rows (in terms of timestamp) and sending newer rows. If false, the updates in the server will be sent to the front end regardless of order. Note that this will only update the UI; no changes will be performed in the database.| | reverse | boolean | false | This option changes the Data Server index iteration. For example, if you are using the default index, the query will return rows in order from the newest database records to the oldest.|

REQUEST_SERVER only attributes

|Name|Type|Default|Description| |----|----|-------|-----------| | disable-polling | boolean | false | This option disables polling if set to true (data updates for the grid will not be fetched automatically).| | polling-interval | number | 5000 | This option enables you to set a custom polling frequency (in milliseconds) for a Request Server resource. Note that this option only works with Request Server resources; if your resource is a Data Server query, your grid is updated in real time. | |request| any | - | Similar to fields but for Request Server scenarios. This optional parameter enables you to specify request fields, which can include wildcards.| |request-auto-setup| boolean | true | This option, if set to true, will automatically set up the request based on the datasources's metadata.|

Component Attributes

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

<grid-pro-client-side-datasource>

|Name|Type|Default|Description| |----|----|-------|-----------| | restart-on-reconnection | boolean | true | This option, if set to true, will force the resource data to be reloaded upon a reconnection event.| | keep-col-defs-on-clear-row-data | boolean | false | This option, if set to true, will retain column definitions upon a restart or clearRowData event. |

<grid-pro-server-side-datasource>

|Name|Type|Default|Description| |----|----|-------|-----------| | zero-based-view-number | boolean | false | This option, if set to true, will make the starting VIEW_NUMBER zero-based (starting from 0 instead of 1).| | live-updates | boolean | false | This option enables live updates for the grid if set to true.|

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>

Enterprise License Required: Server-side datasource requires AG Grid Enterprise licensing and the ServerSideRowModelModule to be registered (see Enterprise Module Registration above).

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.
  • Custom Sort Indicators: Server-side datasources automatically display always-visible sort indicators on sortable columns, providing better visual feedback about which columns can be sorted even when not currently sorted.
• 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 ORDER_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).

| Feature | Client-Side | Server-Side | Notes | | --- | --- |--- | --- | | All Data in Client | Yes | No | Free | | Fetch Data as User Scrolls | No | Yes | Free | | Row Sorting | (client) | (client OR server) our component is server-only | Free | | Row Filtering | (client) | (client OR server) our component is server-only | Free | | Quick Filter | Yes | Yes | Free | | Floating Filters | Yes | Yes | Free | | Dynamic Row Height | Yes | Yes | Free | | Row Grouping | (client) | (server) | Paid (Enterprise) | | Row Pivoting | (client) | (server) | Paid (Enterprise) | | Lazy Loading Row Groups | No | Yes | Paid (Enterprise) | | Value Aggregation | (client) | (server) | Paid (Enterprise) | | Row Selection | Yes | Yes | Free | | Specify Selectable Rows | Yes | Yes | Free | | Header Checkbox Selection | Yes | Yes | Free | | Range Selection | Yes | Yes | Free | | Column Spanning | Yes | Yes | Free | | Column Pinning | Yes | Yes | Free | | Row Pinning | Yes | Yes | Free | | Pagination | Yes | Yes | Free | | Custom Filters | Yes | Yes | Free | | Cell Editors | Yes | Yes | Free | | Cell Renderers | Yes | Yes | Free | | Value Getter | Yes | Yes | Free | | Value Setter | Yes | Yes | Free | | Value Formatter | Yes | Yes | Free | | Value Parser | Yes | Yes | Free | | Full Width Rows | Yes | Yes | Free | | CSV Export | Yes | (data on screen) | Free | | Excel Export | Yes | (data on screen) | Paid (Enterprise) | | Clipboard Copy & Paste | Yes | Yes | Free | | Update via Transaction | Yes | Yes | Free | | Update via Async Transactions | Yes | Yes | Free |

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. Requires AG Grid Enterprise licensing.

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.

Cell Renderers

Grid Pro provides a comprehensive set of built-in cell renderers for common data types and use cases:

Available Renderers

• ActionRenderer: Renders action buttons for row operations (edit, delete, custom actions)
• ActionsMenuRenderer: Renders a dropdown menu with multiple actions
• BooleanRenderer: Displays boolean values as checkboxes or toggle switches
• EditableRenderer: Provides inline editing capabilities for cells
• TextRenderer: Basic text display with optional formatting
• TextFieldRenderer: Text input field for editing
• StatusPillRenderer: Displays status values or countdown timer as colored pills/badges
• SelectRenderer: Dropdown selection for predefined options

Custom Renderers

You can create custom cell renderers by implementing the AG Grid ICellRenderer interface and registering them via the gridComponents property.

Cell Editors

Grid Pro includes predefined cell editors for common data types:

Available Editors

• DateEditor: Date picker with configurable format and validation
• NumberEditor: Numeric input with formatting and validation options
• StringEditor: Text input with optional validation and placeholder
• SelectEditor: Dropdown selection with support for dynamic options
• MultiselectEditor: Multi-selection dropdown for multiple values

Editor Configuration

Each editor supports extensive configuration through editor parameters, allowing customization of appearance, validation, and behavior.

Status Bar Components

Enterprise Feature: Status bar components require AG Grid Enterprise licensing and the StatusBarModule to be registered.

Available Components

• LabelValueStatusBarComponent: Displays key-value pairs in the status bar
• LoadMoreStatusBarComponent: Provides load more functionality (client-side only)
• PaginationStatusBarComponent: Shows pagination controls and information
• ReloadStatusBarComponent: Adds reload/refresh button

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