Version: Smart Feature Phone 2.5

DataStoreCursor.next()

Description#

The next() method of the DataStoreCursor interface makes a request to retrieve information about the next operation that changes a record in the data store. Returns a promise of type DataStoreTask.

Note: The Data Store API is available in Web Workers, from Firefox 32 onwards

Syntax#

cursor.next().then(function(task) {
  // do stuff with next task in the cursor
});

Returns#

A Promise object of type DataStoreTask; it resolves with a DataStoreTask object representing the next operation.

Example#

In the following example, we use navigator.getDataStores to return a list of DataStore objects representing data stores on the device called contacts. Since there is only one such data store, we can access it inside the outer promise using stores[0]. The next promise uses DataStore.getLength to return the number of records in the store. If the value is 0, we populate the data store with records contained in the contactsInit object; if there is already data in the store, we run DataStore.sync to create a DataStoreCursor object allowing us to loop through any additions since the code last accessed the data store and update the data display as necessary.

The cursor is passed to the runNextTask() function, which calls DataStoreCursor.next to start the process of managing the next task — the resulting DataStoreTask object is passed to the manageTask() function to work out what to do with it. runNextTask() is then called repeatedly by manageTask() until the cursor has finished working through all the records.

navigator.getDataStores('contacts').then(function(stores) {
  stores[0].getLength().then(function(storeLength) {
    if(storeLength == 0) {
        for(i = 0; i < contactsInit.length; i++) {
        addContact(stores[0],contactsInit[i]);  
      };
    } else {
      var cursor = stores[0].sync();
      runNextTask(cursor);
    }
  });
});

function runNextTask(cursor) {
  cursor.next().then(function(task) {
    manageTask(cursor, task);
  });
}

function manageTask(cursor, task) {
  if (task.operation == 'done') {
    // Finished adding contacts!
    return;
  }

  if (task.operation == 'add') {
    // Add the contacts that are different to how it was before
    displayExisting(task.id, task.data);
  }

  runNextTask(cursor);
}