v7.3.0

Using a Store

This guide shows how to manage records in a Store, for example how to retrieve records and how to sort or filter the store. It applies to all stores used by the TaskBoard. Before reading this guide, please read the basic guides on how to work with tasks and how to assign resources:

Store example

The store outlined in code below is referred to in the examples ahead in this guide:

const store = new ResourceStore({
    data : [
        { id : 1, name : 'Ms. Marvel', powers : 'Shapeshifting' },
        { id : 2, name : 'Black Widow', powers : 'Martial arts' },
        { id : 3, name : 'Captain Marvel', powers : 'Flight, Energy projection' },
        { id : 4, name : 'X-23', powers : 'Regeneration' },
        { id : 5, name : 'Mockingbird', powers : 'Martial arts' }       
    ]
});

Retrieving records

A Store can be seen as a collection of records with functionality to manage them. To retrieve a record, it is easiest to do it using its index or id:

store.getAt(1); // Black Widow
store.getById(3); // Captain Marvel

There are also shortcuts to get the first or last record:

store.first; // Ms. Marvel
store.last; // Mockingbird

Because stores are iteratables, you can also use destructuring assignments:

// Ms. Marvel, Black Widow, Captain Marvel
const [ first, second, third ] = store;

You can search for a single record:

store.find(record => record.name.startsWith('M')); // Ms. Marvel
store.findRecord('name', 'X-23'); // X-23, surprise

Or query for multiple:

store.query(record => record.name.startsWith('M')); // [Ms. Marvel, Mockingbird]

Sorting

A Store can be sorted by a single field or by multiple fields. Sort can be specified at creation time using stores config:

const store = new Store({
    sorters : [
        { field : 'powers' }, // ascending
        { field : 'name', ascending: false } // descending
    ]
});

After creation it can be sorted as shown below: 

resourceStore.sort('name'); // Sort by name, ascending first time, toggles on additional calls
resourceStore.sort('name', false); // Sort by name, descending

resourceStore.addSorter('powers'); // Also sort by powers
resourceStore.removeSorter('powers'); // Stop sorting by powers

Filtering

Filtering makes the store expose a subset of its records. When iterating or querying the store only this subset will be used (by default). Examples on filtering:

resourceStore.filter('powers', 'Martial arts'); // Black Widow, Mockingbird

resourceStore.filter({
    property : 'id',
    operatior : '<',
    value : 4
}); // Ms. Marvel, Black Widow, Captain Marvel

resourceStore.removeAllFilters(); // Remove filters

Iterating over records

The records in the store can be iterated over in a couple of ways. Using for-of:

for (const record of resourceStore) {
    console.log(record.name);
}

Or by using forEach:

resourceStore.forEach(record => {
    console.log(record.name);
});

The stores implementation of forEach() differs from the native arrays by allowing you to terminate the iteration by returning false.

CRUD operations

Adding records

You can easily add existing records or raw data:

resourceStore.add({ name : 'Scarlet Witch' });

// or

resourceStore.add(new ResourceModel({
  name : 'Storm',
  powers : 'Weather'
}));

Same goes for insertion:

resourceStore.insert(0, { name : 'She-Hulk' });

// or

resourceStore.insert(0, new ResourceModel({
  name : 'Medusa',
  powers : 'Hair'
}));

Removing records

Either retrieve a record and call remove() on it or remove it using its id:

resourceStore.remove(1); // Removes Ms. Marvel

resourceStore.last.remove(); // Removes Mockingbird

Modifying records

Fields in a record are turned into setters which can be assigned to update the record, making it reactive. Doing so triggers events that updates the TaskBoard (if the store is used with a TaskBoard). To modify a record, simply retrieve it and set values:

resourceStore.last.name = 'Jennifer Walters';

To set multiple fields in a single go:

resourceStore.last.set({
    name   : 'Jennifer Walters',
    powers : 'Strength'
});

JSON

If you want to serialize the contents of a store, you can access the data from all of its records in JSON format:

const jsonString = resourceStore.json;

or

const jsonArray = resourceStore.toJSON();

To plug the JSON data back in later:

resourceStore.json = jsonString;

or

resourceStore.data = jsonArray;

Customizing TaskBoard stores

There are multiple ways to customize a taskboard store. The easiest one is to pass a configuration object for it within the project's configuration:

project : {
    // other config
    assignmentStore : {
        allowNoId      : false,
        writeAllFields : true,
        listeners      : {
            remove : () => { 
                // This listener runs after a record is removed from the store
            }
        }
    }
}

Another way to create a custom store with simple configurations is to create a new instance of store with your configuration. This is used when you want to reuse it in multiple places.

const customAssignmentStore = new AssignmentStore({
    allowNoId      : false,
    writeAllFields : true,
    listeners      : {
        remove : () => { 
            // This listener runs after a record is removed from the store
        }
    }
});

Next, you can pass it to the project:

project : {
    // other config
    assignmentStore : customAssignmentStore
}

You can subclass it if you are going to use it in multiple places, or if you want to place it in a separate file/module for code organization:

class CustomTaskStore extends TaskStore {
    static $name = 'CustomTaskStore';
    static configurable = {
        allowNoId      : false,
        writeAllFields : true,
        listeners      : {
            remove : () => { 
                // This listener runs after a record is removed from the store
            }
        },
        tree : true
    };
}

Then create a new instance of it and pass it with the project config when creating a new TaskBoard instance:

const customTaskStore = new CustomTaskStore();

const taskboard = new TaskBoard({
    // other config
    project :{
        taskStore : customTaskStore
    }
});

You can confirm it doing console.log(taskboard.project.taskStore).

Continue reading

Contents