Cell Renderer's and Cell Editors, the former for showing the data, the latter for editing the data. If your application is for showing data only, such as a reporting application, then you will not need to use cell editors. If you are editing your data like a spreadsheet, then cell editors are going to be your best friend as you build your application using ag-Grid.
Use Cell Editors to provide editing functionality to your data through the grid that ties in with the grid navigation, refresh and general data management.
You configure cell editors as part of the column definition and can be one of the following:
cellEditoris looked up from the provided cell editors. Use this if you want to use a built in editor.
The simplest way to enable editing is by providing
colDef.editable=true by doing so all the cells
in the column will be editable.
It is possible to have only a few cells in a column editable, to do so, instead of
you can specify a callback that will get called for each cell displayed for that column. If you return true the
cell will be editable. The params for the callback are:
|node||The RowNode of the row being rendered.|
|column||The column been rendered (in ag-Grid, each colDef is wrapped by a Column).|
|colDef||The colDef been rendered.|
|context||The context as set on the gridOptions.|
|api||A reference to the grid api.|
|columnApi||A reference to the column api.|
To get simple string editing, you do not need to provide an editor. The grid by default allows simple string editing on cells. The default editor is used if you do not provide a cell editor.
If you have
colDef.editable=true set for a column then editing will start upon any of the following:
Editing can start in the following ways:
params.charPresswill contain the character that started the edit. The default editor places this character into the edit field so that the user experience is they are typing into the cell.
singleClickEditthat will allow single click to start editing instead of double click. Another property
suppressClickEditwill prevent both single click and double click from starting the edit - use this if you want to have your own way of starting editing only, such as clicking a button in your custom cell renderer.
startEditingCell()on the grid API
The grid will stop editing when any of the following happen:
stopEditing(from the params above) gets called by the editor. This is how your cell editor informs the grid to stop editing.
stopEditing()on the grid API.
An editor can be in a popup or in cell.
In Cell editing means the contents of the cell will be cleared and the editor will appear inside the cell. The editor will be constrained to the boundaries of the cell, if it is larger that the provided area it will be clipped. When editing is finished, the editor will be removed and the renderer will be placed back inside the cell again.
If you want your editor to appear in a popup (such as a dropdown list), then you can have it appear in a popup. The popup will behave like a menu in that any mouse interaction outside of the popup will close the popup. The popup will appear over the cell, however it will not change the contents of the cell. Behind the popup the cell will remain intact until after editing is finished which will result in the cell being refreshed.
From a lifecycle and behaviour point of view, 'in cell' and 'popup' have no impact on the editor. So you can create a cell editor and change this property and observe how your editor behaves in each way.
To have an editor appear in a popup, have the
isPopup() method return true. If you want editing
to be done within a cell, either return false or don't provide this method at all.
While editing, if you hit tab, the editing will stop on the current cell and start on the next cell. If you hold down shift+tab, the same will happen except the previous cell will start editing rather than the next. This is in line with editing data in Excel.
The next and previous cells can also be navigated using the API functions
api.tabToPreviousCell(). Both of these methods will return true if the navigation was
successful, otherwise false.
The grid, out of the box, comes with the following editors:
selectto behave odd when in the grid. This is because the browser doesn't have a great API for opening and closing the select's popup. We advise you don't use it unless you have to - that is we advise against
agPopupSelectCellEditoras they give poor user experience, especially if using keyboard navigation. If using ag-Grid Enterprise, then you should use the provided
The default text cell editor takes no parameters. The select cell editor takes a list of values from which the user can select. The example below shows configuring the select cell editor.
If you have many instances of a grid, you must register the cell editors with each one.
Value setter and value parsers are the inverse of a value getters and formatters. If you want to parse the data, or set the value into your data in ways other than just using the field, see the sections Value setter and value parsers.
After a cell has been changed with default editing (ie not your own custom cell renderer),
cellValueChanged event is fired. You can listen for this event in the normal
way, or additionally you can add a
onCellValueChanged() callback to the colDef.
This is used if your application needs to do something after a value has been changed.
cellValueChanged event contains the same parameters as
newValueHandler with one difference,
newValue. If 'field' is in the column definition, the
newValue contains the value
in the data after the edit. So for example, if the
onCellValueChanged converts the provided
string value into a number, then
newValueHandler will have the string, and
onCellValueChanged will have the number.
There are two api methods for editing,
Starts editing the provided cell. If another cell is editing, the editing will be stopped in that other cell. Parameters are as follows:
If the grid is editing this will stop editing.
Pass true to cancel editing, i.e. revert any changes.
The following events are fired as editing starts and stops:
The example below illustrates different parts of the editing API. Each button starts editing the 'Last Name' column of the first row with the following differences:
The example below illustrates:
Full row editing is for when you want all cells in the row to become editable at the same time. This gives the impression to the user that the record the row represents is getting edited.
To enable full row editing, set the grid option
editType = 'fullRow'.
If using custom cell editors, the cell editors will work in the exact same way with the following additions:
focusIn()method, it will get called when the user tabs into the cell. This should be used to put the focus on the particular item to be focused, eg the
textfieldwithin your cell editor.
focusOut()method, it will get called when the user tabs out of the cell. No intended use for this, is just there to compliment the
focusIn()method, maybe you will have a reason to use it.
cellValueChangedevent gets called for each column and
rowValueChangedgets called once for the row.
Full row editing is not compatible with popup editors. This is because a) the grid would look confusing to pop up an editor for each cell in the row at the same time and b) the complexity of navigation and popup is almost impossible to model - thus the grid and your application code would be to messy and very error prone. If you are using full row edit, then you are blocked from using popup editors.
This does not mean that you cannot show a popup from your 'in cell' editor - you are free to do that - however the responsibility of showing and hiding the popup belongs with your editor. You may want to use the grids focus events to hide the popups when the user tabs or clicks out of the cell.
The example below shows full row editing. In addition to standard full row editing, the following should also be noted:
focusOut()for this editor are logged to the console.
rowValueChangedevents are logged to console.
ag-row-editingchanges the background color to highlight the editing row.
By default, the grid does not let you edit group rows. This is to cater for the scenario where groups are aggregations of the children (ie a group rows values could be the sum of the children, so editing the group doesn't make sense).
In other scenarios, editing groups does make sense. For example if implementing a file explorer,
editing a folder name or owner does make sense in isolation to the contained files. Thus to cater
for this, you can enable editing of groups with the property
The example below shows using
enableGroupEdit=true along with tree data to allow editing of group data.
The default is for the grid to enter editing when you double click on a cell.
To change the default so that a single click starts editing, set the property
This is useful when you want a cell to enter edit mode as soon as you click on it, similar to the experience
you get when inside Excel.
To change the default so that neither single or double click starts editing, set the property
suppressClickEdit=true. This is useful when you want to start the editing in another way,
such as including a button in your cell renderer.
The grid below has singleClickEdit=true so that editing will start on a cell when you single click on it.
The grid below has suppressClickEdit=true so that clicking doesn't started editing. The grid configures a cellRenderer with a button to start editing.
By default, the grid will not stop editing the currently editing cell when the grid loses focus. This can be bad if, for example, you have a save button, and you need the grid to stop editing before you execute your save function (eg you want to make sure the edit is saved into the grids state).
If you want the grid to stop editing when focus leaves, set the grid property
By default, the grid not stop editing if you focus outside. The default is good for custom popup cell editors as these can have the focus leave the grid (eg if using a popup calendar widget). This would be bad as the grid would stop editing as soon as your external popup appeared.
The example below shows the editing with
Notice the following:
While editing, the grid will listen to navigation events coming from the keyboard, this includes navigate to next cell,
next row... If you want to avoid this events from being consumed by the grid you can do so by configuring
The following example shows a simple example where each cell contains a number and the arrows are used to manipulate its value. Note how the arrows are used to increase or decrease the value of the cell while editing and they are not used for navigation