ResourceStore

Base constructor, passes arguments to construct.

A provided function which creates an array of values for the filterParamName to pass any filters to the server upon load.

By default, this creates a JSON string containing the following properties:

   [{
       field         : <theFieldName>
       operator      : May be: `'='`, `'!='`, `'>'`, `'>='`, `'<'`, `'<='`, `'*'`, `'startsWith'`, `'endsWith'`
       value         : The value to compare
       caseSensitive : true for case sensitive comparisons
   }]

A provided function which creates an array of values for the {#config-sortParamName} to pass any sorters to the server upon load.

By default, this creates a JSON string containing the following properties:

   [{
       field     : <theFieldName>
       ascending : true/false
   }]

Add resources to the store.

NOTE: References (events, assignments) on the resources are determined async by a calculation engine. Thus they cannot be directly accessed after using this function.

For example:

const [resource] = resourceStore.add({ id });
// resource.events is not yet available

To guarantee references are set up, wait for calculations for finish:

const [resource] = resourceStore.add({ id });
await resourceStore.project.commitAsync();
// resource.events is available (assuming EventStore is loaded and so on)

Alternatively use addAsync() instead:

const [resource] = await resourceStore.addAsync({ id });
// resource.events is available (assuming EventStore is loaded and so on)

Add resources to the store and triggers calculations directly after. Await this function to have up to date references on the added resources.

const [resource] = await resourceStore.addAsync({ id });
// resource.events is available (assuming EventStore is loaded and so on)

Applies changes from another store to this store. Useful if cloning records in one store to display in a grid in a popup etc. to reflect back changes.

Applies a set of changes (presumable from a backend) expressed as an object matching the format outputted by the changes property: { added : [], modified/updated : [], removed : [] }

added is expected to be an array of raw data objects consumable by the stores model class for records to add to the store (see example snippet below).

modified (or updated for compatibility with Schedulers CrudManager) is expected to have the same format as added, but should always include the id of the record to update.

Records that have been created locally and gets assigned a proper id by the backend are expected to also pass a phantomId field (name of the field is configurable using the phantomIdField arg, more info on phantom ids below), to match it with the current id of a local record (id will contain the new id).

Note that it is also possible to pass this phantomId -> id mapping in the added array. When encountering a record in that array that already exists in the local store, it will be treated the same way as a record in the modified array.

removed is expected to be an array of objects with the { id : xx } shape. Any matches on an id in the store will be removed, those and any non-matches will also be cleared from the change tracking of the store.

If the store has filters in effect when the changeset is applied, the following rules will determine how the filtered values are affected:

• Among added records, only those that match the filter will be included in the filtered set
• Among updated records, those that did not previously match the filter but now do will be added to the filtered set, and those that did match but no longer do will also remain in the filtered set. This means that new records may appear in the filtered set as a result of applyChanges, but records will not disappear until filters are re-applied.

As an example, consider a store with the following initial state and some operations performed on it:

// Load some data
store.data = [
    { id : 1, name : 'Minerva' },
    { id : 2, name : 'Mars' },
    { id : 3, name : 'Jupiter' }
];
// Add a new record. It gets assigned a generated id,
// for example, 'generated56'
store.add({ name : 'Artemis' });
// Remove Jupiter
store.remove(3);

After syncing those operations to a custom backend (however, you chose to solve it in your application), we might get the following response (see "Transforming a response to the correct format" below if your backend responds in another format):

const serverResponse = {
    added : [
        // Added by the backend, will be added locally
        { id : 5, name : 'Demeter' }
    ],

    updated : [
        // Will change the name of Minerva -> Athena
        { id : 1, name : 'Athena' },
        // Will set proper id 4 for Artemis
        { $PhantomId : 'generated56', id : 4 }
    ],

    removed : [
        // Confirmed remove of Jupiter
        { id : 3 },
        // Removed by the backend, Mars will be removed locally
        { id : 2 }
    ]
};

If that response is then passed to this function:

store.applyChangeset(serverResponse);

The result will be the following data in the store:

[
    { id : 1, name : 'Athena' }, // Changed name
    { id : 4, name : 'Artemis' }, // Got a proper id
    { id : 5, name : 'Demeter' } // Added by the backend
]

Phantom ids

When a record is created locally, it is always assigned a generated id. That id is called a phantom id (note that it is assigned to the normal id field). When passing the new record to the backend, the id is sent with it. When the backend inserts the record into the database, it (normally) gets a proper id assigned. That id then needs to be passed back in the response, to update the local record with the correct id. Making sure that future updates match the correct row in the database.

For example, a newly created record should be passed similar to this to the backend (pseudo format, up to the application/backend to decide):

{
    "added" : {
        "id" : "generated79",
        "name" : "Hercules",
        ...
    }
}

For the backend response to be applicable for this function, it should then respond with:

{
    "updated" : {
        {
            "$PhantomId" : "generated79",
            "id" : 465
        }
    }
}

(Or, as stated above, it can also be passed in the "added" array. Whichever suits your backend best).

This function will then change the id of the local record using the phantom id generated79 to 465.

Transforming a response to the correct format

This function optionally accepts a transformFn, a function that will be called with the changes. It is expected to return a changeset in the format described above ({ added : [], updated : [], removed : [] }), which then will be used to apply the changes.

Consider the following "non-standard" (made-up) changeset:

const changes = {
    // Database ids for records previously added locally
    assignedIds : {
        'phantom1' : 10,
        'phantom2' : 15
    },
    // Ids records removed by the backend
    removed : [11, 27],
    // Modified records, keyed by id
    altered : {
        12 : { name : 'Changed' }
    },
    // New records, keyed by id
    inserted : {
        20  : { name : 'New' }
    }
}

Since it does not match the expected format, it has to be transformed:

store.applyChangeset(changes, ({ assignedIds, inserted, altered, removed }) => ({
   // Convert inserted to [{ id : 20, name : 'New' }]
   added : Object.entries(inserted).map(([id, data] => ({ id, ...data }),
   updated : [
       // Convert assignedIds to [{ $PhantomId : 'phantom1', id : 10 }, ...]
      ...Object.entries(assignedIds).map(([phantomId, id])) => ({ $PhantomId : phantomId, id }),
      // Convert altered to [{ id : 12, name : 'Changed' }]
      ...Object.entries(modified).map(([id, data] => ({ id, ...data })
   ],
   // Convert removed to [{ id : 11 }, ...]
   removed : removed.map(id => ({ id }))
}));

The transform function above would output:

{
    added : [
        {  id : 20, name : 'New' }
    ],
    updated : [
        { $PhantomId : 'phantom1', id : 10 },
        { $PhantomId : 'phantom2', id : 15 },
        {  id : 12, name : 'Changed' }
    ],
    removed : [
       { id : 11 },
       { id : 12 }
    ]
}

And that format can then be applied.

Preventing automatic commit of applied changes

By default, the clearChanges parameter is set to true, which automatically commits applied changes to the store. Setting this parameter to false prevents the automatic commit, keeping the store in a dirty state.

For example, the following will apply changes without committing them:

const changes = {
    added : [
        {  id : 20, name : 'New' }
    ],
    updated : [
        { id : 10, name : 'Fiona' },
    ],
    removed : [
       { id : 11 }
    ]
};

// Apply these changes using the applyChangeset method
store.applyChangeset(changes, null, '$PhantomId', false);

Commits changes, per default only returns changes and resets tracking.

Triggers: beforeCommit, commit

Load data from the readUrl. If configured as lazyLoad, this will load 1 chunk of records starting from index 0. If the store has previously been loaded, it will first be cleared of all records and all lazy load cache.

Triggers: beforeLoad, loadStart, beforeRequest, load, exception, afterRequest

Applies a new dataset to the ResourceStore and triggers calculations directly after. Use it to plug externally fetched data into the store.

await resourceStore.loadDataAsync([{ id }]);
// resourceStore.first.events is available

Loads a page of data from the implemented requestData function.

If this store is paged, and is not already at the lastPage then this will load the next page of data.

If this store is paged, and is not already at the first page then this will load the previous page of data.

Removes all records from the store.

Triggers: beforeRemove, removeAll, change

Creates a chained store, a new Store instance that contains a subset of the records from current store. Which records is determined by a filtering function, which is reapplied when data in the base store changes.

// Chain all records
const all = store.chain();

// Or a subset using a filter function
const oldies = store.chain(record => record.age > 50);

If this store is a tree store, then the resulting chained store will be a tree store sharing the same root node, but only child nodes which pass the chainedFilterFn will be considered when iterating the tree through the methods such as traverse or forEach.

Creates a chained tree store, a new Store instance that contains a subset of the records from current store. Which records is determined by a filtering function, which is reapplied when data in the base store changes.

// Chain all nodes
const fullTree = store.chainTree();
// Or a subset
const oldies = store.chainTree(record => record.age > 50);

The resulting chained store will be a tree store with its own root node, under which all children are links to the nodes in this store. This allows for expanding/collapsing and filtering nodes in the chained store without affecting the original store.

Adds an event listener. This method accepts parameters in the following format:

 myObject.addListener({
     thisObj    : this,          // The this reference for the handlers
     eventname2 : 'functionName' // Resolved at invocation time using the thisObj,
     otherevent : {
         fn      : 'handlerFnName',
         once    : true          // Just this handler is auto-removed on fire
     },
     yetanother  : {
         fn      : 'yetAnotherHandler',
         args    : [ currentState1, currentState2 ] // Capture info to be passed to handler
     },
     prio        : 100           // Higher prio listeners are called before lower
 });

When listeners have a thisObj option, they are linked to the lifecycle of that object. When it is destroyed, those listeners are removed.

The config parameter allows supplying options for the listener(s), for available options see BryntumListenerConfig.

A simpler signature may be used when only adding a listener for one event and no extra options (such as once or delay) are required:

myObject.addListener('click', myController.handleClicks, myController);

The args in this simple case are eventName, handler and thisObj

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed. Set the catchEventHandlerExceptions config to true to catch exceptions thrown by this object's event handlers and allow the event to continue processing. The exception will be rethrown on a zero millisecond timeout,

Removes all event listeners that were registered with the passed names.

Returns true if any listener is registered for the specified eventName, or if null, for any event.

Alias for addListener. Adds an event listener. This method accepts parameters in the following format:

 myObject.on({
     thisObj    : this,          // The this reference for the handlers
     eventname2 : 'functionName' // Resolved at invocation time using the thisObj,
     otherevent : {
         fn      : 'handlerFnName',
         once    : true          // Just this handler is auto-removed on fire
     },
     yetanother  : {
         fn      : 'yetAnotherHandler',
         args    : [ currentState1, currentState2 ] // Capture info to be passed to handler
     },
     prio        : 100           // Higher prio listeners are called before lower
 });

When listeners have a thisObj option, they are linked to the lifecycle of that object. When it is destroyed, those listeners are removed.

The config parameter allows supplying options for the listener(s), for available options see BryntumListenerConfig.

A simpler signature may be used when only adding a listener for one event and no extra options (such as once or delay) are required:

myObject.on('click', myController.handleClicks, myController);

The args in this simple case are eventName, handler and thisObj

Relays all events through another object that also implements Events mixin. Adds a prefix to the event name before relaying, for example add -> storeAdd

// Relay all events from store through grid, will make it possible to listen for store events prefixed on grid:
'storeLoad', 'storeChange', 'storeRemoveAll' etc.
store.relayAll(grid, 'store');

grid.on('storeLoad', () => console.log('Store loaded');

Removes an event listener. Same API signature as addListener

Resume event triggering after a call to suspendEvents(). If any triggered events were queued they will be triggered.

Prevents events from being triggered until resumeEvents() is called. Optionally queues events that are triggered while suspended. Multiple calls stack to require matching calls to resumeEvents() before actually resuming.

Triggers an event, calling all registered listeners with the supplied arguments. Returning false from any listener makes function return false.

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed. Set the catchEventHandlerExceptions config to true to catch exceptions thrown by this object's event handlers and allow the event to continue processing. The exception will be rethrown on a zero millisecond timeout,

Shorthand for removeListener

Equivalent to Array.every(). Returns true if every call of the provided function on each record yields a truthy value.

Equivalent to Array.flatMap(). Creates a new array by spreading the results of calling a provided function on every record

Iterates over all available records in store. Omits group header and footer records if this store is grouped. Does not request new records when store is configured with lazyLoad.

Equivalent to Array.map(). Creates a new array with the results of calling a provided function on every record

Equivalent to Array.reduce(). Applies a function against an accumulator and each record (from left to right) to reduce it to a single value.

Base implementation applies configuration.

Subclasses need only implement this if they have to initialize instance specific properties required by the class. Often a construct method is unnecessary. All initialization of incoming configuration properties can be done in a set propName implementation.

Sets configuration options this object with all the properties passed in the parameter object. Timing is taken care of. If the setter of one config is called first, and references the value of another config which has not yet been set, that config will be set just in time, and the new value will be used.

Changes the value of a numeric property of this object smoothly over the specified duration.

Provides a way of calling callbacks which may have been specified as the name of a function and optionally adds scope resolution.

For example, if the callback is specified as a string, then if it is prefixed with 'this.' then the function is resolved in this object. This is useful when configuring listeners at the class level.

If the callback name is prefixed with 'up.' then the ownership hierarchy is queried using the owner property until an object with the named function is present, then the named function is called upon that object.

If a named function is not found, an error is thrown. If the function should be only called when present, and may not be present, add a ? as a suffix.

Experimental helper function, extracts the currently used configs and wraps them as an app, downloading the resulting JS file.

This function is intended to simplify creating test cases for issue reporting on Bryntum's support forum.

Provides a way of locating callbacks which may have been specified as the name of a function and optionally adds scope resolution.

For example, if the callback is specified as a string, then if it is prefixed with 'this.' then the function is resolved in this object. This is useful when configuring listeners at the class level.

If the callback name is prefixed with 'up.' then the ownership hierarchy is queried using the owner property until an object with the named function is present, then the named function is called upon that object.

Creates a model instance, used internally when data is set/added. Override this in a subclass to do your own custom conversion from data to record.

Get the record at the specified index.

Get a locally available record by id. Find the record even if filtered out, part of collapsed group or collapsed node

Resolves an input of record(s) and/or id(s) into an array of records found in this store. Accepts a single record, a single id, or an array mixing both. Entries that don't resolve to a record in this store are silently skipped.

const records = store.getByIds([1, 5, someRecord, 'abc']);

Get a record by internalId.

Counts the number of records in the store. Allows passing an options object to control which records are counted. For example:

store.getCount({ filteredOut : true });
store.getCount({ headersFooters : true, collapsed : true });

Consider the following dataset loaded into a Store:

[
  { id : 1, name : 'Linda', city : 'NY' },
  { id : 2, name : 'Olivia', city : 'NY' },
  { id : 3, name : 'John', city : 'Stockholm' }
]

No grouping or filtering is applied, thus all records are accessible ("visible"). Passing the different options below would yield the following results:

Grouping by city yields the following records in the Store (pseudocode):

store.group('city');

[
  { name : 'Group NY', groupHeader : true, expanded : true },
  { id : 1, name : 'Linda', city : 'NY' },
  { id : 2, name : 'Olivia', city : 'NY' },
  { name : 'Group Stockholm', groupHeader : true },
  { id : 3, name : 'John', city : 'Stockholm', expanded : true }
]

Passing the different options below would yield the following results:

Collapsing the Stockholm group yields the following records in the Store (pseudocode):

store.collapse(store.getAt(3));

[
  { name : 'Group NY', groupHeader : true, expanded : true },
  { id : 1, name : 'Linda', city : 'NY' },
  { id : 2, name : 'Olivia', city : 'NY' },
  { name : 'Group Stockholm', groupHeader : true, expanded : false }
]

Passing the different options below would yield the following results:

Applying a filter further affects the counts (pseudocode):

store.filter('name', 'Linda');

[
  { name : 'Group NY', groupHeader : true, expanded : true },
  { id : 1, name : 'Linda', city : 'NY' }
]

Passing the different options below would yield the following results:

^* Note that also passing filteredOut would include filtered out group headers in the count.

Creates an array of records from this store from the start to the end - 1

Checks if the specified record is contained in the store

Returns the index of the specified record/id, or -1 if not found.

Checks if a record is available, in the sense that it is not filtered out, hidden in a collapsed group or in a collapsed parent node of a tree store.

Returns all resources that have no events assigned during the specified time range.

Finds the first record for which the specified function returns true

Find occurrences of the specified value in the specified field on all locally available records in the store

Finds the first record for which the specified field has the specified value

Searches the Store records using the passed function.

Find all hits matching the specified input.

const store = new Store({
  fields : ['name', 'kind'],
  data : [
    { id : 1, name : 'Batman', kind : 'hero' },
    { id : 2, name : 'Batkid', kind : 'hero' },
    { id : 3, name : 'Joker', kind : 'villain' },
    { id : 4, name : 'Penguin', kind : 'villain' }
  ]
});

store.search('villain'); // [{ index : 2, data : joker-record }, { index : 3, data : penguin-record }]

Returns true if the supplied function returns true for any record in the store

Adds a single filter to the filters collection. By default, filters are reevaluated and a Store change event fired.

If the silent parameter is passed as true, multiple filters can be added without causing data changes.

When the filters are as required, call filter with no parameters to apply the filters to the store.

Add a sorting level (a sorter).

Removes all filters from the store. Filters that are marked as internal will not be removed.

Removes all groupers, turning store grouping off.

Removes all sorters, turning store sorting off.

Filters the store by adding the specified filter(s) to the existing filters collection applied to this Store. If a filter has an id specified, or a property specified, it will search for corresponding filter(s) in the existing filters first and replace it with a new filter. It will not remove other filters applied to the store!

To add a new filter:

// Filter using simple object
store.filter({
    property : 'age',
    operator : '>',
    value    : 90
});

// Filter using function
store.filter(r => r.age < 90);

// Filter using a named filter as a function
store.filter({
    id : 'my-filter',
    filterBy : record => record.score > 10
});

To remove a specific filter, but keep other filters applied

// Remove by filter `id` or `property`. Filter `id` defaults to the `property-operator` value.
store.removeFilter('age');
store.removeFilter('my-filter');

To replace all existing filters with a new filter

// Remove all filters and filter using simple object
store.filter({
    filters : {
        property : 'age',
        operator : '<',
        value    : 90
    },
    replace : true
});

// Remove all filters and filter using function
store.filter({
    filters : r => r.age > 90,
    replace : true
});

// Remove all filters and filter using a named filter as a function
store.filter({
    filters : {
        id : 'my-filter',
        filterBy : record => record.score > 10
    },
    replace : true
});

Basically filters replacing is an equivalent of having two sequenced calls: clearFilters and filter.

Call without arguments to reapply filters.

// Re-filter the store
store.filter();

Triggers: filter, change

Adds a function used to filter the store. Alias for calling filter(fn). Return true from the function to include record in filtered set

store.filterBy(record => record.age > 25 && record.name.startsWith('A'));

Returns all records in the group with specified groupValue.

Get all group titles.

Group records, either by replacing current sorters or by adding to them. A grouper can specify a custom sorting function which will be called with arguments (recordA, recordB). Works in the same way as a standard array sorter, except that returning null triggers the stores normal sorting routine. Grouped store must always be sorted by the same field.

To clear groupers and stop grouping, use clearGroupers method.

// simple grouper
store.group('city');

// grouper as object, descending order
store.group({ field : 'city', ascending : false });

// using custom sorting function
store.group({
    field : 'city',
    fn : (recordA, recordB) => {
        // apply custom logic, for example:
        return recordA.city.length < recordB.city.length ? -1 : 1;
    }
});

// Stop grouping
store.clearGroupers();

Triggers: group, refresh

Check if a record belongs to a certain group (only for the first grouping level)

Removes the passed filter, or the filter by the passed ID from the filters collection. By default, filters are reevaluated and a Store change event fired.

If the silent parameter is passed as true, multiple filters can be removed without causing data changes.

When the filters are as required, call filter with no parameters to apply the filters to the store.

// Only view top priority events
myEventStore.filter({
    id       : 'priorityFilter',
    property : 'priority',
    value    : 1,
    operator : '='
});

// That individual filter can be removed like this
myEventStore.removeFilter('priorityFilter');

// Add named filter as a function
store.filter({
    id : 'my filter',
    filterBy : record => record.score > 10
});

// Remove named filter function
store.removeFilter('my filter');

Remove a sorting level (a sorter)

Set groupers.

Sort records, either by replacing current sorters or by adding to them. A sorter can specify a custom sorting function which will be called with arguments (recordA, recordB). Works in the same way as a standard array sorter, except that returning null triggers the stores normal sorting routine.

// single sorter
store.sort('age');

// single sorter as object, descending order
store.sort({ field : 'age', ascending : false });

// multiple sorters
store.sort(['age', 'name']);

// using custom sorting function
store.sort((recordA, recordB) => {
    // apply custom logic, for example:
    return recordA.name.length < recordB.name.length ? -1 : 1;
});

// using locale specific sort (slow)
store.sort({ field : 'name', useLocaleSort : 'sv-SE' });

Triggers: beforeSort, sort, refresh

Stops this store from firing events until endBatch is called. Multiple calls to beginBatch stack up, and will require an equal number of endBatch calls to resume events.

Upon call of endBatch, a refresh event is triggered to allow UIs to update themselves based upon the new state of the store.

This is extremely useful when making a large number of changes to a store. It is important not to trigger too many UI updates for performance reasons. Batching the changes ensures that UIs attached to this store are only updated once at the end of the updates.

Ends event suspension started by beginBatch. Multiple calls to beginBatch stack up, and will require an equal number of endBatch calls to resume events.

Upon call of endBatch, a refresh event with action: batch is triggered to allow UIs to update themselves based upon the new state of the store.

This is extremely useful when making a large number of changes to a store. It is important not to trigger too many UI updates for performance reasons. Batching the changes ensures that UIs attached to this store are only updated once at the end of the updates.

Retrieve the data of all (unfiltered) records as an array of JSON objects.

const store = new Store({
    data : [
        { id : 1, name : 'Superman' },
        { id : 2, name : 'Batman' }
    ]
});

const jsonArray = store.toJSON();

//jsonArray:
[{id:1,name:"Superman"},{id:2,name:"Batman"}]

Returns the average value for the specified field. Defaults to look through all locally available records in store

Returns sum by adding value of specified field for records in the group with the specified groupValue.

Returns max value for the specified field, can be used with Date or Number values. Defaults to look through all locally available records in store

Returns min value for the specified field, can be used with Date or Number values. Defaults to look through all locally available records in store

Returns sum calculated by adding value of specified field for specified records. Defaults to using all locally available records in store

Finds the next record locally available.

Finds the previous record locally available.

Traverse all tree nodes (only applicable for Tree Store)

Traverse all tree nodes while the passed fn returns true

Returns the children of the passed branch node which this store owns. By default, this is the entire children array.

If this store isChained, then this returns only the subset of children which are filtered into this store by the chainedFilterFn.

Increase the indentation level of one or more nodes in the tree

Triggers: indent, change

Loads children for a parent node that uses load on demand (when expanding it). Base implementation does nothing, either use AjaxStore which implements it, create your own subclass with an implementation or listen for toggleNode and insert records when you have them available.

Decrease the indentation level of one or more nodes in the tree

Triggers: outdent, change

Collapse an expanded record or expand a collapsed. Optionally forcing a certain state.

Returns an array of distinct values from all locally available records for the specified field.

store.getDistinctValues('age'); // Returns an array of the unique age values

Counts how many times the specified value appears locally in the store