v7.3.0

Using AjaxStore

As described in the Remote data guide, we recommend using the Crud manager approach to communicate with a backend (if you do not have other means in place already), handling all stores in a single request. But in some cases, it might still make sense to handle communication on a per store basis.

The stores used by TaskBoards project (TaskStore, ResourceStore and AssignmentStore) are all based on AjaxStore, which allows you to handle CRUD operations on the backend. AjaxStore for the most part works as a normal Store, but when creating it you need to supply some additional configs with URLs to the server:

const taskBoard = new TaskBoard({
    project : {
        taskStore : {
            createUrl : 'backend/task/create.php',
            readUrl   : 'backend/task/read.php',
            updateUrl : 'backend/task/update.php',
            deleteUrl : 'backend/task/delete.php'
        }
    }
});

As the name suggests, the store then uses these URLs for Ajax requests for the different CRUD operations.

Reading data

Uses GET to retrieve data from the backend. Data can be read automatically following construction of a store configured with { autoLoad : true} or manually by calling store.load():

// Data will be loaded directly
const taskStore = new TaskStore({
    readUrl : 'backend/task/read.php',
    autoLoad : true
});

// Or

const taskStore = new TaskStore({
    readUrl : 'backend/taskread.php'
});

// Data loaded manually
taskStore.load();

When manually calling store.load() you can also supply parameters in object form, which will be appended to the QueryString:

taskStore.load({ from : 1, to : 1000 }); // -> backend/task/read.php?from=1&to=1000

Server response

Data returned is either expected to be an array of record data…

[
    { "id": 1, "name" : "Buy candy" },
    { "id": 2, "name" : "Eat candy" }
]

…or a response object with the following format:

{
    "success" : true,
    "data" : [
        { "id": 1, "name" : "Buy vegetables" },
        { "id": 2, "name" : "Slice vegetables" }
    ]
}

When using the latter format it is also possible to communicate server exceptions:

{
    "success" : false,
    "message" : "That did not work very well, sorry" 
}

Async operations

Loading data, as well as the other CRUD operations, are async operations. Calling store.load returns a Promise, which can be used as is or with async/await:

// Using promise directly
taskStore.load().then(() => console.log('loaded'));

// Using await
await taskStore.load();
console.log('loaded');

You can also supply a listener that will be triggered on load:

const taskStore = new TaskStore({
    readUrl : 'backend/task/read.php',
    listeners: {
        load() {
            console.log('loaded');
        }
    }
});

// Or

taskStore.on('load', () => console.log('loaded'));

The same concept holds true when committing changes manually, as described below (store.commit()).

Modifying data

How to modify data in the store (add, insert, remove, update) is described in the guide Using a Store. When using an AjaxStore, no changes are sent to the backend until store.commit() is called. This can either be done manually or automatically:

taskStore.commit(); // Commits any changes, using the configured urls per action

// Or specify { autoCommit : true } to commit automatically after each action
const autoStore = new TaskStore({
    autoCommit : true,
    /*...*/
});

If you want to cancel changes, you can do so if using manual committing by calling store.clearChanges().

Added records

Any added (or inserted) records will be sent as JSON using POST to createUrl. The format will be:

// Add operation
taskStore.add([
    { name : 'Buy eggs' },
    { name : 'Make meringue' }
]);

// Post to server
data = [
    { "name" : "Buy eggs" }, 
    { "name" : "Make meringue" }
]

Server is expected to respond with the same records with any missing data filled in (such as id). The response takes the same format as for reading data.

{
    "success" : true,   
    "data" : [
        { "id" : 1, "name" : "Buy eggs" },
        { "id" : 2, "name" : "Make meringue" }
    ]
}

Updated records

Works much the same way as when adding records, but posts to updateUrl:

// Modifying some records and committing changes
taskStore.getAt(0).name = 'Buy cake';
taskStore.getAt(1).name = 'Eat cake';
taskStore.commit();

// Post to server
data = [{ "id" : 1, "name" : "Buy cake" }, { "id" : 2, "name" : "Eat cake" }]

Please note that only changed fields are posted. Server is expected to respond with same format as for adding records.

Removed records

Has the simplest requirements of the different operations. Posts ids of removed records to deleteUrl:

// Removing some records and committing
taskStore.getById(1).remove();
taskStore.getById(2).remove();
taskStore.commmit();

// Post to server
data = [1, 2]

Expects a response in this format:

{
    "success" : true
}

Contents