Row Edition

This section describes how to enable the edition operations and perform the edition per row.

Live example

Row Edition live example.

Allowing edition

To allow the user to edit the DikeGrid rows, you must provide an input property called allowEdition.

row-edition.component.html
<dike-grid id="grid-row-edition" height="600px" #grid="dkgGrid"
    allowEdition>
</dike-grid>

You can not change the allowEdition property at runtime.

Edition mode

The allowEdition property internally prepares the DikeGrid to support row edition, but you can only set this property at the creation phase.

The edition mode toggles the DikeGrid UI to show the necessary elements to execute edition operations. Therefore, you must provide an input property named editionMode.

row-edition.component.html
<dike-grid id="grid-row-edition" height="600px" #grid="dkgGrid"
    allowEdition
    [editionMode]="gridProperties.editionMode">
</dike-grid>

Open the Floating Configuration Panel for the live example and click on the Edition mode checkbox.

Once you have enabled the edition mode, you will see an icon (three vertical dots) at the left of every row. When you click on this icon, it will show a contextual menu with the edition operations.

Edition actions

Once you have allowed the edition operations and toggled the DikeGrid to the edition mode, you can take a row to the edition state, make some changes to its fields and then cancel the edition or save the changes. Of course, you can also delete the row.

Before exploring the edition actions, consider the following column configuration:

row-edition.component.html
<dike-grid id="grid-row-edition" height="600px" #grid="dkgGrid"
    allowEdition
    [editionMode]="gridProperties.editionMode">

    <dike-grid-column
        fieldName="employeeId"
        headerText="Employee Id"
        dataType="Text"
        width="350"
        sortable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="completeNameGroup"
        headerText="Complete Name">

        <dike-grid-column
            fieldName="firstName"
            headerText="Name"
            dataType="Text"
            width="150"
            sortable
            editable>
        </dike-grid-column>

        <dike-grid-column
            fieldName="lastName"
            headerText="Surname"
            dataType="Text"
            width="150"
            sortable
            editable>
        </dike-grid-column>
    </dike-grid-column>

    <dike-grid-column
        fieldName="gender"
        headerText="Gender"
        dataType="Binary"
        width="110"
        sortable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="age"
        headerText="Age"
        dataType="Numeric"
        contentAlign="center"
        width="100"
        sortable
        editable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="email"
        headerText="Email"
        dataType="Text"
        width="300"
        sortable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="hireDate"
        headerText="Hire Date"
        dataType="Date"
        sortable
        editable>
    </dike-grid-column>

</dike-grid>

We have defined all columns as editable except for EmployeeId, Gender, and Email columns.

You can not make a column group editable.

Row Status

When the DikeGrid wraps the provided entries, it assigns to the row a creation timestamp, and a status equals to Read value.

The DikeGrid changes the row status and the timestamp every time an edition operation occurs.

The row status values are:

Edition operation
Row status value

No operation

Read

Edition

Editing

Update

Modified

Remove

Deleted

Editing a row

You can double-click on a row to change it to the edition state or click on the Edit option from the row context menu.

After changing a row to the edition state, the DikeGrid instance shows the default column templates for editing. It also displays an icon (a pencil) indicating editing that row.

See the Edition Templates section to customize the column templates for editing.

Saving changes

After you have made the changes you needed, you can save those changes by pressing the ENTER key or clicking on the Save option from the row context menu.

Be aware that the DikeGrid will save the edited row if it is not pristine and is valid. Therefore, the DikeGrid will save the row if you have changed it.

Let us add a simple validator to the Name column to see validation in action.

row-edition.component.html
<dike-grid-column
    fieldName="completeNameGroup"
    headerText="Complete Name">

    <dike-grid-column
        fieldName="firstName"
        headerText="Name"
        dataType="Text"
        width="150"
        sortable
        editable
        [editionSettings]="{ required: true }">
    </dike-grid-column>
</dike-grid-column>

We have just made the Name column required. If you do not provide a value for the Name field, the DikeGrid will show a red bar at the left of the Name field.

When you click on the red bar, the DikeGrid will show you the error message coming from the validator.

We have added a basic validator but very common. You can add more validators to a column, even your custom validators. See the Edition validation section for more details.

After updating the row, the DikeGrid changes the row status to the Modified value.

Canceling edition

You can cancel the row edition at any time by pressing the ESC key or clicking on the Cancel option from the row context menu.

If you have made changes, you will lose those changes by canceling the row edition.

Deleting a row

You can remove a row by clicking on the Delete option from the row context menu.

You can not delete a row if the row is in edition state.

After deleting a row, the DikeGrid changes the row status to the Deleted value.

Edition triggers

We named edition triggers those actions that help you interact with the DikeGrid rows in edition state.

There is one edition trigger per edition action except for deletion. Edition triggers work over a single row. We have seen every edition trigger in the previous sections. See the following table:

Edition action
Edition trigger

Edit

Double-click

Save

Press the ENTER key

Cancel

Press the ESC key

You can disable these edition triggers by providing the related Injection Tokens or at the grid level.

Disabling triggers at the grid level

You must provide a false value to the corresponding flag through the input property named gridEditionSettings.

The gridEditionSettings property is of type DikeGridEditionSettings. You must provide the corresponding flag related to edition triggers.

Let us disable the ENTER key corresponding to the Save action.

<dike-grid id="grid-row-edition" height="600px" #grid="dkgGrid"
    allowEdition
    [editionMode]="gridProperties.editionMode"
    [gridEditionSettings]="editionSettings">
</dike-grid>

Please, open the live example and test if you can save a row by pressing the ENTER key.

You can only set the gridEditionSettings property at the creation phase.

Disabling triggers by providing an Injection Token

Every edition trigger can be disabled by providing the related Injection Token.

Edition trigger
Injection Token

Double-click

ROW_EDITION_DBLCLICK

ENTER Key

ROW_EDITION_ENTER_KEY

ESC Key

ROW_EDITION_ESC_KEY

Same as before, you must provide a false value to the corresponding Injection Token.

Let us disable the ESC key related to the Cancel action.

editing.module.ts
@NgModule({
  providers: [
    { provide: ROW_EDITION_ESC_KEY, useValue: false }
  ]
})
export class EditingModule { }

Please, open the live example and test if you can cancel the row edition by pressing the ESC key.

Editing using the API

You can perform the edition actions using the corresponding API.

Before using the API, we have to retrieve the DikeGrid instance from the component's view.

<dike-grid id="grid-row-edition" height="600px" #grid="dkgGrid">
</dike-gris>

DikeGrid Column API

Using the column API, you can make a column editable and establish its edition settings at runtime.

Method
Description

setColumnEditable()

Use this method to set or unset a column editable.

For further details, see the DikeGridColumnDef definition.

DikeGrid Edition API

You can use the edition API for managing the edition actions.

The methods in the edition API are:

Method
Description

editRow()

This method will change the row status to edition state.

updateRow()

It saves the changes in the given row. The given row must be valid a not pristine. After updating, the DikeGrid sets the row status to Modified.

cancelRowEdition()

It changes the row status to Read status. This method discards all the changes in the given row.

removeRow()

This method will change the row status to Deleted status.

restoreRow()

This method will revert any change that the user has made.

The properties in the edition API are:

Property
Description

rowsInEdition

It returns the current rows in edition state.

modifiedRows

It returns all the rows that have changes in their fields.

removedRows

It returns all the deleted rows.

For further details, see the DikeGridEdition definition.

You do not have to provide the editionMode property for edition API use. It is enough to allow edition by providing the property named allowEdition.

To see the API in action, let us define the following API:

<div class="mt-2 flex flex-row flex-wrap items-center justify-around">
    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onEditRow()"
            [disabled]="!isFiltered">editRow - filtered
        </button>

        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onEmailEditable()">Email - editable
        </button>
    </div>

    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onUpdateRow()">updateRow
        </button>

        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onRestoreRowModified()">restoreRow - modified
        </button>
    </div>

    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onCancelRowEdition()">cancelRowEdition
        </button>

        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onRemoveRow()">removeRow - filtered
        </button>
    </div>

    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onRestoreRowDeleted()">restoreRow - deleted
        </button>
    </div>
</div>

The previous definition generates the following output:

You can only have one row in edition state, and we have enabled the In-line filters.

We describe every button in the following list.

  1. Email - editable. Click on this button to make the Email column editable or not editable. It toggles the current editable value, and it is marked as required.

  2. editRow - filtered. It changes one row from filtered set to edition state. It will be disabled if there are no filtered rows.

  3. updateRow. It saves the changes of the row in edition mode.

  4. restoreRow - modified. It reverts changes from a modified row. You can revert all the changes you have made.

  5. cancelRowEdition. It cancels the edition of the row in edition state.

  6. removeRow - filtered. It takes a row from the filtered set and removes it.

  7. restoreRow - deleted. It restores a row from the deleted rows set.

  8. Rows in edition. It prints the row in edition mode.

  9. Modified rows. It prints all the rows that have been modified.

  10. Removed rows. It prints all the rows that have been deleted.

Edition events

When performing the edition actions, the DikeGrid instance emits the corresponding events.

Events regarding edition actions are:

Event
Description

editionRowChange

It emits the row that has been changed to edition mode.

updateRowChange

It emits the modified rows.

cancelRowEditionChange

It emits the rows that have been canceled for edition.

removeRowChange

It emits the rows that have been deleted.

restoreRowChange

It emits the rows whose changes were reverted.

Let us listen to these events:

<dike-grid id="grid-row-edition" height="600px" #grid="dkgGrid"
    (editionRowChange)="onEditionRowChange($event)"
    (updateRowChange)="onUpdateRowChange($event)"
    (cancelRowEditionChange)="onCancelRowEditionChange($event)"
    (removeRowChange)="onRemoveRowChange($event)"
    (restoreRowChange)="onRestoreRowChange($event)">
</dike-grid>

Please, open your dev console to see the output of these events.

You can also listen to these events from the DikeGridEdition instance.

Summary

You allow the edition by providing a property named allowEdition. Then, to let the user toggle to the edition mode, provide a property called editioMode. Finally, you define a column as editable to modify the column value.

In this section, we have explored how to edit one row at a time using the UI or the API.

Complete code for this section

<div class="mt-2 flex flex-row flex-wrap items-center justify-around">
    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onEditRow()"
            [disabled]="!isFiltered">editRow - filtered
        </button>

        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onEmailEditable()">Email - editable
        </button>
    </div>

    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onUpdateRow()">updateRow
        </button>

        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onRestoreRowModified()">restoreRow - modified
        </button>
    </div>

    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onCancelRowEdition()">cancelRowEdition
        </button>

        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onRemoveRow()">removeRow - filtered
        </button>
    </div>

    <div class="flex-none w-56 flex flex-col m-2 items-center">
        <button mat-raised-button
            class="flex-none w-56 my-2"
            color="primary"
            (click)="onRestoreRowDeleted()">restoreRow - deleted
        </button>
    </div>
</div>

<mat-divider class="m-6"></mat-divider>

<div class="mt-2 flex flex-row flex-wrap items-center justify-around">
    <button mat-raised-button
        class="flex-none w-56 my-2"
        color="primary"
        (click)="onRowsInEdition()">Rows in edition
    </button>

    <button mat-raised-button
        class="flex-none w-56 my-2"
        color="primary"
        (click)="onModifiedRows()">Modified rows
    </button>

    <button mat-raised-button
        class="flex-none w-56 my-2"
        color="primary"
        (click)="onRemovedRows()">Removed rows
    </button>
</div>

<dike-grid id="grid-row-edition" height="600px" #grid="dkgGrid"
    [displayRowId]="gridProperties.displayRowId"
    [gridElevation]="gridProperties.matElevation"
    [gridElevationValue]="gridProperties.elevationValue"
    [striped]="gridProperties.stripeRows"
    [verticalRowLines]="gridProperties.verticalRowLines"

    allowEdition
    [editionMode]="gridProperties.editionMode"
    [allowSorting]="gridProperties.allowSorting"
    [allowRowFiltering]="gridProperties.allowRowFilter"

    [gridEditionSettings]="editionSettings"

    (editionRowChange)="onEditionRowChange($event)"
    (updateRowChange)="onUpdateRowChange($event)"
    (cancelRowEditionChange)="onCancelRowEditionChange($event)"
    (removeRowChange)="onRemoveRowChange($event)"
    (restoreRowChange)="onRestoreRowChange($event)"
    (filterChange)="onFilterChange($event)"

    [datasource]="dkgDataSource">

    <dike-grid-column
        fieldName="employeeId"
        headerText="Employee Id"
        dataType="Text"
        width="350"
        sortable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="completeNameGroup"
        headerText="Complete Name">

        <dike-grid-column
            fieldName="firstName"
            headerText="Name"
            dataType="Text"
            width="150"
            sortable
            editable
            [editionSettings]="{ required: true }">
        </dike-grid-column>

        <dike-grid-column
            fieldName="lastName"
            headerText="Surname"
            dataType="Text"
            width="150"
            sortable
            editable>
        </dike-grid-column>
    </dike-grid-column>

    <dike-grid-column
        fieldName="gender"
        headerText="Gender"
        dataType="Binary"
        width="110"
        sortable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="age"
        headerText="Age"
        dataType="Numeric"
        contentAlign="center"
        width="100"
        sortable
        editable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="email"
        headerText="Email"
        dataType="Text"
        width="300"
        sortable>
    </dike-grid-column>

    <dike-grid-column
        fieldName="hireDate"
        headerText="Hire Date"
        dataType="Date"
        sortable
        editable>
    </dike-grid-column>

</dike-grid>

Last updated