-
Notifications
You must be signed in to change notification settings - Fork 161
Grid Editing
- Revision history
- Overview
- User Stories - Developer - End user
- Common behaviors
- Cell editing
- Row editing
- Event arguments and sequence
- Event cancelation
Version | User | Date | Notes |
---|---|---|---|
0.1 | Radoslav Karaivanov | May 15, 2018 | Initial Draft |
0.2 | Zdravko Kolev | May 25, 2018 | TBD Update |
0.3 | Zdravko Kolev | May 30, 2018 | Finishing up the initial spec reqs |
0.4 | Stefan Ivanov | Oct 1, 2018 | Adding row edit scenarios |
0.5 | Nikolay Alipiev | Oct 9, 2018 | Adding row edit info |
0.6 | Milko Venkov | Oct 10, 2018 | Update Transaction's API |
0.7 | Milko Venkov | Oct 10, 2018 | Add row edit related testing scenarios |
0.8 | Nikolay Alipiev | Oct 16, 2018 | Interaction with other features |
1.0 | Zdravko Kolev | Dec 10, 2018 | Updating the cell editing section |
1.1 | Zdravko Kolev | Mar 13, 2019 | Updating Exit edit mode section |
1.2 | Nadia Robakova | Mar 23, 2019 | Updating Exit edit mode section |
1.3 | Damyan Petev | Aug 28, 2020 | Events and sequence updates |
1.4 | Alex Kamenov | Sep 18, 2020 | Tests: Events and sequence updates |
1.5 | Zdravko Kolev | Feb 22, 2021 | Add exit edit mode capabilities |
The grid provides default cell templates for editable columns which are based on the data type of the column.
It also provides rowEditable
property, which allows editing several cells from a row, using a editing dialog, and submitting the changes to the data source at once.
The grid can use Transaction
provider, which accumulates pending changes, that are not directly applied to the data source, and later to submit them at once.
This specification defines the default and expected behaviors when a cell is in edit mode with the default editing templates provided by the grid and/or the ones supplied by the user.
- As a developer, I want to be able to provide my own custom template for editing.
- This feature is already supported.
- As a developer, I want to be able to override the default behavior for committing/discarding changes:
- The current version won't provide the ability to set different keys for entering/exiting edit mode.
- As a developer, I want to be able to override the behavior of keyboard navigation/interaction with the cell editing:
- The current version won't provide the ability to override the behavior of keyboard navigation/interaction with the cell editing.
- As an end user, I want to be able to enter in edit mode when an editable cell is focused.
- Through mouse interaction: double clicking on the cell transitions it into edit mode.
-
Keyboard interaction: Pressing
Enter
orF2
transitions it into edit mode. - Single click: will enter edit mode only if the previous selected cell was in edit mode and currently selected cell is editable. If the previous selected cell wasn't in edit mode, single click will select the cell (without entering edit mode).
- As an end user, I want the default input editors to be focused when the cell transitions into edit mode.
- String data type: Already supported.
- Number data type: Already supported.
-
Date data type: Currently the
igx-datepicker's
input cannot be focused and does not react on keyboard interactions. - Add ability to open the datepicker dialog with the
Space
key. -
Boolean data type: The
igx-checkbox
supports focus but does not expose an API to trigger it programatically.
- As an end user, I want to commit the changes to the cell value when I:
- Press the
Enter
key - Already supported. - Press the
F2
key - Already supported, enter/exit edit mode, depending on the cell state. - Press the
Tab
key - Currently not supported but a common behavior in most data grids.Tab
press should commit and moves to the next cell, and put it in edit mode if the cell is editable.- Note: This can potentially clash with editing templates provided by the user where there are more than one focusable elements in the template. Should we just keep it for our default templates, expose some way of overriding the "default" behavior or something else entirely.
- Commit the new value on blur
- [TBD] Should the changes be committed on horizontal/vertical scrolling of the grid? Example. Should the cell remain in edit mode?
- Press the
- As an end user, I want to discard the changes to the cell value when I:
- Press
Escape
key - Already supported. ESC revers and exits edit mode for the cell and row. - On blur - Won't discard,
Blur
commits. On selection of another cell, edited cell will commit its value.
- Press
- As an end user, I want to know the count of the changes and of the hidden columns when editing a row.
While editing if the following action occurs it will:
Feature | Keep in edit mode | Exit edit mode | Commit | Does not commit |
---|---|---|---|---|
Filtering | ❌ | ✔ | ❌ | ✔ |
Sorting | ❌ | ✔ | ❌ | ✔ |
Paging | ❌ | ✔ | ❌ | ✔ |
Moving | ❌ | ✔ | ❌ | ✔ |
Pinning | ❌ | ✔ | ❌ | ✔ |
Hiding | ❌ | ✔ | ❌ | ✔ |
Group By | ❌ | ✔ | ❌ | ✔ |
Resizing | ✔ | ❌ | ❌ | ❌ |
Enter | ❌ | ✔ | ✔ | ❌ |
Escape | ❌ | ✔ | ❌ | ✔ |
F2 | ❌ | ✔ | ✔ | ❌ |
Tab click | ❌ | ✔ | ✔ | ❌ |
Cell click | ❌ | ✔ | ✔ | ❌ |
Add new row | ❌ | ✔ | ✔ | ❌ |
Delete row | ❌ | ✔ | ✔ | ❌ |
Enabled if the column is set to be editable
.
- On double click
- On single click - Single click will enter edit mode only if the previously selected cell was in edit mode and currently selected cell is editable. If the previously selected cell was not in edit mode, single click will select the cell without entering edit mode;
- On key press
Enter
- On key press
F2
- With changes commit
- On key press
Tab
- On single click to another cell - when you click on another cell in the grid, your changes will be submitted.
- On key press
The cell remains in edit mode when you scroll vertically or horizontally or click outside the grid.
editable
on each igx-column
component.
On the igx-grid
component:
cellEditEnter
- emits when an editable cell enters in edit mode.
cellEdit
- emits before committing the new cell value.
cellEditDone
- emits after cell edit's new value has been committed.
cellEditExit
- emits when the cell has exited edit mode.
See Event arguments and sequence for more details on order and arguments.
When row editing is enabled for a grid that has some of its columns defined as not editable, within the row edit UI their content is displayed in a grayed-out / disabled style. Text, numbers and icons are shown in grays.500 color and boolean columns will show a disabled checkbox in on/off state depending on the value from the data source.
rowEditable
- enables/disables row editing overlay. If rowEditable is enabled then all columns that have field property defined, unless primaryKey, will be editable, even though the editable property is not defined for them.
rowEditEnter
- emitted when an editable row enters in edit mode.
rowEdit
- emitted when row edit is exited and the changes are committed.
rowEditDone
- emitted after a row has been edited and new row's value has been committed.
rowEditExit
- emitted when the row has exited edit mode.
See Event arguments and sequence for more details on order and arguments.
- [igxRowEditText] - reference template for row editing ovelray text
- [igxRowEditActions] - reference template that holds buttons
- [IgxRowEditTabStopDirective] - selector
[igxRowEditTabStop]
- set on any elements inside of a custom row-edit overlay that should be accessibly viaTab
navigation. Any elements with the directive still must have a tab index set.
Transaction
is a provider that accumulates the applied changes as a transaction log and in the same time holds a state for each modified row and its last state.
transactions
- returns the Transaction
object that contains all transactions and the states of the modified rows.
add(transaction, recordRef?)
- adds transaction.
getTransactionLog(id?)
- returns all transactions. If id is provided returns last transaction for provided id.
aggregatedState()
- returns changed state for all changed rows.
getState(id)
- returns the state for the row with provided id.
enabled()
- returns whether transaction is enabled for this service.
getAggregatedValue(id, mergeChanges?)' - returns changed field for the row with provided id. If
mergeChanges` is set to true returns entire data row with all the fields.
startPending()
- start pending transaction that accumulates changes and is not added to the transaction log.
endPending()
- add pending transactions to the transaction log.
commit(data)
- commits all the changes into the specified data.
clear
- clear all pending transactions and state
undo()
- removes the last transaction if any.
redo()
- applies the last undone transaction if any.
Interactive Prototype Showing the Flow of Actions
- Default position of the overlay will be below the row that is in edit mode, unless there is no space - in that case it will appear above the row. Once shown top/bottom this position is maintained during scrolling, until the overlay is closed.
- While in row edit mode, loosing focus and moving to a cell in another row, then all the cell changes in the previous row are applied.
- While in row edit mode, click on a non-editable cell in either the same or another row, all the cell changes in the previously edited row are applied, row exits edit mode and overlay is closed.
- While in row edit mode, the
TAB
(andShift + Tab
) key moves the user only between editable cells, skipping hidden ones, until the last (first) cell is reached. PressingTAB
on the last editable cell (Shift + Tab
on the first) will transition the focus to the first (last) focusable element (marked with theigxRowEditTabStop
directive) in the row edit overlay. - While row is in edit mode, and data operation is executed, then the row exits edit mode and current changes are applied, either directly to the data source, or to a transaction provider, if available. This is valid for cases like, changing page or page size, sorting, filtering etc.
- While row is in edit mode, grid is scrolled and row goes outside the visible area, and then the grid is scrolled so that the row is visible again, the row should be still in edit mode.
- As an end user, I want to commit the changes to the whole row when I:
- Press the
Enter
key - Press the
F2
key
- Press the
- As an end user, I want to cancel the changes to the whole row when I:
- Press the
Esc
key
- Press the
- As an end user, I want to move the focus from one editable cell in the row to the next, and from the right-most editable cell to the CANCEL and DONE buttons, and from the DONE button to the left-most editable cell within the currently edited row.
- Press the
Tab
key - Press the
Shift + Tab
key for the opposite direction
- Press the
-
General tests:
- Should be able to enter edit mode on dblclick, enter and f2.
- Should display the banner below the edited row if it is not the last one.
- Should display the banner after the edited row if it is the last one, but has room underneath it.
- Should display the banner above the edited row if it is the last one.
- Should add correct class to the edited row.
- Should preserve updated value inside the cell when it enters edit mode again. Grid editing events (execution sequence and cancelation process)
-
Grid editing events (execution sequence and cancelation process) Execution sequence: RowEditEnter -> cellEditEnter -> cellEdit -> cellEditDone -> cellEditExit -> rowEdit -> rowEditDone -> rowEditExit
** rowEditEnter:
- When canceled and press enter and double click over a cell not cell nor row should be in edit mode
- If rowEditEnter is canceled cellEditEnter shouldn't be emitted.
** cellEditEnter:
-
When cellEditEnter is canceled cell edit should never enter edit mode. Once the cancelation Is released cell should be able to enter edit freely.
-
When rowEdit is enabled and cellEditEnter is canceled and approach editing, only the row should remain in edit mode.
-
When rowEdit is enabled and cellEditEnter is canceled and in edit mode, you should be able to navigate through rows by mouse click, while row editing remains open till you cancel it or hit done button.
-
When rowEdit is enabled and cellEditEnter is canceled and in edit mode, tabulation and arrow keys should navigate only within the context of the opened row edit.
** cellEdit:
-
When cellEdit is canceled and in edit mode, the cell should never be committed by pressing enter and cell should remain in edit mode.
-
When cellEdit is canceled and in edit mode, pressing esc should exit the edit mode.
-
When cellEdit is canceled and in edit mode with rowEdit enabled, cell should never be commited by pressing enter but should close cell and row edit.
-
When cellEdit is canceled and in edit mode with rowEdit enabled, pressing done or cancel should not commit any value and should close cell and row edit.
-
When cellEdit is canceled and in edit mode with rowEdit enabled, pressing tab with new values within the cell should never be stored or saved.
** cellEditExit:
-
When cellEditExit is canceled cell should never leave edit mode no matter what you are pressing (enter, mouse click, etc.)
-
When cellEditExit is canceled and sorting or filtering is trigger cell should leave edit mode.
-
When cellEditExit is canceled and rowEdit is enabled and in edit mode, not clicking outside nor tabulation or cancel/done button press should close cell/row editing.
-
When cellEditExit is canceled and enter edit mode and change the value, pressing enter should commit.
** rowEdit:
-
When rowEdit is canceled, clicking done button should do nothing
-
When rowEdit is canceled, you should be able to set new values in cells but not committing them
-
When rowEdit is canceled, tabulating between cells in the context should be allowed
** rowEditExit:
-
When rowEditExit is canceled tabulation and edit mode of the cells should be allowed
-
When rowEditExit is canceled, cancel and done button should not close or commit row editing
-
When rowEditExit is canceled, editing cell and committing it's value by hitting enter should reflect on the summaries calculations but should not close row editing mode.
-
Navigation - Keyboard:
- Should jump from first editable columns to overlay buttons.
- Should jump from last editable columns to overlay buttons.
- Should scroll editable column into view when navigating from buttons.
- Should skip non-editable columns.
- Should skip non-editable columns when column pinning is enabled.
- Should skip non-editable columns when column hiding is enabled.
- Should skip non-editable columns when column pinning & hiding is enabled.
- Should skip non-editable columns when column grouping is enabled.
- Should skip non-editable columns when column when all column features are enabled.
-
Exit row editing:
- Should call correct methods on clicking DONE and CANCEL buttons in row edit overlay.
- Should exit row editing AND COMMIT on clicking the DONE button in row edit overlay.
- Should exit row editing AND COMMIT on add row.
- Should exit row editing AND COMMIT on delete row.
- Should exit row editing AND DISCARD on filter.
- Should exit row editing AND DISCARD on sort.
- Should exit row editing AND COMMIT on click on non-editable cell in same row.
- Should exit row editing AND COMMIT on click on non-editable cell in other row.
- Should exit row editing AND COMMIT on click on editable cell in other row.
- Should exit row editing AND COMMIT on ENTER KEYDOWN.
- Should exit row editing AND DISCARD on clicking the CANCEL button in row edit overlay.
- Should exit row editing AND DISCARD on ESC KEYDOWN.
-
Paging:
- Should preserve the changes after page navigation.
- Should save changes when changing page while editing.
- Should exit edit mode when changing the page size while editing.
- Should exit edit mode when changing the page size resulting in the edited cell going to the next page.
-
Filtering:
- Should exit edit mode on filter applied.
- Should include the new value in the results when filtering.
- Should preserve the cell's data if it has been modified while being filtered out.
-
Row Editing - GroupBy:
- Should exit edit mode when Grouping/UnGrouping.
-
Sorting:
- Should exit edit mode when Sorting.
- Should include the new value in the results when sorting.
- Editing a sorted row.
-
Summaries:
- Should update summaries after row editing completes.
-
Column manipulations:
- Should exit edit mode when moving a column.
- Should exit edit mode when pinning/unpinning a column.
- Should exit edit mode when resizing a column.
- Should exit edit mode when hiding a column.
- Should close the row editing overlay on column hiding.
- Should show the updated value when showing the column again.
-
Events:
- Should properly emit 'onRowEdit' event - Button Click.
- Should properly emit 'onRowEditCancel' event - Cancel Button Click.
- Should properly emit 'onRowEditCancel' event - Sorting.
- Should properly emit 'onRowEdit' event - Filtering.
- Should properly emit 'rowEditDone' event if there is a change made - Button Click.
-
Column editable property:
- Default column editable value is true, when row editing is enabled.
-
Row Editing Overlay:
- Open overlay for top row.
-
Row Editing - Custom overlay:
- Custom overlay.
-
Row Editing - Transaction:
- Transaction Update, Delete, Add, Undo, Redo, Commit check transaction and grid state.
- Should allow change value of cell with initial value of 0.
- Should allow change value of cell with initial value of false.
- Should allow change value of cell with initial value of empty string.
- Should allow to change of a cell in added row in grid with transactions.
-
API methods:
- Should not commit added row to grid's data in grid with transactions.
- Should not delete deleted row from grid's data in grid with transactions.
- Should not update updated cell in grid's data in grid with transactions.
Event | Description | Arguments | Cancellable |
---|---|---|---|
rowEditEnter |
If [rowEditing] is enabled, fires when a row enters edit mode
|
IGridEditEventArgs |
true |
cellEditEnter |
Fires when a cell enters edit mode | IGridEditEventArgs |
true |
cellEdit |
If value is changed, fires just before a cell's value is committed (e.g. by pressing Enter ) |
IGridEditEventArgs |
true |
cellEditDone |
If value is changed, fires after a cell has been edited and cell's value is committed | IGridEditDoneEventArgs |
false |
cellEditExit |
Fires when a cell exits edit mode | IGridEditEventArgs |
false |
rowEdit |
If [rowEditing] is enabled, fires just before a row in edit mode's value is committed (e.g. by clicking the Done button on the Row Editing Overlay) |
IGridEditEventArgs |
true |
rowEditDone |
If [rowEditing] is enabled, fires after a row has been edited and new row's value has been committed. |
IGridEditDoneEventArgs |
false |
rowEditExit |
If [rowEditing] is enabled, fires when a row exits edit mode
|
IGridEditEventArgs |
false |
Note: In a row editing scenario cell edit events fire normally, so after the initial
rowEditEnter
multiple cell edit event sequences may fire depending on the user interaction, until a finalize action is taken (Enter, Done button) which finishes current cell edit (if any) and goes through the row's edit->done->exit sequence.
If the following event is canceled:
- RowEditEnter - Neither Row nor Cell will enter edit mode.
- CellEditEnter - Row edit allowed, although neither of the cells in the row context will be editable.
-
CellEdit - Allowed Cell/Row edit, hitting
Done
button orEnter
won't commit the value or row transaction. Cell editing and Row editing won't be closed untilCancel
button is hit. -
RowEdit - Committing cell is possible, but not the whole row. The row will stay in edit mode and the row transaction will be considered open. Hitting
Done
does not commit or close the row.Cancel
button closes the editing process and the transaction without committing the changes.