AbstractCrudManagerMixin
Mixin

Abstract

An abstract mixin that supplies most of the CrudManager functionality. It implements basic mechanisms of collecting stores to organize batch communication with a server. It does not contain methods related to data transfer nor encoding. These methods are to be provided in sub-classes. Out of the box there are mixins implementing support of AJAX for data transferring and JSON for data encoding system. For example this is how we make a model that will implement CrudManager protocol and use AJAX/JSON to pass the data to the server:

class SystemSettings extends JsonEncode(AjaxTransport(AbstractCrudManagerMixin(Model))) {
    ...
}

Data transfer and encoding methods

These are methods that must be provided by subclasses of this class:

No results

Configs

Configs are options you supply in a configuration object when creating an instance of this class

loadUrl : String
Convenience shortcut to set only the url to load from, when you do not need to supply any other config options in the load section of the transport config.

Using loadUrl:
```
{
    loadUrl : 'read.php
}
```
Equals the following transport config:
```
{
    transport : {
        load : {
            url : 'read.php'
        }
    }
}
```
When read at runtime, it will return the value from transport.load.url.

Has a corresponding runtime loadUrl property.
syncUrl : String
Convenience shortcut to set only the url to sync to, when you do not need to supply any other config options in the sync section of the transport config.

Using loadUrl:
```
{
    syncUrl : 'sync.php
}
```
Equals the following transport config:
```
{
    transport : {
        load : {
            url : 'sync.php'
        }
    }
}
```
When read at runtime, it will return the value from transport.sync.url.

Has a corresponding runtime syncUrl property.
syncConflictResolution : 'local'/'remote'local

internal
Specifies the way to handle conflicts happening when applying sync responses to served stores, The conflicts could happen when remote coming changes interfere with local changes made after sending the request.

Supported values are:
- local local modifications are preserved and corresponding remote changes get rejected
- remote remote changes gets applied overriding the local modifications.
autoLoad : Booleanfalse

Specify true to automatically call load method on the next frame after creation.

Called on the next frame to allow a Scheduler (or similar) linked to a standalone CrudManager to register its stores before loading starts.
autoSync : Booleanfalse

true to automatically persist store changes after edits are made in any of the stores monitored. Please note that sync request will not be invoked immediately but only after autoSyncTimeout interval.
autoSyncTimeout : Number100

The timeout in milliseconds to wait before persisting changes to the server. Used when autoSync is set to true.
crudStores : Store[]/String[]/CrudManagerStoreDescriptor[]/StoreConfig

Sets the list of stores controlled by the CRUD manager.

When adding a store to the CrudManager, make sure the server response format is correct for load and sync requests. Learn more in the Working with data guide.

Store can be provided by itself, its id or as a store descriptor.

Has a corresponding runtime crudStores property.
forceSync : Boolean

Specify as true to force sync requests to be sent when calling sync(), even if there are no local changes. Useful in a polling scenario, to keep client up to date with the backend.

Has a corresponding runtime forceSync property.
ignoreRemoteChangesInSTM : Boolean

Set to true to make STM ignore changes coming from the backend. This will allow user to only undo redo local changes.

Has a corresponding runtime ignoreRemoteChangesInSTM property.
includeChildrenInRemoveRequest : Booleantrue
Set to false to only include the id of a removed parent node in the request to the backend (also affects programmatic calls to get changes etc.), and not the ids of its children.

Consider the following scenario, removing parent 1:
```
{
  id : 1,
  children : [
    { id : 11 },
    { id : 12 }
  ]
}
```
With includeChildrenInRemoveRequest : false, the backend will only receive the removal of id 1.

With includeChildrenInRemoveRequest : true (the default), the backend will receive the removal of id 1, 11 and 12.
phantomIdField : String$PhantomId

Field name to be used to transfer a phantom record identifier.
phantomParentIdField : String$PhantomParentId

Field name to be used to transfer a phantom parent record identifier.
resetIdsBeforeSync : Booleantrue

True to reset identifiers (defined by idField config) of phantom records before submitting them to the server.

storeIdProperty : String

Name of a store property to retrieve store identifiers from. Make sure you have an instance of a store to use it by id. Store identifier is used as a container name holding corresponding store data while transferring them to/from the server. By default, id property is used. And in case a container identifier has to differ this config can be used:

class CatStore extends Store {
    static configurable = {
        // store id is "meow" but for sending/receiving store data
        // we want to have "cats" container in JSON, so we create a new property "storeIdForCrud"
        id             : 'meow',
        storeIdForCrud : 'cats'
    }
});

// create an instance to use a store by id
new CatStore();

class MyCrudManager extends CrudManager {
    ...
    crudStores           : ['meow'],
    // crud manager will get store identifier from "storeIdForCrud" property
    storeIdProperty  : 'storeIdForCrud'
});

The storeIdProperty property can also be specified directly on a store:

class CatStore extends Store {
    static configurable = {
        // storeId is "meow" but for sending/receiving store data
        // we want to have "cats" container in JSON
        id              : 'meow',
        // so we create a new property "storeIdForCrud"..
        storeIdForCrud  : 'cats',
        // and point CrudManager to use it as the store identifier source
        storeIdProperty  : 'storeIdForCrud'
    }
});

class DogStore extends Store {
    static configurable = {
        // storeId is "dogs" and it will be used as a container name for the store data
        storeId : 'dogs',
        // id is set to get a store by identifier
        id      : 'dogs'
    }
});

// create an instance to use a store by id
new CatStore();
new DogStore();

class MyCrudManager extends CrudManager {
    ...
    crudStores : ['meow', 'dogs']
});

supportShortSyncResponse : Booleantrue

When true the Crud Manager does not require all updated and removed records to be mentioned in the sync response. In this case response should include only server side changes.

Please note that added records should still be mentioned in response to provide real identifier instead of the phantom one.
syncApplySequence : String[]
An array of store identifiers sets an alternative sync responses apply order. By default, the order in which sync responses are applied to the stores is the same as they registered in. But in case of some tricky dependencies between stores this order can be changed:
```
class MyCrudManager extends CrudManager {
    // register stores (will be loaded in this order: 'store1' then 'store2' and finally 'store3')
    crudStores : ['store1', 'store2', 'store3'],
    // but we apply changes from server to them in an opposite order
    syncApplySequence : ['store3', 'store2', 'store1']
});
```
Has a corresponding runtime syncApplySequence property.
trackResponseType : Booleanfalse

When true forces the CRUD manager to process responses depending on their type attribute. So load request may be responded with sync response for example. Can be used for smart server logic allowing the server to decide when it's better to respond with a complete data set (load response) or it's enough to return just a delta (sync response).
writeAllFields : Booleanfalse

true to write all fields from the record to the server. If set to false it will only send the fields that were modified. Note that any fields that have persist set to false will still be ignored and fields having alwaysWrite set to true will always be included.

Properties

Properties are getters/setters or publicly accessible variables on this class

isAbstractCrudManagerMixin : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of AbstractCrudManagerMixin class, or subclass thereof.

loadUrl : String
Convenience shortcut to set only the url to load from, when you do not need to supply any other config options in the load section of the transport config.

Using loadUrl:
```
{
    loadUrl : 'read.php
}
```
Equals the following transport config:
```
{
    transport : {
        load : {
            url : 'read.php'
        }
    }
}
```
When read at runtime, it will return the value from transport.load.url.

Has a corresponding loadUrl config.
syncUrl : String
Convenience shortcut to set only the url to sync to, when you do not need to supply any other config options in the sync section of the transport config.

Using loadUrl:
```
{
    syncUrl : 'sync.php
}
```
Equals the following transport config:
```
{
    transport : {
        load : {
            url : 'sync.php'
        }
    }
}
```
When read at runtime, it will return the value from transport.sync.url.

Has a corresponding syncUrl config.
crudStoresJSON : Object

internal

Returns the data from all CrudManager crudStores in a format that can be consumed by inlineData.

changes : Object

READONLY

Returns current changes as an object consisting of added/modified/removed arrays of records for every managed store, keyed by each store's id. Returns null if no changes exist. Format:

{
    resources : {
        added    : [{ name : 'New guy' }],
        modified : [{ id : 2, name : 'Mike' }],
        removed  : [{ id : 3 }]
    },
    events : {
        modified : [{  id : 12, name : 'Cool task' }]
    },
    ...
}

crudRevision : Number

READONLY

The server revision stamp. The revision stamp is a number which should be incremented after each server-side change. This property reflects the current version of the data retrieved from the server and gets updated after each load and sync call.
crudStores : CrudManagerStoreDescriptor[]

A list of registered stores whose server communication will be collected into a single batch. Each store is represented by a store descriptor.

Has a corresponding crudStores config.
forceSync : Boolean

Specify as true to force sync requests to be sent when calling sync(), even if there are no local changes. Useful in a polling scenario, to keep client up to date with the backend.

Has a corresponding forceSync config.
ignoreRemoteChangesInSTM : Boolean

Set to true to make STM ignore changes coming from the backend. This will allow user to only undo redo local changes.

Has a corresponding ignoreRemoteChangesInSTM config.
isChangeTrackingSuspended : Boolean

READONLY

Returns true if changes tracking is suspended
isCrudManagerLoading : Boolean

READONLY

Returns true if the crud manager is currently loading data
isCrudManagerSyncing : Boolean

READONLY

Returns true if the crud manager is currently syncing data
requestId : Number

internal

READONLY

Generates unique request identifier.
syncApplySequence : CrudManagerStoreDescriptor[]

An array of stores presenting an alternative sync responses apply order. Each store is represented by a store descriptor.

Has a corresponding syncApplySequence config.
isAbstractCrudManagerMixin : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of AbstractCrudManagerMixin class, or subclass thereof.

Functions

Functions are methods available for calling on the class

cancelRequest( promise, reject )

Cancels request to the server.
decode( response )
: Object

Decodes response from the server.
encode( request )
: String

Encodes request to the server.
sendRequest( request )
: Promise

ASYNC

Sends request to the server.
acceptChanges( )
Accepts all changes in all stores, resets the modification tracking:
- Clears change tracking for all records
- Clears added
- Clears modified
- Clears removed Leaves the store in an "unmodified" state.
addCrudStore( store, position, fromStore )
Adds a store to the collection.
```
// append stores to the end of collection
crudManager.addCrudStore([
    store1,
    // storeId
    'bar',
    // store descriptor
    {
        storeId : 'foo',
        store   : store3
    },
    {
        storeId         : 'bar',
        store           : store4,
        // to write all fields of modified records
        writeAllFields  : true
    }
]);
```
Note: Order in which stores are kept in the collection is very essential sometimes. Exactly in this order the loaded data will be put into each store.

When adding a store to the CrudManager, make sure the server response format is correct for load and sync requests. Learn more in the Working with data guide.
addStoreToApplySequence( store, position, fromStore )
Adds a store to the alternative sync responses apply sequence. By default, the order in which sync responses are applied to the stores is the same as they registered in. But this order can be changes either on construction step using syncApplySequence option or by calling this method.

Please note, that if the sequence was not initialized before this method call then you will have to do it yourself like this for example:
```
// alternative sequence was not set for this crud manager
// so let's fill it with existing stores keeping the same order
crudManager.addStoreToApplySequence(crudManager.crudStores);

// and now we can add our new store

// we will load its data last
crudManager.addCrudStore(someNewStore);
// but changes to it will be applied first
crudManager.addStoreToApplySequence(someNewStore, 0);
```
add registered stores to the sequence along with the store(s) you want to add
applyChangeset( changes, transformFn, phantomIdField$PhantomId, clearChangestrue )
Applies a set of changes, as an object keyed by store id, to the affected stores. This function is intended to use in apps that handle their own data syncing, it is not needed when using the CrudManager approach.

Example of a changeset:
```
project.applyChangeset({
    events : {
        added : [
            { id : 10, name : 'Event 10', startDate : '2022-06-07' }
        ],
        updated : [
            { id : 5, name : 'Changed' }
        ],
        removed : [
            { id : 1 }
        ]
    },
    resources : { ... },
    ...
});
```
Optionally accepts a transformFn to convert an incoming changeset to the expected format. See applyChangeset for more details.

Setting clearChanges param to false will result in restoring the changes on the store applied using the applyChangeset method. By default, it has been set to true to clear all the applied changes on the store.

For example, following will restore the changes on the store:
```
// Apply these changes using the applyChangeset method
project.applyChangeset({
    events : {
        added : [
            { id : 10, name : 'Event 10', startDate : '2022-06-07' }
        ],
        updated : [
            { id : 5, name : 'Changed' }
        ],
        removed : [
            { id : 1 }
        ]
    },
    resources : { ... },
    ...
}, null, '$PhantomId', false);
```
In SchedulerPro and Gantt, when autoSync is enabled, and client wants to apply changes without triggering a sync request, applyProjectChanges method should be used instead of this. It helps maintain current behavior while providing flexibility for scenarios where syncing is not required.

crudStoreHasChanges( storeId )

: Boolean

Returns true if any of registered stores (or some particular store) has non persisted changes.

// if we have any unsaved changes
if (crudManager.crudStoreHasChanges()) {
    // persist them
    crudManager.sync();
// otherwise
} else {
    alert("There are no unsaved changes...");
}

doDestroy( )

internal

Removes all stores and cancels active requests.
getCrudStore( storeId )
: Store

Returns a registered store.
getStoreDescriptor( storeId )
: CrudManagerStoreDescriptor

Returns a registered store descriptor.

load( options )

: Promise

ASYNC

Loads data to the stores registered in the crud manager. For example:

crudManager.load(
    // here are request parameters
    {
        store1 : { append : true, page : 3, smth : 'foo' },
        store2 : { page : 2, bar : '!!!' }
    }
).then(
    () => alert('OMG! It works!'),
    ({ response, cancelled }) => console.log(`Error: ${cancelled ? 'Cancelled' : response.message}`)
);

** Note: ** If there is an incomplete load request in progress then system will try to cancel it by calling cancelRequest.

loadCrudManagerData( response, options )
: Promise

ASYNC

Loads data to the Crud Manager
removeCrudStore( store )
Removes a store from collection. If the store was registered in alternative sync sequence list it will be removed from there as well.
```
// remove store having storeId equal to "foo"
crudManager.removeCrudStore("foo");

// remove store3
crudManager.removeCrudStore(store3);
```

removeStoreFromApplySequence( store )

Removes a store from the alternative sync sequence.

// remove store having storeId equal to "foo"
crudManager.removeStoreFromApplySequence("foo");

resumeAutoSync( doSynctrue )

Resumes automatic sync upon store changes. Will schedule a sync if the internal counter is 0.
resumeChangeTracking( skipChangeCheck )

Resumes hasChanges and noChanges events. By default, it will check for changes and if there are any, hasChanges or noChanges event will be triggered.
revertChanges( )

Reverts all changes in all stores and re-inserts any records that were removed locally. Any new uncommitted records will be removed.
suspendAutoSync( )

Suspends automatic sync upon store changes. Can be called multiple times (it uses an internal counter).
suspendChangeTracking( )

Suspends hasChanges and noChanges events.
sync( )
: Promise

ASYNC
Persists changes made on the registered stores to the server and/or receives changes made on the backend. Usage:
```
// persist and run a callback on request completion
crud.sync().then(
    () => console.log("Changes saved..."),
    ({ response, cancelled }) => console.log(`Error: ${cancelled ? 'Cancelled' : response.message}`)
);
```
** Note: ** If there is an incomplete sync request in progress then system will queue the call and delay it until previous request completion. In this case syncDelayed event will be fired.

** Note: ** Please take a look at autoSync config. This option allows persisting changes automatically after any data modification.

** Note: ** By default a sync request is only sent if there are any local changes. To always send a request when calling this function, configure forceSync as true.

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

beforeLoad

PREVENTABLE

Fires before load request is sent. Return false to cancel load request.
beforeLoadApply

PREVENTABLE

Fires before loaded data get applied to the stores. Return false to prevent data applying. This event can be used for server data preprocessing. To achieve it user can modify the response object.
beforeResponseApply

PREVENTABLE

Fires before server response gets applied to the stores. Return false to prevent data applying. This event can be used for server data preprocessing. To achieve it user can modify the response object.

beforeSync

ASYNC

PREVENTABLE

Fires before sync request is sent. Return false to cancel sync request.

crudManager.on('beforesync', function() {
    // cannot persist changes before at least one record is added
    // to the `someStore` store
    if (!someStore.getCount()) return false;
});

beforeSyncApply

PREVENTABLE

Fires before sync response data get applied to the stores. Return false to prevent data applying. This event can be used for server data preprocessing. To achieve it user can modify the response object.

hasChanges

Fires when data in any of the registered data stores is changed.

    crudManager.on('hasChanges', function (crud) {
        // enable persist changes button when some store gets changed
        saveButton.enable();
    });

You can suspend this event with suspendChangeTracking API call.

load

Fires on successful load request completion after data gets loaded to the stores.
loadCanceled

Fired after load request was canceled by some beforeLoad listener or due to incomplete prior load request.
loadFail

Fires when a load request fails.
noChanges
Fires when registered stores get into state when they don't have any not persisted change. This happens after load or sync request completion. Or this may happen after a record update which turns its fields back to their original state.
```
crudManager.on('nochanges', function (crud) {
    // disable persist changes button when there is no changes
    saveButton.disable();
});
```
You can suspend this event with suspendChangeTracking API call.
requestDone

Fires on successful request completion after data gets applied to the stores.
requestFail

Fires when a request fails.
sync

Fires on successful sync request completion.
syncCanceled

Fires after sync request was canceled by some beforeSync listener.
syncDelayed

Fires after sync request was delayed due to incomplete previous one.
syncFail

Fires when a sync request fails.

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onBeforeLoad

PREVENTABLE

Called before load request is sent. Return false to cancel load request.
onBeforeLoadApply

PREVENTABLE

Called before loaded data get applied to the stores. Return false to prevent data applying. This event can be used for server data preprocessing. To achieve it user can modify the response object.
onBeforeResponseApply

PREVENTABLE

Called before server response gets applied to the stores. Return false to prevent data applying. This event can be used for server data preprocessing. To achieve it user can modify the response object.

onBeforeSync

ASYNC

PREVENTABLE

Called before sync request is sent. Return false to cancel sync request.

crudManager.on('beforesync', function() {
    // cannot persist changes before at least one record is added
    // to the `someStore` store
    if (!someStore.getCount()) return false;
});

onBeforeSyncApply

PREVENTABLE

Called before sync response data get applied to the stores. Return false to prevent data applying. This event can be used for server data preprocessing. To achieve it user can modify the response object.

onHasChanges

Called when data in any of the registered data stores is changed.

    crudManager.on('hasChanges', function (crud) {
        // enable persist changes button when some store gets changed
        saveButton.enable();
    });

You can suspend this event with suspendChangeTracking API call.

onLoad

Called on successful load request completion after data gets loaded to the stores.
onLoadCanceled

Called after load request was canceled by some beforeLoad listener or due to incomplete prior load request.
onLoadFail

Called when a load request fails.
onNoChanges
Called when registered stores get into state when they don't have any not persisted change. This happens after load or sync request completion. Or this may happen after a record update which turns its fields back to their original state.
```
crudManager.on('nochanges', function (crud) {
    // disable persist changes button when there is no changes
    saveButton.disable();
});
```
You can suspend this event with suspendChangeTracking API call.
onRequestDone

Called on successful request completion after data gets applied to the stores.
onRequestFail

Called when a request fails.
onSync

Called on successful sync request completion.
onSyncCanceled

Called after sync request was canceled by some beforeSync listener.
onSyncDelayed

Called after sync request was delayed due to incomplete previous one.
onSyncFail

Called when a sync request fails.

AbstractCrudManagerMixin
Mixin

Abstract

Data transfer and encoding methods

Configs

Properties

Functions

Events

Event handlers

Source path

Inheritance tree1

Mixins3

Contents

AbstractCrudManagerMixin Mixin Abstract

Data transfer and encoding methods

Configs

Properties

Functions

Events

Event handlers

Source path

Inheritance tree1

Mixins3

Contents

AbstractCrudManagerMixin
Mixin

Abstract