Grid Editing

• Revision history
• Overview
  • Objectives
• User Stories - Developer - End user
• Row editing
  • Transactions
  • Navigation
  • Additional Keyboard Navigation Scenarios
  • Test Scenarios
• Cell editing
  • Enter edit mode
  • Exit edit mode
  • Scrolling

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

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. Note:
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.

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:

onRowEditDone - emitted when row edit is exited and the changes are committed.

onRowEditCancel - emitted when row edit is exited and the changes are not committed.

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.
• 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 COMMIT on filter.
  • Should exit row editing AND COMMIT 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 'onRowEditDone' event - Button Click.
  • Should properly emit 'onRowEditCancel' event - Button Click.
  • Should properly emit 'onRowEditDone' event - Filtering.
  • Should properly emit 'onRowEditDone' event - Sorting.
• 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.

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

• Without commiting the changes
  • On key press Enter
  • When you perform paging, sorting, filtering, searching and hiding operations;
• With changes commit
  • On key press Enter
  • On key press F2
  • On key press Tab
  • On single click to another cell - when you click on another cell in the grid, your changes will be submitted.
  • Operations like, resize, pin, move, sort column or change page, will exit edit mode and changes will be submitted.

Scrolling

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