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. While adding a row the developer must step in and ensure that a unique value is provided for the PK field of the new record being added by the end-user. In most cases this PK assignment happens on the create server response. The grid does not assign PKs to new rows. What's more, if the PK column is editable there is no mechanism to disallow the user to fill in a value for it (even if the value is non-unique).

When editing for adding a row ends with confirmation from the end-user, one of two things happen:
- If the grid uses transactions, a new row transaction is added. The grid ensures that such rows are identified by object references and may be further edited until a commit is called.
- If the grid does not use transactions, the new row is directly added to its data source. Unless this operation is intercepted by subscribing to an appropriate for your application rowEdit event and a PK is assigned for the row, the correct behavior of that row is no longer ensured.

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.