Novin@Cover-Ag-Grid-Web

novin@cover-ag-grid-web is a ui table library written for RDT system (Rayvar DataTable)

Table of Content

Novin@Cover-Ag-Grid-Web

How to Install

To install @novin/cover-ag-grid-web run command :

npm install @novin/cover-ag-grid-web

Quick Start

import { Schema } from "@novin/cover-ag-grid-web/types";

type Entity = {
  id: string;
  firstName: string;
  lastName: string;
  age: number;
};

const schema: Schema<Entity> = {
  fields: [
    {
      fieldName: "id",
      isKey: true,
    },
    {
      fieldName: "firstName",
      title: "نام",
    },
    {
      fieldName: "lastName",
      title: "نام خانوادگی",
    },
    {
      fieldName: "age",
      title: "سن",
    },
  ],
  filters: [],
  sorts: [],
};

Local Grid :

import { LocalGrid } from "@novin/cover-ag-grid-web";
import "@novin/cover-ag-grid-web/dist/styles.css";

const element = document.getElementById("my-grid");

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows([
    { id: "1", firstName: "سنبله", lastName: "کاشی", age: 23 },
    { id: "2", firstName: "نیلوفر", lastName: "علم", age: 35 },
    { id: "3", firstName: "کامبیز", lastName: "دیرباز", age: "42" },
  ])
  .build();

Remote Grid :

import { RemoteGrid } from "@novin/cover-ag-grid-web";
import {
  RdtRequestModel,
  RdtResponseModel,
  StatusCode,
} from "@novin/cover-ag-grid-web/types";
import "@novin/cover-ag-grid-web/dist/styles.css";

const element = document.getElementById("my-grid");

const grid = await new RemoteGrid<Entity>(element)
  .schema(schema)
  .datasource(
    async (request: RdtRequestModel): Promise<RdtResponseModel<Entity>> => {
      await new Promise((res) => setTimeout(res, 2000)); // wait for 2 seconds
      return {
        rows: [
          { id: "1", firstName: "سنبله", lastName: "کاشی", age: 23 },
          { id: "2", firstName: "نیلوفر", lastName: "علم", age: 35 },
          { id: "3", firstName: "کامبیز", lastName: "دیرباز", age: "42" },
        ],
        isLastPage: false,
        status: StatusCode.SUCCESS,
      };
    }
  );

Filtering

To enable filtering for a specific column, the filtering information should be included in Schema.Filters.

type Schema<TData = any> = {
  fields: Array<Field<TData>>;
  filters: Array<Filter<TData>>;
  sorts: Array<Sort<TData>>;
};

type Filter<TData> = {
  fieldName: FieldProperty<TData>; // the field that has a column and user can work with its filter.
  filterName: FieldProperty<TData>; // the field that filter applies on.
  type: FilterType;
};

type FieldProperty<TData> = keyof TData;

type FilterType =
  | "EqualBy"
  | "NotEqualBy"
  | "Contains"
  | "NotContains"
  | "Unknown"
  | "LessThan"
  | "LessThanOrEqual"
  | "GreaterThan"
  | "GreaterThanOrEqual"
  | "Or"
  | "And";

Also column data type should be specified. (Schema.Field.Type.Name)

Note : For local grids, filtering is applied internally by Ag-Grid, but for remote grids, every change in filter instances, calls datasource with updated RDT request.

Example: Defining Filterable Column In Schema

const schema: Schema<Entity> = {
  fields: [
    {
      fieldName: "id",
      isKey: true,
    },
    {
      fieldName: "firstName",
      title: "نام",
      type: {
        name: "String",
      },
    },
    {
      fieldName: "lastName",
      title: "نام خانوادگی",
    },
    {
      fieldName: "age",
      title: "سن",
      type: {
        name: "Int",
      },
    },
  ],
  filters: [
    {
      fieldName: "firstName",
      filterName: "firstName",
      type: "EqualBy",
    },
    {
      fieldName: "age",
      filterName: "age",
      type: "GreaterThan",
    },
  ],
  sorts: [],
};

Example: LocalGrid Filtering

firstName column is filterable, it filters rows with equal value to filter value.
age column is filterable, it filters rows with greater value than filter value.

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid(element)
  .schema(schema)
  .rows(...)

Example: RemoteGrid Filtering

firstName and age columns are filterable. by changing filters value, datasource gets called with new request.filters value.

import { RemoteGrid } from "@novin/cover-ag-grid-web";
import "@novin/cover-ag-grid-web/dist/styles.css";

const element = document.getElementById("my-grid");

const grid = await new RemoteGrid(element)
  .schema(schema)
  .datasource(
    async (request: RdtRequestModel): Promise<RdtResponseModel<Entity>> => {
      request.filters.forEach((filter) => console.log({ filter }));
      // request to external source and return new values...
    }
  );

Sorting

To enable filtering for a specific column, the filtering information should be included in Schema.Sorts.

type Schema<TData = any> = {
  fields: Array<Field<TData>>;
  filters: Array<Filter<TData>>;
  sorts: Array<Sort<TData>>;
};

type Sort<TData> = {
  fieldName: FieldProperty<TData>;
  type: SortType;
  order: OrderType;
};

type FieldProperty<TData> = keyof TData;

type SortType = "All" | "Asc" | "Desc";

enum OrderType {
  Asc,
  Desc,
  All,
}

Note : For local grids, sorting is applied internally by Ag-Grid, but for remote grids, every change in columns sorting, calls datasource with updated RDT request.

Example: Defining Sortable Column In Schema

const schema: Schema<Entity> = {
  fields: [
    {
      fieldName: "id",
      isKey: true,
    },
    {
      fieldName: "firstName",
      title: "نام",
    },
    {
      fieldName: "lastName",
      title: "نام خانوادگی",
    },
    {
      fieldName: "age",
      title: "سن",
    },
  ],
  filters: [],
  sorts: [
    {
      fieldName: "age",
      order: OrderType.Asc, // or simply 0
      type: "All",
    },
  ],
};

Example: LocalGrid Sorting

age column is sortable.

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid(element)
  .schema(schema)
  .rows(...)

Example: RemoteGrid Sorting

age column is sortable. by click on age column, column sorting changes and datasource gets called with new request.orders value.

import { RemoteGrid } from "@novin/cover-ag-grid-web";
import "@novin/cover-ag-grid-web/dist/styles.css";

const element = document.getElementById("my-grid");

const grid = await new RemoteGrid(element)
  .schema(schema)
  .datasource(
    async (request: RdtRequestModel): Promise<RdtResponseModel<Entity>> => {
      request.orders.forEach((order) => console.log({ order }));
      // request to external source and return new values...
    }
  );

Editing

To enable editing for a column, use isEditable property on field definition. Also column data type should be specified so grid can choose which cell editor to use.

Example: Defining Editable Column In Schema

In the below schema :

firstName is editable with default TextEditor
lastName is editable with default TextEditor
age is editable with default NumberEditor

const schema: Schema<Entity> = {
  fields: [
    {
      fieldName: "id",
      isKey: true,
    },
    {
      fieldName: "firstName",
      title: "نام",
      isEditable: true,
      type: {
        name: "String",
      },
    },
    {
      fieldName: "lastName",
      title: "نام خانوادگی",
      isEditable: true,
      type: {
        name: "String",
      },
    },
    {
      fieldName: "age",
      title: "سن",
      isEditable: true,
      type: {
        name: "Int",
      },
    },
  ],
  filters: [],
  sorts: [],
};

Editing can be single-row or multiple-row (also known as bulk-edit) editing. At least one column should be editable to display the edit action button on the grid's actions column. The final data of rows can be validated by using the onEditRows callback. If it returns true, then the grid will update the row values with new values. If it returns false, then the grid will abort the changes. If it does not return either true or false, the grid will assume that the changes are valid and will update the row data.

Single Row Editing

By default, single-row editing is enabled in the grid after it finds at least one editable column in the grid schema. To enable row editing, the grid displays an edit button in the actions column for each row. Once row editing is enabled for a specific row, its every editable column will display its respective editor. After clicking the edit button, two new buttons will appear in the actions column:
- Submit: This button submits the changes made to the row and exits the edit mode.
- Cancel: This button cancels the changes made to the row and exits the edit mode.
Example: Single Row Edit
- firstName, lastName and age column are editable (isEditable=true)
```
import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .build()
```
Multiple Row Editing

Multiple-row editing is only accessible through the grid API. The startBulkEdit method is used to activate bulk-edit mode. After changing the editing mode to bulk-edit, editing rows will not trigger the onEditRows callback until finishBulkEdit method is called.

While editing rows in bulk-edit mode, an undo button will appear in every edited row's actions column, which aborts changes and resets the row's data to its initial value. The finishBulkEdit method is used to deactivate bulk-edit mode and call the onEditRows callback with changed values.

Row Validation

You can prevent user from entering invalid values for columns while editing rows. row validation is possible in two ways:

Validation Rules

Validation rules can be defined via the validation method. You can define rules for each individual field and provide a validation function that gets called every time the field is changed. If the validation function returns a string, it means that the changed value is not valid, and the grid will display a tooltip error with the returned value as its error message. This allows users to see exactly what is wrong with their input and how to correct it.

Example: Validation Rules

firstName, lastName and age column are editable (isEditable=true)

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .validation([
        {
          field: "age",
          validate(data) {
            if (data.age >= 20) return "age can not be greater than 20";
          },
        },
        {
          field: "firstName",
          validate(data) {
            if (data.firstName.startsWith("John"))
              return "firstName cannot start with 'John'";
            if (data.firstName.startsWith("Jane"))
              return "firstName cannot start with 'Jane'";
          },
        },
    ])
  .fullRowEdit()
  .build()

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .validation([
      {
        validate(data, field) {
          switch (field) {
            case "firstName":
              if (data.firstName.startsWith("John"))
                return "firstName cannot start with John'";
              if (data.firstName.startsWith("Jane"))
                return "firstName cannot start with 'Jane'";
              break;
            case "age":
              if (data.age >= 20) return "age can not be greater than 20";
              break;
          }
        },
      },
    ])
  .fullRowEdit()
  .build()

onEditRows Callback

grid calls onEditRows callback after finish editing and before submitting new data. If onEditRows returns true, grid apply changes and if it returns false, grid discard changes. If onEditRows does not return either true or false, grid apply changes.

Example: onEditRows Callback

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
 .schema(schema)
 .rows(...)
 .onEditRows(async (rows) => {
   console.log("new changes", rows)
   return true // return false (or nothing/void) to discard changes
 })

Data Types

Six data types are supported by grid. Which means:

The grid has default cell renderer for each type.
The grid has default cell editor for each type.
The grid has default filter for each type.
The grid has default sorting mechanism for each type.

Note : If you want to use the default grid components for a column, you need to specify the column's type using the Schema.Field.Type.Name property. This allows the grid to determine which renderers, editors, and filters to use.

Int

The Int type represents numeric value
String

The String type represents text value
Bit

The Bit type represents binary value. grid displays a checkbox as cell renderer and a two-option dropdown for filtering (with values true/false)
Date

The Date type represents a date value. The grid tries to format the given value using the Schema.Field.Properties.Format. If no format is provided, the grid uses its default format to parse and render the value.
- default date format : YYYY/MM/DD
Time

The Time type represents a time value. The grid tries to format the given value using the Schema.Field.Properties.Format. If no format is provided, the grid uses its default format to parse and render the value.
- default time format : HHHH:mm:ss
List

The List type format represents a specific set of values that are available for that column. It's like a value source for a column. grid displays dropdown while editing List columns. list source must be defined through Schema.Field.Type.Source property. It can be a string (which represents an external source endpoint) or it can be an array of values (TAutoCompleteItem<TData>[])

Note : If column source is an endpoint string, then columnSource function should be provided to grid, in this way grid can call columnSource with given endpoint to fetch items.

Object
-incomplete-

All Build Options

Option Name	Description
build	builds the grid with given options and return an instance
contextMenu	define context menu items
suppressContextMenu	disable context menu
cellRenderers	define custom cell renderer for columns
cellEditors	define custom cell editor for columns
validation	define validation rules for row editing
onCellClick	cell is clicked
onCellDoubleClick	cell is double clicked
onRowClick	row is clicked
onRowDoubleClick	row is double clicked
onEditRows	row editing finished. return true to submit changes or false to discard changes.
onDeleteRows	deleting a row. return true to confirm deleting or false to prevent from deleting.
onSchemaChange	grid' schema has changed. The reason can be column resizing, change columns visibility or change columns ordering.
rowClassRules	define rules to apply css classes to row elements.
rowCssRules	define rules to apply css properties to row elements.
cellCssRules	define rules to apply css properties to cell elements.
localize	define custom localization
schema	RDT schema object
fullRowEdit	enable full row editing
defaultSelect	select first row by default
selection	set selection config
pagination	set pagination mode ("infinite-scroll" "pagination")
actionBar	define action bar component
detailPanelComponent	define detail panel component for rows
title	set title for grid
isRowMaster	if returns false, then detail panel component won't show for that specific row.
suppressToolbar	disable toolbar
toolbarActions	define custom toolbar actions
actions	define custom actions for 'actions column'
emptyPinnedRowOptions	empty pinned row options!
columnSource	source function that grid uses to fetch dropdown values for `List` type columns
nativeColumnDefs	AgGrid ColDef definitions for columns
defaultColDefs	AgGrid defaultColDef
settings	It is possible to pass most of the above parameters through `settings` function.

Methods

Method Name	Description
getSchema	returns initial schema object
getCurrentSchema	returns current schema object
getSelectedRows	returns an array of selected rows
updateRows	directly update rows with given data, regardless of validations and onEditRows callback
selectRows	select rows
deselectRows	deselect rows
deleteRows	delete rows. If onDeleteRows returns true, the rows will be removed from the grid. However, if onDeleteRows returns false, then the deletion process will be canceled. If onDeleteRows is not defined, the grid will continue deleting rows without asking for confirmation.
setLoading	enable or disable grid's loading
addOnSelectionChangeListener	subscribe to selection changes.
removeOnSelectionChangeListener	unsubscribe to selection changes.
setPageSize	change grid page size
startEditing	enable editing for a given row
stopEditing	finish editing. onEditRows will get call if it is provided.
displayEmptyPinnedRow	display empty pinned row at the top of grid (above all the rows)
hideEmptyPinnedRow	hide empty pinned row. inserted data will get removed from row.
insertEmptyPinnedRowData	If inserted values are not valid, it does nothing. Otherwise it calls onAdd on emptyPinnedRowOptions (if provided), if onAdd function returns `true`, new data will get inserted in grid, otherwise it will get ignored.
getEmptyPinnedRowData	returns current inserted data in the empty pinned row
refreshToolbar	refresh toolbar component
getElement	returns grid html container element
startBulkUpdate	enable bulk-edit mode
finishBulkUpdate	disable bulk-edit mode. onEditRows will gets called with changes.
restoreRowInitialData	discard changed values while was editing and set row value to it's initial value.
getRowDataKey	returns row unique key.
getCurrentEditingRow	returns current editing row
submitCurrentEditingRow	finish editing current row.
isBulkEditEnabled	returns `true` if grid is in bulk-edit mode, otherwise returns `false`
isRowEdited	developers-only-method
setLatestAction	developers-only-method
isOptionalColumn	developers-only-method

Selection

Grid selection can be single-select or multiple-select.

to enable single-selection, selection mode must be equal to "single"
to enable multi-selection, selection mode must be equal to "multiple"
by default, grid shows checkbox for selection. it can be disabled by setting checkbox property to false.
for multi-selection grids, selectAll property can be set to true to display select all checkbox.

Schema

const schema: Schema<Entity> = {
  fields: [
    {
      fieldName: "id",
      isKey: true,
    },
    {
      fieldName: "firstName",
      title: "نام",
    },
    {
      fieldName: "lastName",
      title: "نام خانوادگی",
    },
    {
      fieldName: "age",
      title: "سن",
    },
  ],
  filters: [],
  sorts: [],
};

Example: Single Select

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .selection({
    selection: "single",
    checkbox: true
  })
  .build()

Example: Multiple Select

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .selection({
    selection: "multiple",
    checkbox: true,
    selectAll: true // optional
  })
  .build()

Example: Keep Track Of Selection List

type OnSelectionChangeArgs<TData> = {
  selectedList: Array<TData>;
};
type OnSelectionChange<TData> = (args: OnSelectionChangeArgs<TData>) => void;

import { LocalGrid } from "@novin/cover-ag-grid-web"
import { OnSelectionChange } from "@novin/cover-ag-grid-web/types"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .selection({
    selection: "multiple",
    checkbox: true,
    selectAll: true // optional
  })
  .build()

const onSelectionChange: OnSelectionChange<Entity> = ({ selectedList }) => {
  console.log("selection changed", selectedList)
}

grid.addOnSelectionChangeListener(onSelectionChange)

Pagination

type GridPaginationSetting = {
  paginationMode: "infiniteScroll" | "pagination";
  pageSize: number;
};

Example: Pagination

import { RemoteGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new RemoteGrid<Entity>(element)
  .schema(schema)
  .datasource(...)
  .pagination({
    paginationMode: "infiniteScroll", // or "pagination"
    pageSize: 20
  })
  .build()

Context Menu

type GetContextMenuItems<TData> = (
  params: GetContextMenuItemsParams<TData>
) => ContextMenuItem[];
type GetContextMenuItemsParams<TData> = {
  gridInstance: LocalGrid<TData> | RemoteGrid<TData>;
  field: FieldProperty<TData>;
  rowData: TData;
};
type ContextMenuItem = string | AgGrid.MenuItemDef;

Example: Context Menu

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .contextMenu((params: GetContextMenuItemsParams<Entity>) => {
    const { gridInstance, rowData, field } = params
    return [
      {
        name: rowData[field],
        action() {
          console.log({ rowData, field })
        }
      },
      {
        name: "Edit Row",
        action() {
          gridInstance.startEditing([rowData.userId])
        }
      }
    ]
  })

Event Listeners

Grid supports variant of event listeners, based on Ag-Grid supported event listeners.

onCellClick
onCellDoubleClick
onRowClick
onRowDoubleClick

type OnCellClick<TData> = (data: TData, field: string | undefined) => void;
type OnRowClick<TData> = (data: TData) => void;

Example: Grid Event Listeners

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .onCellClick(params => {
    console.log("onCellClick", params)
  })
  .onCellDoubleClick(params => {
    console.log("onCellDoubleClick", params)
  })
  .onRowClick(params => {
    console.log("onRowClick", params)
  })
  .onRowDoubleClick(params => {
    console.log("onRowDoubleClick", params)
  })
  .build()

Localization

type LocaleText = {
  submitEditAction?: string;
  cancelEditAction?: string;
  editRowAction?: string;
  restoreOriginRowDataAction?: string;
  deleteRowAction?: string;
  emptyCellPlaceholder?: string;
  requiredFieldError?: string;
  selectAll?: string;
  selectAllSearchResults?: string;
  searchOoo?: string;
  blanks?: string;
  noMatches?: string;
  filterOoo?: string;
  equals?: string;
  notEqual?: string;
  blank?: string;
  notBlank?: string;
  empty?: string;
  lessThan?: string;
  greaterThan?: string;
  lessThanOrEqual?: string;
  greaterThanOrEqual?: string;
  inRange?: string;
  inRangeStart?: string;
  inRangeEnd?: string;
  contains?: string;
  notContains?: string;
  startsWith?: string;
  endsWith?: string;
  dateFormatOoo?: string;
  andCondition?: string;
  orCondition?: string;
  applyFilter?: string;
  resetFilter?: string;
  clearFilter?: string;
  cancelFilter?: string;
  textFilter?: string;
  numberFilter?: string;
  dateFilter?: string;
  setFilter?: string;
  columns?: string;
  filters?: string;
  pivotMode?: string;
  groups?: string;
  rowGroupColumnsEmptyMessage?: string;
  values?: string;
  valueColumnsEmptyMessage?: string;
  pivots?: string;
  pivotColumnsEmptyMessage?: string;
  group?: string;
  rowDragRow?: string;
  rowDragRows?: string;
  loadingOoo?: string;
  noRowsToShow?: string;
  enabled?: string;
  pinColumn?: string;
  pinLeft?: string;
  pinRight?: string;
  noPin?: string;
  valueAggregation?: string;
  autosizeThiscolumn?: string;
  autosizeAllColumns?: string;
  groupBy?: string;
  ungroupBy?: string;
  addToValues?: string;
  removeFromValues?: string;
  addToLabels?: string;
  removeFromLabels?: string;
  resetColumns?: string;
  expandAll?: string;
  collapseAll?: string;
  copy?: string;
  ctrlC?: string;
  copyWithHeaders?: string;
  copyWithGroupHeaders?: string;
  paste?: string;
  ctrlV?: string;
  export?: string;
  csvExport?: string;
  excelExport?: string;
  sum?: string;
  min?: string;
  max?: string;
  none?: string;
  count?: string;
  avg?: string;
  filteredRows?: string;
  selectedRows?: string;
  totalRows?: string;
  totalAndFilteredRows?: string;
  more?: string;
  to?: string;
  of?: string;
  page?: string;
  nextPage?: string;
  lastPage?: string;
  firstPage?: string;
  previousPage?: string;
  pivotColumnGroupTotals?: string;
  pivotChartAndPivotMode?: string;
  pivotChart?: string;
  chartRange?: string;
  columnChart?: string;
  groupedColumn?: string;
  stackedColumn?: string;
  normalizedColumn?: string;
  barChart?: string;
  groupedBar?: string;
  stackedBar?: string;
  normalizedBar?: string;
  pieChart?: string;
  pie?: string;
  doughnut?: string;
  line?: string;
  xyChart?: string;
  scatter?: string;
  bubble?: string;
  areaChart?: string;
  area?: string;
  stackedArea?: string;
  normalizedArea?: string;
  histogramChart?: string;
  histogramFrequency?: string;
  combinationChart?: string;
  columnLineCombo?: string;
  AreaColumnCombo?: string;
  pivotChartTitle?: string;
  rangeChartTitle?: string;
  settings?: string;
  data?: string;
  format?: string;
  categories?: string;
  defaultCategory?: string;
  series?: string;
  xyValues?: string;
  paired?: string;
  axis?: string;
  navigator?: string;
  color?: string;
  thickness?: string;
  xType?: string;
  automatic?: string;
  category?: string;
  number?: string;
  time?: string;
  autoRotate?: string;
  xRotation?: string;
  yRotation?: string;
  ticks?: string;
  width?: string;
  height?: string;
  length?: string;
  padding?: string;
  spacing?: string;
  chart?: string;
  title?: string;
  titlePlaceholder?: string;
  background?: string;
  font?: string;
  top?: string;
  right?: string;
  bottom?: string;
  left?: string;
  labels?: string;
  size?: string;
  minSize?: string;
  maxSize?: string;
  legend?: string;
  position?: string;
  markerSize?: string;
  markerStroke?: string;
  markerPadding?: string;
  itemSpacing?: string;
  itemPaddingX?: string;
  itemPaddingY?: string;
  layoutHorizontalSpacing?: string;
  layoutVerticalSpacing?: string;
  strokeWidth?: string;
  lineDash?: string;
  offset?: string;
  offsets?: string;
  tooltips?: string;
  callout?: string;
  markers?: string;
  shadow?: string;
  blur?: string;
  xOffset?: string;
  yOffset?: string;
  lineWidth?: string;
  normal?: string;
  bold?: string;
  italic?: string;
  boldItalic?: string;
  predefined?: string;
  fillOpacity?: string;
  strokeOpacity?: string;
  histogramBinCount?: string;
  columnGroup?: string;
  barGroup?: string;
  pieGroup?: string;
  lineGroup?: string;
  scatterGroup?: string;
  areaGroup?: string;
  histogramGroup?: string;
  combinationGroup?: string;
  groupedColumnTooltip?: string;
  stackedColumnTooltip?: string;
  normalizedColumnTooltip?: string;
  groupedBarTooltip?: string;
  stackedBarTooltip?: string;
  normalizedBarTooltip?: string;
  pieTooltip?: string;
  doughnutTooltip?: string;
  lineTooltip?: string;
  groupedAreaTooltip?: string;
  stackedAreaTooltip?: string;
  normalizedAreaTooltip?: string;
  scatterTooltip?: string;
  bubbleTooltip?: string;
  histogramTooltip?: string;
  columnLineComboTooltip?: string;
  areaColumnComboTooltip?: string;
  customComboTooltip?: string;
  noDataToChart?: string;
  pivotChartRequiresPivotMode?: string;
  chartSettingsToolbarTooltip?: string;
  chartLinkToolbarTooltip?: string;
  chartUnlinkToolbarTooltip?: string;
  chartDownloadToolbarTooltip?: string;
  seriesChartType?: string;
  seriesType?: string;
  secondaryAxis?: string;
  ariaChecked?: string;
  ariaColumn?: string;
  ariaColumnGroup?: string;
  ariaColumnList?: string;
  ariaColumnSelectAll?: string;
  ariaDateFilterInput?: string;
  ariaDefaultListName?: string;
  ariaFilterColumnsInput?: string;
  ariaFilterFromValue?: string;
  ariaFilterInput?: string;
  ariaFilterList?: string;
  ariaFilterToValue?: string;
  ariaFilterValue?: string;
  ariaFilteringOperator?: string;
  ariaHidden?: string;
  ariaIndeterminate?: string;
  ariaInputEditor?: string;
  ariaMenuColumn?: string;
  ariaRowDeselect?: string;
  ariaRowSelectAll?: string;
  ariaRowToggleSelection?: string;
  ariaRowSelect?: string;
  ariaSearch?: string;
  ariaSortableColumn?: string;
  ariaToggleVisibility?: string;
  ariaUnchecked?: string;
  ariaVisible?: string;
  ariaSearchFilterValues?: string;
  ariaRowGroupDropZonePanelLabel?: string;
  ariaValuesDropZonePanelLabel?: string;
  ariaPivotDropZonePanelLabel?: string;
  ariaDropZoneColumnComponentDescription?: string;
  ariaDropZoneColumnValueItemDescription?: string;
  ariaDropZoneColumnGroupItemDescription?: string;
  ariaDropZoneColumnComponentAggFuncSeperator?: string;
  ariaDropZoneColumnComponentSortAscending?: string;
  ariaDropZoneColumnComponentSortDescending?: string;
  ariaLabelColumnMenu?: string;
  ariaLabelCellEditor?: string;
  ariaLabelDialog?: string;
  ariaLabelSelectField?: string;
  ariaLabelTooltip?: string;
  ariaLabelContextMenu?: string;
  ariaLabelSubMenu?: string;
  ariaLabelAggregationFunction?: string;
  thousandSeparator?: string;
  decimalSeparator?: string;
};

Example: Localization

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(schema)
  .rows(...)
  .localize({
    noRowsToShow: "ردیفی یافت نشد"
  })

Cell Renderers

It is possible to override default render behavior for cell renderers. You can implement custom cell renderer for fields or more generally, types.

type CellRenderer<TData> = {
  field: FieldProperty<TData>;
  renderer: typeof CustomCellRenderer<TData>;
};

abstract class CustomCellRenderer<TData> {
  abstract init(params: AgGrid.ICellRendererParams<TData>): void;
  abstract getGui(): HTMLElement;
  abstract refresh(params: AgGrid.ICellRendererParams<TData>): boolean;
  abstract destroy(): void;
}

Note : Please to figuring out how to implement a custom cell renderer, checkout Ag-Grid official documentation.

Cell Editors

It is possible to override default editor behavior for cell editors. You can implement custom cell editor for fields or more generally, types.

type CellEditor<TData> = {
  fieldOrType:
    | Field<TData>["fieldName"]
    | "string"
    | "number"
    | "boolean"
    | "date"
    | "time"
    | "object"
    | "list";
  editor: any; // AgGrid custom editor component
};

Note : Please to figuring out how to implement a custom cell editor, checkout Ag-Grid official documentation.

Action Bar

Example: Action Bar

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(...)
  .rows(...)
  .selection({
    selection: "single",
    checkbox: false
  })
  .actionBar((gridInstance) => {
    const container = document.createElement("div");

    const addButton = document.createElement("button");
    addButton.innerHTML = "add";
    addButton.onclick = () => gridInstance.displayEmptyPinnedRow();

    const removeButton = document.createElement("button")
    removeButton.innerHTML = "remove"
    removeButton.onclick = () => {
      const selected = gridInstance.getSelectedRows()[0]
      if(selected) gridInstance.deleteRows([selected])
    }

    container.append(addButton, removeButton);

    return container;
  })
  .build();

Detail Panel

it possible to render a html element as detail panel for rows.

Example: Detail Panel

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocUsealGrid<Entity>(element)
  .schema(...)
  .rows(...)
  .detailPanelComponent((data, gridInstance) => {
    const container = document.createElement("div");
    container.innerHTML = `${data.firstName} + ${data.lastName} | ${data.age}`;
    return container;
  })
  .build()

Use isRowMaster callback to conditionally choose which rows have detail panel.

Toolbar

Example: Custom Toolbar Action

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(...)
  .rows(...)
  .toolbarActions((defaults) => [
    ...defaults,
    {
      name: "custom-toolbar-action",
      icon: "print",
      async action(grid) {
        const selectedList = grid.getSelectedRows();
        console.log({ selectedList });
      },
    },
  ])
  .build()

Column Actions

Example: Column Actions

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(...)
  .rows(...)
  .actions((defaults) => [
    ...defaults,
    {
      title: "print",
      action(event) {
        const selectedList = event.grid.getSelectedRows();
        console.log({ selectedList });
      },
    },
  ])
  .build()

Styling

Example: Row Class Rules

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(...)
  .rows(...)
  .rowClassRules({
    "disabled-row": row => row.age >= 50
  })
  .build()

Example: Row Css Rules

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(...)
  .rows(...)
  .rowCssRules([
      {
        rule(data, grid) {
          return data.age >= 50
        },
        styles: {
          color: "gray"
        }
      }
    ])
  .build()

Example: Cell Css Rules

import { LocalGrid } from "@novin/cover-ag-grid-web"
import "@novin/cover-ag-grid-web/dist/styles.css"

const element = document.getElementById("my-grid")

const grid = await new LocalGrid<Entity>(element)
  .schema(...)
  .rows(...)
  .cellCssRules([
    {
      field: "firstName",
      rule(data, field, grid) {
        return data.firstName == "John"
      },
      styles: {
        fontWeight: "bold"
      }
    }
  ])
  .build()

Type of Grids

RemoteGrid

Remote grids have external datasource for collecting rows to display in grid. a datasource function need to be provided for RemoteGrid class to fetch rows.

Each action that requires loading new rows, calls datasource function. Like filtering, sorting, changing pagination...

LocalGrid

Local grids have internal values (client-side) for rows. You can provide initial values by rows(...) function to grid or simply call setRows(...) after building grid instance.

In local grids, all data handling happens in client-side. Like filtering, sorting and CRUD operations.

Global Config

setCellCssRules
setCellEditors
setCellValidations
setColumnActions
setLocaleText
setSettings
setToolbarActions