Grid Editing

• Revision history
• Overview
  • Objectives
• User Stories - Developer - End user
• Common behaviors
• Cell editing
  • Enter edit mode
  • Exit edit mode
  • Scrolling
• Row editing
  • Transactions
  • Navigation
  • Additional Keyboard Navigation Scenarios
  • Test Scenarios
• Event arguments and sequence
• Event cancelation

Revision history

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

Overview

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.

Objectives

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.

User Stories

Developer

1. As a developer, I want to be able to provide my own custom template for editing.
   • This feature is already supported.
2. 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.
3. 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.

End user

1. 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 or F2 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).
2. 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.
3. 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?
4. 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.

Common behaviors

Exit edit mode

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	❌	✔	✔	❌

Cell Editing

Enabled if the column is set to be editable.

Enter edit mode

• 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

Exit edit mode

• 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.

Scrolling

The cell remains in edit mode when you scroll vertically or horizontally or click outside the grid.

Inputs:

editable on each igx-column component.

Outputs:

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.

Row Editing

Inputs:

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.

Outputs:

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.

Directives:

• [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 via Tab navigation. Any elements with the directive still must have a tab index set.

Transactions

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.

IgxGridComponent

transactions - returns the Transaction object that contains all transactions and the states of the modified rows.

Transaction

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

Behavior, Navigation and interaction with other features

1. 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.
2. 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.
3. 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.
4. While in row edit mode, the TAB (and Shift + Tab) key moves the user only between editable cells, skipping hidden ones, until the last (first) cell is reached. Pressing TAB on the last editable cell (Shift + Tab on the first) will transition the focus to the first (last) focusable element (marked with the igxRowEditTabStop directive) in the row edit overlay.
5. 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.
6. 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.

Additional Keyboard Navigation Scenarios

1. As an end user, I want to commit the changes to the whole row when I:
   • Press the Enter key
   • Press the F2 key
2. As an end user, I want to cancel the changes to the whole row when I:
   • Press the Esc key
3. 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

Test Scenarios:

• 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 arguments and sequence

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.

Event cancelation

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 or Enter won't commit the value or row transaction. Cell editing and Row editing won't be closed until Cancel 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.