Editing
The grid supports editing of data in the grid. You can enable editing by adding the EditBehavior
to the behaviors
prop of the GridOptions
interface. Below is the list of props that can be used to configure the EditBehavior
.
export interface EditBehaviorOptions {
editStartMode?: EditStartMode;
keyStrokeValid?: (
event: KeyboardEvent,
columnOptions?: ColumnOptions
) => boolean;
editableFunction?: (cellInfo: CellInfo) => boolean;
}
Edit Start Mode
The editStartMode
prop can be used to configure how editing starts. The editStartMode
prop can be set to one of the following values:
export enum EditStartMode {
Click = "Click",
DoubleClick = "DoubleClick",
Excel = "Excel",
}
Click
When the editStartMode
prop is set to Click
, editing starts when you click on a cell.
DoubleClick
When the editStartMode
prop is set to DoubleClick
, editing starts when you double click on a cell.
Excel
When the editStartMode
prop is set to Excel
, editing starts when you click on a cell. The difference between Click
and Excel
is that when you click on a cell, the cell is selected. You can begin typing to edit the cell. Similar to Excel, when you start typing, the text you type replaces the existing text in the cell. Hitting the escape key cancels the edit.
You can use the arrow keys to navigate to the next cell. You can also use the tab key to navigate to the next cell. You can use the shift + tab keys to navigate to the previous cell. You can also use the enter key to navigate to the cell below. You can use the shift + enter keys to navigate to the cell above.
Key Stroke Valid
The keyStrokeValid
prop can be used to configure which keys are valid for editing. The keyStrokeValid
prop is a function that takes in a KeyboardEvent
and returns a boolean. The keyStrokeValid
prop is called when a key is pressed. If the keyStrokeValid
prop returns true, the key is valid for editing. If the keyStrokeValid
prop returns false, the key is not valid for editing.
Editable Function
The editableFunction
prop can be used to configure which cells are editable. The editableFunction
prop is a function that takes in a CellInfo
and returns a boolean. The editableFunction
prop is called when a cell is clicked. If the editableFunction
prop returns true, the cell is editable. If the editableFunction
prop returns false, the cell is not editable.
Editable Columns
You can configure which columns are editable by setting the editOptions
prop on the ColumnOptions
interface. The editOptions
prop is an object that can have the following properties:
export interface EditOptions {
editorRenderer?: (props: RendererProps) => unknown;
editStartMode?: EditStartMode;
keyStrokeValid?: (
event: KeyboardEvent,
columnOptions?: ColumnOptions
) => boolean;
validateValue?: (value: EditInfo, columnOptions: ColumnOptions) => EditInfo;
editableFunction?: (cellInfo: CellInfo) => boolean;
enableEdit?: boolean;
}
Editor Renderer
The editorRenderer
prop can be used to configure the editor that is used to edit the cell. The editorRenderer
prop is a function that takes in a RendererProps
and returns a React component. The editorRenderer
prop is called when a cell is clicked. The editorRenderer
prop is passed the RendererProps
interface. Here is a sample editor:
export const SelectEditor: FunctionComponent<RendererProps> = ({ node }) => {
const api = getApi(node);
const selectRef = useRef<HTMLSelectElement>(null);
const { rowIdentifier, columnIdentifier } = getRowColFromNode(node);
const selectVal =
api.hasChange(rowIdentifier, columnIdentifier)?.newValue ??
resolveExpression(
node.rowPosition?.data,
node.columnPosition?.column!.dataField!
);
const allValues = getDistinctValues(
node.gridOptions,
node.columnPosition?.column!
);
const handleChange = (newVal: unknown) => {
api.addChange(node.rowPosition!, node.columnPosition!, newVal);
};
return createEditor(
createSelectField(node.gridOptions, {
ref: selectRef,
options: allValues,
onChange: handleChange,
value: selectVal as string | number,
}),
selectRef,
rowIdentifier
);
};
Edit Start Mode
This is the same as the editStartMode
prop on the EditBehaviorOptions
interface.
Key Stroke Valid
This is the same as the keyStrokeValid
prop on the EditBehaviorOptions
interface.
Validate Value
The validateValue
prop can be used to validate the value that is entered into the cell. The validateValue
prop is a function that takes in an EditInfo
and returns an EditInfo
. The validateValue
prop is called when a key is pressed. The validateValue
prop is passed the EditInfo
interface. Here is a sample validateValue
function:
export const validateValue: (value: EditInfo, columnOptions: ColumnOptions) => {
if (parseInt((value.newValue?.toString() || "").replace(/,/g, "")) < 50000) {
value.validationMessage = "Salary should be greater than 50000";
} else if (parseInt((value.newValue?.toString() || "").replace(/,/g, "")) > 100000) {
value.validationMessage = "Salary should be less than 100000";
} else {
value.validationMessage = "";
}
value.valid = value.validationMessage === "";
return value;
}
Editable Function
This is the same as the editableFunction
prop on the EditBehaviorOptions
interface.
Enable Edit
The enableEdit
prop can be used to enable or disable editing for a column. The enableEdit
prop is a boolean. If the enableEdit
prop is true, editing is enabled for the column. If the enableEdit
prop is false, editing is disabled for the column.
Example
In the example above, the isActive
column is editable. The isActive
column is editable because the enableEdit
prop is set to true. The isActive
column is editable because the editStartMode
prop is set to EditStartMode.Click
. The isActive
column is editable because the editorRenderer
prop is set to CheckBoxEditor
. When the isActive
column is clicked, the CheckBoxEditor
is used to edit the cell. Once the user clicks the CheckBoxEditor
, the updated value is added to the grid's changes collection and can be accessed via the getChanges
method of the GridApi
. Let's take a look at how to access the changes collection.
Accessing the Changes Collection
The getChanges
method of the GridApi
can be used to access the changes collection. The getChanges
method returns an array of ChangeInfo
objects. The ChangeInfo
interface is defined as follows:
You will also notice, that once the user makes some changes, an icon is displayed in the grid header. This icon is used to indicate that the grid has changes. When you click the icon, the changes are displayed in a modal. The modal is displayed using the EditMenu in the Toolbar interface. You can always customize the EditMenu to display the changes in a different way. There are examples of how to customize the Toolbar section of the documentation.
Now that we have looked at a basic CheckBoxEditor, let's take a look at the other editors that are available.
Editors
CheckBoxEditor
The CheckBoxEditor
is used to edit boolean values. The CheckBoxEditor
is a simple checkbox that is used to edit boolean values. The CheckBoxEditor
is used by default when the boolean
column type is used. The CheckBoxEditor
is also used when the editorRenderer
prop is set to CheckBoxEditor
on the EditBehaviorOptions
interface. The code for the CheckBoxEditor
is available here
DateEditor
The DateEditor
is used to edit date values. The DateEditor
is also used when the editorRenderer
prop is set to DateEditor
on the EditBehaviorOptions
interface. The code for the DateEditor
is available here
SelectEditor
The SelectEditor
is used to edit string values. The code for the SelectEditor
is available here
When using the SelectEditor
, please ensure you add the filterBehavior to the grid. The filterBehavior is required for the SelectEditor
to figure out the list of values to display in the dropdown.
TextInputEditor
The TextInputEditor
is used to edit string values. The TextInputEditor
is also used when the editorRenderer
prop is set to TextInputEditor
on the EditBehaviorOptions
interface. The code for the TextInputEditor
is available here
The CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
are all wired up to use the grid's Adapter mechanism. This means, if you use the Material Adapter, the CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
will use the Material UI components automatically. If you don't, the CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
will use the default HTML elements.
Let's use these editors to edit the grid.
Using the Editors
Let's use the CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
to edit the grid.
There are a few things to note here.
The
annualSalary
column is using theTextInputEditor
and has a custom validation function. The validation function ensures that the salary is between 50000 and 100000. If the salary is not between 50000 and 100000, the cell becomes red and the validation message is displayed when the user clicks on the toolbar edit icon.The
hireDate
column is using theDateEditor
. TheDateEditor
is a simple date picker that is used to edit date values. TheDateEditor
uses the HTML 5 input type ofdate
but is wired up to use the grid's Adapter mechanism. This means, if you use the Material Adapter, theDateEditor
will use the Material UI date picker automatically.The
department
column is using theSelectEditor
. TheSelectEditor
is a simple dropdown that is used to edit string. Notice that theSelectEditor
is using thefilterBehavior
to figure out the list of values to display in the dropdown. Similar to theDateEditor
TheSelectEditor
is wired up to use the grid's Adapter mechanism. This means, if you use the Material Adapter, theSelectEditor
will use the Material UI dropdown automatically.The
lastName
column is using the defaultTextInputEditor
, but the Edit Start Mode is set toExcel
. This means, the user can edit the cell by double clicking on the cell, or you can just start typing in the cell.The
firstName
column is using the defaultTextInputEditor
.
Material UI
Let's use the Material UI Adapter to use the Material UI components for the CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
.
As you can see, the CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
are using the Material UI components, with a single line of code!
Custom Editors
Now that we have seen how to use the built-in editors, let's see how to create a custom editor.
Let's create a custom editor that allows the user to edit the isActive
column using a dropdown.
There you have it! You have created a custom editor that allows the user to edit the isActive
column using a dropdown.
Conditional Editing
You can also use the editableFunction
function to enable or disable editing for a particular row and column. This property is available
both on the EditOptions
interface of the Column
and on the EditBehaviorOptions
interface of the EditBehavior
.
You can use the one on the Column
to enable or disable editing for a particular column, and you can use the one on the EditBehavior
to enable or disable editing for the entire grid.
In the above example, we have enabled editing for the isActive
column only for the even rows, and we have enabled editing for the lastName
column only for the odd rows.
We have also enabled editing for the entire grid, except for the row with the employeeId
of 1. This is because we have used the editableFunction
property on the EditBehavior
to enable or disable editing for the entire grid. This property overrides the editableFunction
property on the Column
.
Conclusion
In this tutorial, we have seen how to use the built-in editors and how to create a custom editor. We have also seen how to use the Material UI Adapter to use the Material UI components for the CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
. We have also seen how to use the validateValue
function to validate the value entered by the user. We have also seen how to use the getChanges
function to get the changes made by the user. We have also seen how to use the EditStartMode
enum to specify the edit start mode.
We created a custom editor that allows the user to edit the isActive
column using a dropdown. We have also seen how to use the addChange
function to add a change to the grid, and we saw how using the material adapter, we can use the Material UI components for the CheckBoxEditor
, DateEditor
, SelectEditor
, and TextInputEditor
.