sc-grid

1 Purpose

sc-grid places a data grid on a form, allowing users to view, search, edit, and manage tabular data from documents.

The grid provides features such as pagination, sorting, filtering, inline editing, CSV export, and child document display. It uses AG Grid as the underlying grid library and integrates with Formbird's document management system.

The sc-grid definition provides fields for setting the properties of a grid field and is fully described below.

2 Definition

sc-grid is defined by a set of name/value pair fields consisting of:

• Required system fields
• Required customizable fields
• Optional customizable fields

Note:

1. Default values for fields described in the tables below are shown in bold text.

2.1 Required System Fields

2.2 Required Customizable Fields

2.3 Optional Customizable Fields

3 Typical Definition

Below is a typical sc-grid definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-grid",
    "label": "Test sc-grid",
    "name": "testScGrid",
    "filter": "{'query':{'bool':{'must':[{'match':{'systemHeader.templateId':{'query':'template-id'}}}]}}}",
    "gridColumns": [
        {
            "field": "name",
            "editable": true,
            "cellDataType": "text"
        },
        {
            "field": "description",
            "editable": true,
            "cellDataType": "text"
        }
    ],
    "rowsPerPage": 10,
    "lengthMenu": [5, 10, 50, 100]
}

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

    "displayChildDoc": false,
    "enabled": false,
    "fullWidth": true,
    "mandatory": true,
    "visible": false

4 Examples

Example 1

A sc-grid definition with basic columns for displaying and editing document data.

{
    "componentName": "sc-grid",
    "label": "Document Grid",
    "name": "documentGrid",
    "filter": "{'query':{'bool':{'must':[{'match':{'systemHeader.templateId':{'query':'template-id'}}}]}}}",
    "fullWidth": true,
    "gridColumns": [
        {
            "field": "name",
            "editable": true,
            "cellDataType": "text",
            "headerName": "Document Name"
        },
        {
            "field": "description",
            "editable": true,
            "cellDataType": "text",
            "headerName": "Description"
        },
        {
            "field": "systemHeader.currentVersion",
            "editable": true,
            "cellDataType": "boolean",
            "headerName": "Current Version?"
        }
    ],
    "rowsPerPage": 10,
    "lengthMenu": [5, 10, 50, 100]
}

Resulting field on the form:

Example 2

A sc-grid definition with advanced features including filtering, custom editors, and child document display.

{
    "componentName": "sc-grid",
    "name": "advancedGrid",
    "label": "Advanced Data Grid",
    "fullWidth": true,
    "filter": "{'query':{'bool':{'must':[{'match':{'systemHeader.templateId':{'query':'ad147008-7a01-461e-ae9d-190c0ed93435'}}}]}}}",
    "gridColumns": [
        {
            "field": "documentId",
            "editable": true,
            "cellDataType": "text",
            "headerName": "ID"
        },
        {
            "field": "name",
            "editable": true,
            "cellDataType": "text",
            "cellEditor": "agLargeTextCellEditor",
            "cellEditorPopup": true,
            "cellEditorParams": {
                "maxLength": 100
            }
        },
        {
            "field": "assetType",
            "editable": true,
            "cellEditor": "agSelectCellEditor",
            "cellEditorParams": {
                "values": [
                    "Valve - Gate/Sluice",
                    "Valve - Butterfly",
                    "Valve - Air Release / Entry",
                    "Valve - NRV / Swing Check"
                ]
            }
        },
        {
            "field": "staticValues",
            "editable": true,
            "scFormatterKey": "multiSelect",
            "scEditorKey": "multiSelectEditor",
            "headerName": "Static Values"
        },
        {
            "headerName": "Actions",
            "width": 100,
            "scCellRendererKey": "actionRenderer"
        }
    ],
    "rowsPerPage": 5,
    "lengthMenu": [5, 10, 15, 20, 200],
    "displayChildDoc": true
}

Resulting field on the form:

Example 3

A sc-grid definition for read-only data display with search and export capabilities.

{
    "componentName": "sc-grid",
    "name": "readOnlyGrid",
    "label": "Report Data",
    "fullWidth": true,
    "gridColumns": [
        {
            "field": "name",
            "editable": false,
            "cellDataType": "text",
            "headerName": "Name"
        },
        {
            "field": "description",
            "editable": false,
            "cellDataType": "text",
            "headerName": "Description"
        },
        {
            "field": "systemHeader.createdDate",
            "editable": false,
            "cellDataType": "date",
            "headerName": "Created Date"
        }
    ],
    "rowsPerPage": 20,
    "lengthMenu": [10, 20, 50, 100]
}

Grid Features:

• Search: Built-in search functionality across all columns
• Pagination: Configurable page sizes and navigation
• Sorting: Click column headers to sort data
• Export: CSV export functionality via the "Download CSV export file" button
• Inline Editing: When enabled, allows direct cell editing
• Child Document Display: Shows selected document's form below the grid
• Custom Editors: Support for various cell editors (text, select, multi-select, etc.)
• Custom Renderers: Support for custom cell renderers (e.g., action buttons)

5 Column Configuration

The gridColumns array defines the columns displayed in the grid. Each column object supports the following properties:

5.1 Basic Column Properties

5.2 Cell Editors

Use the following fields on a column to enable and configure inline editing:

• editable: Set to true to allow editing for the column.
• cellEditor: Name of the editor to use (see list below).
• cellEditorPopup: Set to true to render the editor in a popup.
• cellEditorParams: Object with editor-specific configuration.

Supported editors (based on AG Grid provided editors — see Provided Cell Editors in the AG Grid docs: https://www.ag-grid.com/javascript-data-grid/provided-cell-editors/):

Notes:

• The boolean checkbox editor can also be driven via cellDataType: "boolean" with editable: true.
• Some AG Grid editors (e.g. Rich Select) require Enterprise; sc-grid uses community editors by default. Prefer agSelectCellEditor unless Enterprise is available.
• You can alternatively specify Formbird editor keys using scEditorKey; these are mapped to concrete editors via an internal factory.

Editor examples:

Text (single-line):

{
  "field": "title",
  "editable": true,
  "cellEditor": "agTextCellEditor",
  "cellEditorParams": { "maxLength": 120 }
}

Large text with popup:

{
  "field": "description",
  "editable": true,
  "cellEditor": "agLargeTextCellEditor",
  "cellEditorPopup": true,
  "cellEditorParams": { "maxLength": 500 }
}

Select with fixed options:

{
  "field": "status",
  "editable": true,
  "cellEditor": "agSelectCellEditor",
  "cellEditorParams": { "values": ["Active", "Inactive", "Pending"] }
}

Number with bounds and precision:

{
  "field": "quantity",
  "editable": true,
  "cellEditor": "agNumberCellEditor",
  "cellEditorParams": { "min": 0, "max": 1000, "precision": 0 }
}

Date with min/max:

{
  "field": "startDate",
  "editable": true,
  "cellEditor": "agDateCellEditor",
  "cellEditorParams": { "min": "2020-01-01", "max": "2030-12-31" }
}

Boolean checkbox:

{
  "field": "isActive",
  "editable": true,
  "cellDataType": "boolean",
  "cellEditor": "agCheckboxCellEditor"
}

Formbird multi-select (custom):

{
  "field": "tags",
  "editable": true,
  "scFormatterKey": "multiSelect",
  "scEditorKey": "multiSelectEditor"
}

5.3 Custom Formatters and Renderers

How the keys are resolved at runtime

During grid initialisation, columns are normalised and any Formbird keys are mapped onto concrete implementations:

```132:137:/workspaces/formbird-sc-components/projects/sc-grid/src/app/grid/grid.component.ts this.gridColumns = this.gridColumns.map(col => ({ ...col, cellEditor: !col.cellEditor && col.scEditorKey ? CellEditorFactory[col.scEditorKey] : col.cellEditor, valueFormatter: !col.valueFormatter && col.scFormatterKey ? GridFormatters[col.scFormatterKey] : col.valueFormatter, cellRenderer: !col.cellRenderer && col.scCellRendererKey ? CellRendererFactory[col.scCellRendererKey] : col.celRenerer }));

- Formatters: keys reference functions in `projects/sc-grid/src/app/grid/utils/grid.formatters.ts`.

```1:6:/workspaces/formbird-sc-components/projects/sc-grid/src/app/grid/utils/grid.formatters.ts
export const GridFormatters = {

  multiSelect(params: any): string {
    const value = params.value;
    return Array.isArray(value) ? value.join(', ') : typeof value === 'string' ? value : '';
  }
}

• Editors: keys reference components in CellEditorFactory defined in projects/sc-grid/src/app/grid/utils/grid.factory.ts.

```1:11:/workspaces/formbird-sc-components/projects/sc-grid/src/app/grid/utils/grid.factory.ts import { ActionCellComponent } from '../comps/action-cell.component'; import { SelectEditorComponent } from '../comps/select-editor.component';

export const CellEditorFactory = { multiSelectEditor: SelectEditorComponent, relatedDocumentEditor: RelatedDocumentEditorComponent };

export const CellRendererFactory = { actionRenderer: ActionCellComponent, relatedDocumentRenderer: RelatedDocumentRendererComponent }

Example using the keys

```json
{
  "field": "staticValues",
  "editable": true,
  "scFormatterKey": "multiSelect",
  "scEditorKey": "multiSelectEditor",
  "headerName": "Static Values"
}

5.4 Example Column Configurations

Text Column with Large Editor:

{
  "field": "description",
  "editable": true,
  "cellEditor": "agLargeTextCellEditor",
  "cellEditorPopup": true,
  "cellEditorParams": {
    "maxLength": 500
  }
}

Select Column with Options:

{
  "field": "status",
  "editable": true,
  "cellEditor": "agSelectCellEditor",
  "cellEditorParams": {
    "values": ["Active", "Inactive", "Pending"]
  }
}

Action Column with Custom Renderer:

{
  "headerName": "Actions",
  "width": 100,
  "scCellRendererKey": "actionRenderer"
}

Related Document Column:

{
  "field": "relatedDocument",
  "editable": true,
  "scEditorKey": "relatedDocumentEditor",
  "scCellRendererKey": "relatedDocumentRenderer",
  "headerName": "Related Document"
}

5.5 Responsive Column Hiding

The grid supports responsive column hiding through the gridOptions.responsiveHiddenColumns property. Columns specified in this array will be automatically hidden when the viewport width is less than 900px.

Example:

{
  "componentName": "sc-grid",
  "name": "responsiveGrid",
  "gridOptions": {
    "responsiveHiddenColumns": ["staticValues", "refType", "metadata"]
  },
  "gridColumns": [
    {
      "field": "name",
      "headerName": "Name"
    },
    {
      "field": "staticValues",
      "headerName": "Static Values"
    },
    {
      "field": "refType",
      "headerName": "Reference Type"
    }
  ]
}

Default behavior: If gridOptions.responsiveHiddenColumns is not specified, the default columns ["staticValues", "refType"] will be hidden on narrow screens.