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

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 confirming the addition.

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 7: 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 8: 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

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 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 + plus key	Enters edit mode for adding a row
Alt + Shift + plus key	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	`rowId`: object?
beginAddChild*	Starts the adding child UI	void	`rowId`: object

* only available for igxTreeGrid

Both methods accept a rowId parameter. For adding a row this specifies the row the UI should spawn under. If unspecified, the grid spawns the UI under the first visible row in the view.

For adding a child, the rowId parameter is mandatory as it specifies the parent of the new row.

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

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.

Action strip tests: