BaseViewModelCollection class

Level: advanced

note

This functionality is available for Creatio 8.3.2 and later.

The BaseViewModelCollection class stores a collection of related view model items and supports CRUD operations. It provides array-like behavior and extended API for managing collection elements.

Since version 8.3.2, the BaseViewModelCollection class provides a dedicated API for granular collection change events. The API supports event handling for collection-level updates as well as item additions, removals, index shifts, and per-item attribute changes, eliminating the need for manual snapshots and comparisons. Learn more: Track changes in collection data.

Methods

public registerOnCollectionChangeCallback(
    callback: (changes: ViewModelCollectionChange<ViewModel>) => void,
    action?: ViewModelCollectionActionType
): void

Registers a callback function that is invoked when the collection changes. Throws an Error if an unsupported action type is provided.

Parameters

Parameter	Type	Required	Description
callback	(changes: ViewModelCollectionChange<ViewModel>) => void	Yes	Callback function invoked on collection changes.
action	ViewModelCollectionActionType	No	Register the callback for a specific collection change action. Specify the action parameter to receive only for certain change types. If omitted, the callback is invoked for all collection change actions. Learn more about the ViewModelCollectionActionType enumeration: ViewModelCollectionActionType.

Usage examples

View the example that listens for all collection changes below.

Listen for all collection changes

collection.registerOnCollectionChangeCallback((changes) => {
    console.log("Collection changed: ", changes.action);
    console.log("Affected items: ", changes.affectedElements.length);
});

View the example that listens for item additions to the collection below.

Listen for changes of a specific type

collection.registerOnCollectionChangeCallback(
    (changes) => {
        console.log("Item added at index: ", changes.index);
    },
    ViewModelCollectionActionType.Add
);

---

public registerOnItemAttributesChangesCallback(
    callback: (item: ViewModel) => void
): void

Registers a callback function that is invoked when any attribute of any item in the collection changes. Only non-silent item attribute changes trigger the callback. Silent changes are internal updates that do not trigger UI refresh.

Parameters

Parameter	Type	Required	Description
callback	(item: ViewModel) => void	Yes	Callback function to be invoked when item attribute changes occur.

Usage example

View the example that listens for item attribute changes in the collection below.

Listen for item attribute changes in the collection

collection.registerOnItemAttributesChangesCallback((item) => {
    console.log("Item attributes changed:", item.primaryAttributeName);
    /* Implement validation or refresh the UI. */
});

---

public unregisterOnCollectionChangeCallback(
    callback: (changes: ViewModelCollectionChange<ViewModel>) => void,
    action?: ViewModelCollectionActionType
): void

Removes a previously registered callback function that is invoked when the collection changes. Anonymous functions cannot be unregistered unless you store a reference to them. Throws an Error if the specified callback is not registered.

Important

Pass the exact same function reference that was used during registration.

Parameters

Parameter	Type	Required	Description
callback	(changes: ViewModelCollectionChange<ViewModel>) => void	Yes	The exact callback function reference to unregister.
action	ViewModelCollectionActionType	No	Unregister the callback for a specific collection change action. Specify the action parameter to stop listening only for certain change types. If omitted, the callback is removed for all collection change actions. Learn more about the ViewModelCollectionActionType enumeration: ViewModelCollectionActionType.

Usage example

View the example that registers and unregisters a collection change callback below.

Register and unregister a collection change callback

const callback = (changes) => {
    console.log("Collection changed");
};

/* Register the callback for all action types. */
collection.registerOnCollectionChangeCallback(callback);

/* Unregister the callback for "Add" action type only. */
collection.unregisterOnCollectionChangeCallback(
    callback,
    ViewModelCollectionActionType.Add
);

/* Unregister the callback for all action types. */
collection.unregisterOnCollectionChangeCallback(myCallback);

---

public unregisterOnItemAttributesChangesCallback(
    callback: (item: ViewModel) => void
): void

Removes a previously registered callback function that is invoked when item attributes change. Anonymous functions cannot be unregistered unless you store a reference to them. Throws an Error if the specified callback is not registered.

Parameters

Parameter	Type	Required	Description
callback	(item: ViewModel) => void	Yes	The exact callback function reference to unregister.

Usage example

View the example that registers and unregisters an item attribute change callback below.

Register and unregister an item attribute change callback

const attributeChangeHandler = (item) => {
    console.log("Attributes changed on item:", item);
};

/* Register the callback. */
collection.registerOnItemAttributesChangesCallback(attributeChangeHandler);

/* Unregister the callback. */
collection.unregisterOnItemAttributesChangesCallback(attributeChangeHandler);

---

Types

ViewModelCollectionChange<T>

Represents information about a change in the collection.

Properties

Property	Type	Description
collection	T[]	Current state of the collection.
affectedElements	T[]	Items affected by the change.
action	ViewModelCollectionActionType	Type of performed action. Learn more about the ViewModelCollectionActionType enumeration: ViewModelCollectionActionType.
index?	number	Index where the change occurred, if applicable.

---

ViewModelCollectionActionType

Specifies the collection change action type.

Available values

Add	Item addition.
Remove	Item removal.
Move	Item movement within the collection.
Reload	Collection reload with new items.

---

See also

Track changes in collection data