@equinor/fusion-framework-module-ag-grid

AG Grid Module for Fusion Framework

This module provides an agnostic wrapper around the AG Grid library for use in Fusion applications. It sets up configuration and registers AG Grid modules, ensuring a consistent way to configure AG Grid and use it within Fusion portals and applications.

The intention of this module is to provide a consistent way to configure AG Grid and to ensure that the correct version of AG Grid is used.

[!TIP] This is the base package for AG Grid in Fusion, which means that ag-grid-enterprise and ag-grid-community is required to be installed. This package should be consumed by the host (portal) which configures AG Grid for the applications. See @equinor/fusion-framework-module-ag-grid for usage in applications.

Installation

npm i @equinor/fusion-framework-module-ag-grid

[!WARNING] Fusion will try to keep the semantic major and minor versions in sync with AG Grid, but there might be cases where this is not possible. So @equinor/fusion-framework-module-ag-grid and ag-grid might have different patch versions.

[!IMPORTANT] Before upgrading to AG Grid 33, please read remove all previous references to @equinor/fusion-react-ag-grid-styles, @ag-grid-community/* and @ag-grid-enterprise/* from your project dependencies.

Configuration

Portal

import { type FrameworkConfigurator } from '@equinor/fusion-framework';
import { enableAgGrid } from '@equinor/fusion-framework-module-ag-grid';

export async function configure(config: FrameworkConfigurator) {
    enableAgGrid(config, (builder) => {
        builder.setLicenseKey('your-license-key');
    });
}

Theming

This module uses the alpine theme as the base theme for AG Grid. The theme can be customized by providing a custom theme in the application.

[!TIP] AG Grid has a theme builder that can be used to preview and generate a custom theme.

enableAgGrid(configurator, (builder) => {
    builder.setTheme((theme) => {
        return theme.withParams({
            backgroundColor: "#1f2836",
            browserColorScheme: "dark",
            chromeBackgroundColor: {
                ref: "foregroundColor",
                mix: 0.07,
                onto: "backgroundColor"
            },
            foregroundColor: "#FFF",
            headerFontSize: 14
        });
    });
});

[!IMPORTANT] Themes are by default inherited from parent scopes (aka portals). This means that the theme set in the portal will be inherited by the application.

NOTE: Configured themes are global and will affect all instances of AG Grid in the application.

Customizing a grid instance

The module provides a hook to customize a grid instance.

import { useTheme } from '@equinor/fusion-framework-react-app/ag-grid';

const MyComponent = () => {
    const baseTheme = useTheme();
    const [hasError, setHasError] = useState(false);
    const theme = useMemo(() => baseTheme.withParams({
        // add red text color if error
        cellTextColor: hasError ? "#FF0000" : baseTheme.cellTextColor,
    }), [baseTheme, hasError]);

    return (
        <AgGridReact
            theme={theme}
            ...
        />
    );
};

Modules

Since AG Grid 33, all modules have been aggregated into a single package, which means the modules need to be defined in the application configuration.

import { enableAgGrid } from '@equinor/fusion-framework-module-ag-grid';
import { ClientSideRowModelModule } from '@equinor/fusion-framework-module-ag-grid/community';
import {
    ClipboardModule,
    ColumnsToolPanelModule,
    ExcelExportModule,
    FiltersToolPanelModule,
    MenuModule,
} from '@equinor/fusion-framework-module-ag-grid/enterprise';

export const configure: AppModuleInitiator = (configurator, { env }) => {
    enableAgGrid(configurator, (builder) => {
        builder.addModules([
            ClientSideRowModelModule,
            ClipboardModule,
            ColumnsToolPanelModule,
            ExcelExportModule,
            FiltersToolPanelModule,
            MenuModule,
        ]);
    });
};

[!IMPORTANT] Modules are required to be defined in the application configuration, as this is the only way to ensure that tree shaking works correctly.

Usage

Enterprise and Community features

Enterprise features are available from the namespace @equinor/fusion-framework-module-ag-grid/enterprise.

Community features are available from the namespace @equinor/fusion-framework-module-ag-grid/community.

[!NOTE] Since this is only a re-export of the ag-grid packages, there might be some issues with TypeScript typings.

Please leave an issue if you encounter any problems.

Example

import { AgGridReact } from "ag-grid-react";
import type {
  CellValueChangedEvent,
  ColDef,
  ValueParserParams,
} from "@equinor/fusion-framework-module-ag-grid/community";

function numberParser(params: ValueParserParams) {
  return Number(params.newValue);
}

const GridExample = () => {
  const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
  const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
  const [rowData, setRowData] = useState<any[]>(getData());
  const [columnDefs, setColumnDefs] = useState<ColDef[]>([
    { headerName: "Name", field: "simple" },
    { headerName: "Bad Number", field: "numberBad" },
    {
      headerName: "Good Number",
      field: "numberGood",
      valueParser: numberParser,
    },
  ]);
  const defaultColDef = useMemo<ColDef>(() => {
    return {
      flex: 1,
      editable: true,
      cellDataType: false,
    };
  }, []);

  const onCellValueChanged = useCallback((event: CellValueChangedEvent) => {
    console.log("data after changes is: ", event.data);
  }, []);

  return (
    <div style={containerStyle}>
      <div style={gridStyle}>
        <AgGridReact
          rowData={rowData}
          columnDefs={columnDefs}
          defaultColDef={defaultColDef}
          onCellValueChanged={onCellValueChanged}
        />
      </div>
    </div>
  );
};

Migration from AG Grid 32 to 33

Since AG Grid version 33, there have been significant breaking changes regarding the module structure and tree shaking. All modules have been consolidated into a single package, which necessitates defining the modules in the application configuration to ensure proper tree shaking. This change aims to streamline the module management process and improve performance by only including the necessary modules in the final bundle.

[!IMPORTANT]

It is crucial for developers to read this guide thoroughly to understand the changes and migration steps required for upgrading to AG Grid 33. Additionally, developers should also refer to the official AG Grid upgrade guide available at Upgrading to AG Grid 33 for comprehensive details and best practices.

Imports

Remove the following imports:

• @ag-grid-community/*
• @ag-grid-enterprise/*

Replace with:

• @equinor/fusion-framework-module-ag-grid

Modules

Since AG Grid 33, all modules have been aggregated into a single package, which means the modules need to be defined in the application configuration.

Move all ModuleRegistry.registerModules to builder.setModules in the application configuration.

// my-app/src/app.ts
- import { ClientSideRowModelModule } from '@ag-grid-community/client-side-row-model';
- import { ColumnsToolPanelModule } from '@ag-grid-enterprise/column-tool-panel';
- import { FiltersToolPanelModule } from '@ag-grid-enterprise/filter-tool-panel';
- import { MenuModule } from '@ag-grid-enterprise/menu';
- import { ExcelExportModule } from '@ag-grid-enterprise/excel-export';
- import { ClipboardModule } from '@ag-grid-enterprise/clipboard';
- import { RangeSelectionModule } from '@ag-grid-enterprise/range-selection';

- ModuleRegistry.registerModules([
-     ClientSideRowModelModule,
-     ColumnsToolPanelModule,
-     FiltersToolPanelModule,
-     MenuModule,
-     ExcelExportModule,
-     RangeSelectionModule,
-     ClipboardModule,
- ]);
// config.ts
+ import { enableAgGrid } from '@equinor/fusion-framework-module-ag-grid';
+ import { ClientSideRowModelModule } from '@equinor/fusion-framework-module-ag-grid/community';
+ import {
+     ClipboardModule,
+     ColumnsToolPanelModule,
+     ExcelExportModule,
+     FiltersToolPanelModule,
+     MenuModule,
+ } from '@equinor/fusion-framework-module-ag-grid/enterprise';
  
  export const configure: AppModuleInitiator = (configurator, { env }) => {
+    enableAgGrid(configurator, (builder) => {
+        builder.addModules([
+            ClientSideRowModelModule,
+            ClipboardModule,
+            ColumnsToolPanelModule,
+            ExcelExportModule,
+            FiltersToolPanelModule,
+            MenuModule,
+        ]);
+    });
  };