Premium

Web Components Hierarchical Grid Row Adding

The Ignite UI for Web Components Row Adding feature in Web Components Hierarchical Grid enables users to input and submit new data records without navigating to a separate form or page. With the IgcHierarchicalGrid, users can manipulate data through inline row adding and a powerful API for CRUD operations. Add an ActionStrip component with editing actions enabled in the grid’s template. After that hover a row and use the provided button. Finally press ALT + + to spawn the row adding UI.

Web Components Hierarchical Grid Row Adding Example

Row Adding Usage

Then define a IgcHierarchicalGrid with bound data source, IgcHierarchicalGrid.rowEditable set to true and an ActionStrip component with editing actions enabled. The IgcHierarchicalGrid.addRow input controls the visibility of the button that spawns the row adding UI.

<igc-hierarchical-grid id="hGrid" auto-generate="false" primary-key="Debut" row-editable="true">
    <igc-column field="Artist" data-type="string"></igc-column>
    <igc-column field="HasGrammyAward" header="Has Grammy Award?" data-type="boolean">
    </igc-column>
    <igc-column field="Debut" data-type="number"></igc-column>
    <igc-column field="GrammyNominations" header="Grammy Nominations" data-type="number"></igc-column>
    <igc-column field="GrammyAwards" header="Grammy Awards" data-type="number"></igc-column>

    <igc-action-strip id="actionstrip1">
        <igc-grid-editing-actions add-row="true"></igc-grid-editing-actions>
    </igc-action-strip>

    <igc-row-island key="Albums" auto-generate="false" primary-key="USBillboard200" row-editable="true">
        <igc-column field="Album" [data-type]="String"></igc-column>
        <igc-column field="LaunchDate" header="Launch Date" data-type="date"></igc-column>
        <igc-column field="BillboardReview" header="Billboard Review" data-type="number"></igc-column>
        <igc-column field="USBillboard200" header="US Billboard 200" data-type="number"></igc-column>
        <igc-row-island key="Songs" auto-generate="false" primary-key="Number" row-editable="true">
            <igc-column field="Number" header="No." data-type="number"></igc-column>
            <igc-column field="Title" data-type="string"></igc-column>
            <igc-column field="Released" data-type="date"></igc-column>
            <igc-column field="Genre" data-type="string"></igc-column>

            <igc-action-strip id="actionstrip3">
                <igc-grid-editing-actions add-row="true"></igc-grid-editing-actions>
            </igc-action-strip>

        </igc-row-island>

        <igc-action-strip id="actionstrip2">
            <igc-grid-editing-actions add-row="true"></igc-grid-editing-actions>
        </igc-action-strip>
    </igc-row-island>
</igc-hierarchical-grid>

Note: Setting primary key is mandatory for row adding operations.

Note: Every column excluding the primary key one is editable in the row adding UI by default. If you want to disable editing for a specific column, then you have to set the Column.editable column’s input to false.

Note: The GridEditingActions input controlling the visibility of the add row button may use the action strip context (which is of type IgcRowType to fine tune which records the button shows for.

The internal BaseTransactionService is automatically provided for IgcHierarchicalGrid. It holds pending cell changes until the row state is submitted or cancelled.

Start Row Adding Programmatically

IgcHierarchicalGrid allows to programmatically spawn the add row UI by using two different public methods. One that accepts a row ID for specifying the row under which the UI should spawn and another that works by index. You can use these methods to spawn the UI anywhere within the current data view. Changing the page or specifying a row that is e.g. filtered out is not supported.

Using IgcHierarchicalGrid.beginAddRowById requires you to specify the row to use as context for the operation by its RowID (PK). The method then functions as though the end-user clicked on the add row action strip button for the specified row, spawning the UI under it. You can also make the UI spawn as the very first row in the grid by passing null for the first parameter.

this.grid.beginAddRowById('ALFKI');  // Spawns the add row UI under the row with PK 'ALFKI'
this.grid.beginAddRowById(null);     // Spawns the add row UI as the first record

The IgcHierarchicalGrid.beginAddRowByIndex method works similarly but requires you to specify the index at which the UI should spawn. Allowed values range between 0 and the size of the data view - 1.

this.grid.beginAddRowByIndex(10);   // Spawns the add row UI at index 10
this.grid.beginAddRowByIndex(0);    // Spawns the add row UI as the first record

Positioning

The default position of row add UI is below the row that the end user clicked the add row button for.
The IgcHierarchicalGrid scrolls to fully display the add row UI automatically.
The overlay for the add row UI maintains its position during scrolling.

Behavior

The add row UI has the same behavior as the row editing one as they are designed to provide a consistent editing experience to end users. Please, refer to the Hierarchical Grid Row Editing topic for more information.

After a new row is added through the row adding UI, its position and/or visibility is determined by the sorting, filtering and grouping state of the IgcHierarchicalGrid. In a IgcHierarchicalGrid that does not have any of these states applied, it appears as the last record. A snackbar is briefly displayed containing a button the end user may use to scroll the IgcHierarchicalGrid to its position if it is not in view.

ALT + + - Enters edit mode for adding a row
ESC exits row adding mode without submitting any changes
TAB move focus from one editable cell in the row to the next and from the right-most editable cell to the CANCEL and DONE buttons. Navigation from DONE button goes to the left-most editable cell within the currently edited row.

Feature Integration

Any row adding operation will stop if the data view of the IgcHierarchicalGrid gets modified. Any changes made by the end user are submitted. Operations that change the data view include but are not limited to sorting, grouping, filtering, paging, etc.
Summaries are updated after the row add operation finishes. The same is valid for the other data view dependant features such as sorting, filtering, etc.
When spawning the UI for the IgcHierarchicalGrid, any child layout currently expanded for a row that the end user clicks the add row button for is collapsed.

Customizing Row Adding Overlay

Customizing Text

Customizing the text of the row adding overlay is possible using the IgcGridBaseDirective.rowAddTextTemplate.

this.grid.rowAddTextTemplate = (ctx: IgcGridEmptyTemplateContext) => {
    return html`Adding Row`;
}

Customizing Buttons

Customizing the buttons of the row editing overlay is possible by using the RowEditActions template.

this.grid.rowEditActionsTemplate = (endRowEdit: IgcGridRowEditActionsTemplateContext) => {
    return html`
        <button @click="${evt => endRowEdit.implicit(false, evt)}">Cancel</button>
        <button @click="${evt => endRowEdit.implicit(true, evt)}">Apply</button>
    `;
}

Styling

The row adding UI comprises the buttons in the ActionStrip editing actions, the editing editors and overlay, as well as the snackbar which allows end users to scroll to the newly added row. To style these components you may refer to these comprehensive guides in their respective topics:

API References

Additional Resources

Hierarchical Grid Editing

Our community is active and always welcoming to new ideas.

Web Components Hierarchical Grid Row Adding