Grid cell editing and edit templates

Ignite UI for Angular Grid component provides a great data manipulation capabilities and powerful API for Angular CRUD operations. By default the Grid is using in cell editing and different editors will be shown based on the data type of the column, thanks to the default cell editing template. In addition you can define your own custom templates for update data actions and to override the default behavior for committing and discarding any changes.

Demo


Cell Editing

Editing through UI

In order to be able to enter edit mode for specific cell, you should first set the column to be editable. If you want to use a data type specific edit templates, you should specify the column dataType property. So let's now see what are the default templates for each type:

  • For string data type, default template is using igxInput
  • For number data type, default template is using igxInput type="number", so if you try to update cell to a value which can not be parsed to a number your change is going to be discarded, and the value in the cell will be set to 0.
  • For date data type, default template is using igx-date-picker
  • For boolean data type, default template is using igx-checkbox

You can enter edit mode for specific cell, when an editable cell is focused in one of the following ways:

  • 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;

You can exit edit mode without committing the changes in one of the following ways:

  • on key press Escape;
  • when you perform sorting, filtering, searching and hiding operations;

You can exit edit mode and commit the changes in one of the following ways:

  • 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 paging, resize, pin or move will exit edit mode and changes will be submitted.
Note

The cell remains in edit mode when you scroll vertically or horizontally or click outside the Grid. This is valid for both cell editing and row editing.

Editing through API

You can also modify the cell value through the IgxGrid API but only if primary key is defined:

...
    public updateCell() {
        this.grid1.updateCell(newValue, rowID, 'ReorderLevel');
    }
...

Please notice that if the cell you want to update is outside Grid's display container the new value will not be submitted.

Another way to update cell is directly through update method of IgxGridCellComponent:

...
    public updateCell() {
        const cell = this.grid1.getCellByColumn(rowIndex, 'ReorderLevel');
        // You can also get cell by rowID if primary key is defined
        // cell = this.grid1.getCellByKey(rowID, 'ReorderLevel');
        cell.update(70);
    }
...

Cell Editing Templates

If you want to provide a custom template which will be applied when a cell is in edit mode, you can make use of the igxCellEditor directive. To do this, you need to pass an ng-template with the igxCellEditor directive and properly bind your custom control to the cell.editValue:

<igx-column field="ReorderLevel" header="Reorder Level" [editable]="true">
    <ng-template igxCellEditor let-cell="cell">
        <input type="number" [(ngModel)]="cell.editValue" />
    </ng-template>
</igx-column>
Note

Any changes made to the cell's editValue in edit mode, will trigger the appropriate editing event on exit and apply to the transaction state (if transactions are enabled).

Note

The cell editing template directive (igxCellEditor) is different from the cell template(igxCell) - the former handles how a column's cells in edit mode are displayed an controls the edited cell's edit value, the latter control how a column's cell's are show when outside of edit mode.

For more information on how to configure columns and their templates, you can see the documentation for Grid Columns configuration.

CRUD operations

Note

Please keep in mind that when you perform some CRUD operation all of the applied pipes like filtering, sorting and grouping will be re-applied and your view will be automatically updated.

The IgxGridComponent provides a straightforward API for basic CRUD operations.

Adding a new record

The Grid component exposes the addRow method which will add the provided data to the data source itself.

// Adding a new record
// Assuming we have a `getNewRecord` method returning the new row data.
const record = this.getNewRecord();
this.grid.addRow(record);

Updating data in the Grid

Updating data in the Grid is achieved through updateRow and updateCell methods but only if primary key for the grid is defined. You can also directly update a cell and/or a row value through their respective update methods.

// Updating the whole row
this.grid.updateRow(newData, this.selectedCell.cellID.rowID);

// Just a particular cell through the Grid API
this.grid.updateCell(newData, this.selectedCell.cellID.rowID, this.selectedCell.column.field);

// Directly using the cell `update` method
this.selectedCell.update(newData);

// Directly using the row `update` method
const row = this.grid.getRowByKey(rowID);
row.update(newData);

Deleting data from the Grid

Please keep in mind that deleteRow() method will remove the specified row only if primary key is defined.

// Delete row through Grid API
this.grid.deleteRow(this.selectedCell.cellID.rowID);
// Delete row through row object
const row = this.grid.getRowByIndex(rowIndex);
row.delete();

These can be wired to user interactions, not necessarily related to the igx-grid; for example, a button click:

<button igxButton igxRipple (click)="deleteRow($event)">Delete Row</button>

Editing Events

The grid exposes a wide array of events that provide greater control over the editing experience. These events are fired during the Row Editing and Cell Editing life cycle - when starting, committing or canceling editing.

The events can be broken down as follows:

Event Description Arguments Cancellable
onCellEditEnter Fires when a cell enters edit mode IGridEditEventArgs true
onRowEditEnter If [rowEditing] is enabled, fires when a row enters edit mode (after onCellEditEnter) IGridEditEventArgs true
onCellEdit Fires when a cell's value is committed (e.g. by pressing Enter) IGridEditEventArgs true
onCellEditCancel Fires when a cell exits edit mode without committing its value (e.g. by pressing Escape) IGridEditEventArgs true
onRowEdit Fires when a row in edit mode's value is committed (e.g. by clicking the Done button on the Row Editing Overlay) IGridEditEventArgs true
onRowEditCancel Fires when a row exits edit mode without committing its values (e.g. by clicking the Cancel button on the Row Editing Overlay) IGridEditEventArgs true

All of the above events can be cancelled. For example, if onCellEditEnter is cancelled, the cell will never enter edit mode.

Cell validation on edit event

Using the grid's editing events we can alter how the user interacts with the grid. In this example, we'll validate a cell based on the data entered in it by binding to the onCellEdit event. If the new value of the cell does not meet our predefined criteria, we'll prevent it from reaching the data source by cancelling the event (event.cancel = true). We'll also display a custom error message using IgxToast.

The first thing we need to is bind to the grid's event:

<igx-grid (onCellEdit)="handleCellEdit($event)"
...>
...
</igx-grid>

The onCellEdit emits whenever any cell's value is about to be committed. In our handleCellEdit definition, we need to make sure that we check for our specific column before taking any action:

export class MyGridEventsComponent {
    ...
    public handleCellEdit(event: IGridEditEventArgs): void {
        const column = this.grid.columnList.find(e => e.index === event.cellID.columnID);
        if (column.header === "Ordered") {
            const rowData = this.grid.data
            .find(entry => entry[this.grid.primaryKey] === event.cellID.rowID);
            if (!rowData) {
                return;
            }
            if (event.newValue > rowData.UnitsInStock) {
                event.cancel = true;
                this.toast.show();
            }
        }
    }
}

If the value entered in a cell under the Ordered column is larger than the available amount (the value under Units in Stock), the editing will be cancelled and a toast with an error message will be displayed.

The result of the above validation being applied to our igx-grid can be seen in the below demo:


Styling

The IgxGrid allows for its cells to be styled through the Ignite UI for Angular Theme Library. The grid's theme exposes a wide range of properties, which allow users to style many different aspects of the grid.

In the below steps, we are going to go over how you can style the grid's cell in edit mode and how you can scope those styles.

In order to use the Ignite UI Theming Library, we must first import the theme index file in our global styles:

Importing style library

@import '~igniteui-angular/lib/core/styles/themes/index';
...

Now we can make use of all of the functions exposed by the Ignite UI for Angular theme engine.

Defining a palette

After we've properly imported the index file, we create a custom palette that we can use. Let's define two colors that we like and use them to build a palette with igx-palette:

$white: #fff;
$blue: #4567bb;

$color-palette: igx-palette($primary: $white, $secondary: $blue);

Defining themes

We can now define the theme using our palette. The cells are styled by the igx-grid-theme, so we can use that to generate a theme for our IgxGrid:

$custom-grid-theme: igx-grid-theme(
    $cell-editing-background: $blue,
    $cell-edited-value-color: $white,
    $cell-active-border-color: $white,
    $edit-mode-color: igx-color($color-palette, "secondary", 200)
);

Applying the theme

The easiest way to apply our theme is with a sass @include statement in the global styles file:

@include igx-grid($custom-grid-theme); 

This way, the theme will apply to all grids in our application. If we wish to apply this custom styling only to a specific component, we need to scope the theme.

Scoped component theme

In order for the custom theme do affect only our specific component, we can move all of the styles we just defined from the global styles file to our custom component's style file (including the import of the index file).

This way, due to Angular's ViewEncapsulation, our styles will be applied only to our custom component.

Note

If the component is using an Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep in order to style the grid.

Note

We wrap the statement inside of a :host selector to prevent our styles from affecting elements outside of our component:

:host {
    ::ng-deep {
            @include igx-grid($custom-grid-theme); 
        }
    }
}

Styling Demo

In addition to the steps above, we can also style the controls that are used for the cells' editing templates: igx-input-group, igx-datepicker & igx-checkbox


API References

Additional Resources