Grid Add Row

Add Row Specification

Owned by

Team Name

Developer Name

Stefan Ivanov

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date:

Signed off by

Radoslav Mirchev | Date:
Radoslav Karaivanov | Date:

Revision History

Version	Users	Date	Notes
1	Stefan Ivanov	22.08.2020	Initial Draft
2	Stamen Stoychev	01.09.2020	Adding developer experience
3	Stamen Stoychev	04.09.2020	Applying discussion feedback
4	Stefan Ivanov	28.09.2020	Adding row pinning integration
5	Stamen Stoychev	01.10.2020	Changing API

1. Overview

The Add Row functionality of the Grid provides the interface for inserting a new row of data that is input by the end-user field after field at the time of creation.

Objectives

Inserting additional rows of data should be an easy and intuitive experience that feels like belonging to the grid. Added rows should appear after the last row in the current context and there should be a clear indication that sets the correct expectation about this position. While the user puts in data, the record is not subjected to filtering, sorting and similar data operations, this happens once the row addition completes with a confirming action, when also a Snackbar notification is shown for 6 seconds (this value is configurable) to confirm the addition and allow the end-user jump to the newly added record.

End-to-end user experience prototype

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

...

2. User Stories

Elaborate more on the multi-facetted use cases

Developer stories:

Story 1: As a developer, I want to allow the addition of data rows via a property, so that I can let users insert records like in excel

End-user stories:

Story 1: As an end-user, I want to add rows of data in a grid, so that I can create new data records
Story 2: As an end-user, I want to trigger row addition from wherever I am in the grid so that I don't have to scroll to a particular place or look for a specific button to do so

Story 3: As an end-user, I want to input values cell after cell for every column similarly to how I edit a row so that I can fill all columns

Story 4: As an end-user, I want to add rows as siblings or children when data is organized hierarchically so that I have control over where records are inserted

Story 5: As an end-user, I want to cancel the addition of the data, so that I can discard my input so far
Story 6: As an end-user, I want to have a visual confirmation that a row has been added once I complete its input so that I have certainty that my data was added

Story 7: As an end-user, I want to make the grid scroll to the just added row so that I can inspect if it contains the correct information
Story 8: As an end user, I want the count of defined columns to be displayed in the defaultRowEditTemplate when adding new row in grid with enabled batch editing.

3. Functionality

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

3.1. End-User Experience

** The Add Row UI appears below the row from which it was triggered and behaves like a normal row with respect to vertical and horizontal scrolling, including scenarios where some column may be pinned. Once a row is committed with a confirming action, any data operations over the grid such as sorting, filtering, and group by are carried over the new row as well. The Add Row UI respects the grid display density and always takes twice the height of a grid row.

** When adding a new row is triggered by a Pinned row, the newly inserted row will inherit this context and appear as the last pinned row in the pinned collection.

** When multirow layouts are defined they affect the layout of the add row UI accordingly.

** When used in a TreeGrid the Add Row feature provides options to either insert the new row as a sibling at the same level for which the action strip is shown or as a child of it. In both cases, it is added as the last element at the bottom of the data island. prototype

** When used in a Hierarchical Grid the feature can be enabled for each grid in the hierarchy individually.

** End-to-end user experience. prototype

** Prepared design files for styling e.g. interplay with features and light/dark variants -> the add row UI leverages on existing styles and functionality defined for row editing with the only difference that the add row UI does not show a banner message.

3.2. Developer Experience

Enabling the UI

Two options control the presence of the row adding UI that separately enable the action strip buttons for rows and children.
```
<igx-grid>
    <igx-action-strip>
        <igx-grid-editing-actions [addRow]="true"></igx-grid-editing-actions>
    </igx-action-strip>
</igx-grid>
```
```
<igx-tree-grid>
    <igx-action-strip>
        <igx-grid-editing-actions [addRow]="true" [addChild]="true"></igx-grid-editing-actions>
    </igx-action-strip>
</igx-tree-grid>
```
Note: Decorating the component with the *IgxActionStripMenuItem directive will render the buttons in a dropdown instead of inline.

Note: Enabling add child for non-tree grid scenarios has no effect.

An API method is available to start the add row UI if the built-in buttons don't fit the application requirements.

Regardless of the presence of these options the key combinations for spawning the add row UI as listed below are active for grids that have rowEditing enabled. This prerequisite comes from the requirement to allow new, uncommitted rows to be further editable before commit.

Users may prevent spawning the new row UI by subscribing to the rowEditEnter output and set its cancelled argument when the addRow flag is active.
```
function onRowEditEnter($args) {
    if ($args.newRow) {
        $args.cancel = true
    }
}
```
Note: A compatible grid is one that has PK defined.
Providing a PK

A grid with CRUD enabled requires a primary key field to be defined.

If the added record has no PK field value, one will be generated based on the related column dataType (if set) or on the field data type.

The generated unique id will be:
- GUID if the field is of type string.
- Negative number if the field is of type number.
In case the data type is not set and cannot be inferred then the type will default to string.

The developer may provide a primary key value of his own via the editRow events in case he wants to use a different primary key generation logic or if he wants to prevent the users from setting a duplicate primary key value (in case the column is editable).

Remote scenarios

In most remote data scenarios the PK assignment happens on the create server response. In this case the added records on the client will not have the final primary key value until saved on the server in a data base. In that case the recommended way to handle this update in the grid is as follows:
1. If the grid does not use transactions.
  
  Once the create request is successfully completed and returns the added record data, the developer can replace that record's id in his local data record instance.
2. If the grid uses transactions.
  
  Once the create request or batch update request is successfully completed and returns the added record instances (with their db generated ids), the related ADD transactions should be cleared from the transaction log using the clear API method. This is necessary because the local transaction will have a generated id field, which may differ than the one created in the DB, so they should be cleared. The developer can then add the records passed in the response to his local data instance.
This will ensure that the remotely generated ids are always reflected in the local data, and subsequent update/delete operations target the correct record ids.

3.3. Globalization/Localization

Done, Cancel buttons

If the action strip menu is rendered as menu these additional strings appear and are also localized:

Add Row, Add Child

3.4. Keyboard Navigation

Keyboard navigation while in edit mode for adding a row or child repeats the behavior of row editing as it uses the same template. The following additions are available to the grid body key combinations for adding a row and a child:

Name	Description
`ALT` + `+`	Enters edit mode for adding a row
MacOS`option` + `=`	Enters edit mode for adding a row
`ALT` + `SHIFT` + `+`	Enters edit mode for adding a child (igxTreeGrid only)
MacOS`option` + `shift` + `=`	Enters edit mode for adding a child (igxTreeGrid only)

Note: Both key combinations function only when row adding is enabled through the grid options.

3.5. API

Options

In igxGridEditingActions component:

Name	Description	Type	Default value	Valid values
addChild	Shows/hides the add child button based on context expression	boolean	true	true, false
addRow	Shows/hides the add row button based on context expression	boolean	true	true, false

Could be just set to true to show the buttons for spawning the adding UI but may also contain an expression to conditionally hide them for certain conditions. As an example the following will hide the add child button for tree rows that have hierarchy level 3 or more:

<igx-tree-grid [rowEditing]="true">
    <igx-action-strip #actionStrip>
        <igx-grid-editing-actions [addRow]="true" [addChild]="actionStrip.context.level < 3">
        </igx-grid-editing-actions>
    </igx-action-strip>
</igx-tree-grid>

Methods

Name	Description	Return type	Parameters
beginAddRow	Starts the adding row UI	void
beginAddChild*	Starts the adding child UI	void

* only available for igxTreeGridRow

Both methods are available for and use the context of the row components of their respective grids.

Events

Name	Description	Cancelable	Parameters

Note: The editing UI fires all appropriate events that row editing would. However, the event arguments include an additional addRow boolean parameter indicating the purpose the UI spawned for.

4. Test Scenarios

Grid

Automation

General tests:

Should be able to enter add row mode on action strip click.
Should be able to enter add row mode through the exposed API method (w/ and w/o rowID).
Should display the banner above the row if there is no room underneath it.
Should not be able to enter add row mode when rowEditing is disabled.
Should be able to enter add row mode through the key combination Alt + plus key.
Should be able to enter add child row mode through the exposed API method (rowID is needed).
Should be able to enter add child row mode through the key combination Alt + Shift + plus key.
Should emit all grid editing events as per row editing specification.
Should generate correct row id based on the primary column type.
Should correctly add new row as last row.

Action strip tests:

Should be able to spawn the row adding UI for rows and children.
Should be able to spawn the adding UI depending on an expression.

Exit add row mode tests:

Should exit add row mode and commit on clicking DONE button in the overlay.
Should exit add row mode and discard on clicking CANCEL button in the overlay.
Should exit add row mode and discard on ESC KEYDOWN.
Should exit add row mode and commit on ENTER KEYDOWN.

Feature Integration:

Paging:

Should preserve the changes after page navigation.
Should save changes when changing page while adding row.
Should go to correct page via the the action strip "Show" button when row is added.

Filtering:

Should exit add row mode on filter applied.
Filtering should consider newly added rows.
Should not show the action strip "Show" button if added row is filtered out.

Sorting:

Should exit add row mode and discard on sorting.
Sorting should consider newly added rows.
Should go to correct row via the the action strip "Show" button when row is added in sorted grid.

Master-Detail:

Should collapse expanded detail view before spawning add row UI.

Multi-row layout

Should render adding row with correct mrl layout.

Row Pinning

Should allow adding row from pinned row - both the disabled one in the scrollable area and from the pinned area.
Should add row as pinned if it was added from a pinned row.
Should add row as unpinned if added from the pinned(disabled) row in the scrollable area.

Group by

Should show the action strip "Show" button if added row is in collapsed group and on click should expand the group and scroll to the correct added row.

Summaries:

Should update summaries after adding new row.

Column manipulations:

Should exit add row mode when moving a column.
Should exit add row mode when pinning/unpinning a column.
Should exit add row mode when resizing a column.
Should exit add row mode when hiding a column.

Add row transactions:

Should create ADD transaction when adding a new row.
All updates on uncommitted add row should be merged into one ADD transaction.

Tree Grid

General tests:

Should show action strip "add row" button only for root level rows.
Should show action strip "add child" button for all rows.
Should be able to enter add row mode through the exposed API method - beginAddChild
Should allow adding child to row via the UI.
Should show the action strip "Show" button if added row is child of collapsed tree row and on click should expand it and scroll to the correct added row.