Editing Views with ColectionView

The CollectionView provides support for editing items with methods similar to those found in .NET's IEditableCollectionView interface: editItem, commitEdit, and cancelEdit.

• The editItem method saves a copy of the item and puts the collection in 'edit mode'. While in edit mode, the view is not refreshed, so items will not be sorted or filtered out of view during the edit process.

• The commitEdit method exits edit mode so sorting and filtering become active again. If the item has changed, the collectionChanged event fires so bound controls can show the changes.

• The cancelEdit method restores the original data and exits edit mode.

Editing behavior

When editing starts, a pencil icon appears on the row header to indicate the collection is in edit mode.

If you press the 'Escape' key while in edit mode, the edits will be canceled and the original data will be restored.

If you move the selection to a different row, or move the focus away from the grid, the edits WILL be committed! At this point, the collection will refresh and any active filtering/sorting will be applied using the new item values.

Adding Items

The CollectionView provides support for adding items with the methods addNew, commitNew, and cancelNew. Removing items is done with the remove method.

The addNew method adds an empty item to the collection and returns a reference to the new item. The caller can use this return value to initialize the new item. Alternatively, you can provide a CollectionView.newItemCreator function to create and initialize new items.

The addNew method also puts the collection in 'add' mode, suspending sorting and filtering to keep the new item in place until it is committed.

The commitNew method causes the collection to exit 'add mode' and refreshes the collection so sorting and filtering are restored.

The cancelNew method removes the new item from the collection and exits 'add mode'.

To add an item, you must first enable the grid to add new items. Set the allowAddNew property to true. Then move the selection to the last row, the "New Item Template" (it has an asterisk on the row header). It looks like this:

Edit the new item as usual, and when you are done press Enter or move the selection to a different row to commit the new row.

If you press the 'Escape' key while editing the new row, the addition will be canceled and the new row will be removed from the collection.

Removing Items

To remove items, select an entire row by clicking the row header, then press the Delete key. The grid will call the collection's remove method and the item will be removed from the collection.

Tracking Changes

Web applications often use a pattern of downloading some data from the server, making changes locally, and updating the server with the changes later.

The CollectionView can help by keeping track of items that have been added, removed, or modified.

To use this feature, set the trackChanges property to true. Once you do that, the CollectionView will add items to these collections:

• itemsAdded
• itemsRemoved
• itemsEdited

When you are ready, send the changes to the server and call the clearChanges method to reset the change-tracking collections.

Check out the Tracking Changes Demo

Validation

The CollectionView has a getError property that provides validation support. To use it, set getError to a function that takes two parameters containing the data item being validated and the property to validate, and returns a string describing the error condition (or null if there are no errors),

import * as wijmo from '@grapecity/wijmo';

let view = new wijmo.CollectionView();

// only accept gmail email addresses.
view.getError = (item, property) => {
    if ( property == "email" && item.endsWith('@gmail.com') ) {
        return null;
    }
    else {
        return 'Invalid email. Please enter a gmail address';
    }
}

The getError property goes beyond basic HTML5 validation based only on the value itself (such as min, max, required, pattern, etc). It allows you to specify conditions that involve multiple properties.

The getError property allows you to include the validation logic in the collection itself, rather than in the UI used for editing items. The same method can then be used by input forms or by controls such as the FlexGrid.