dojo.data.ItemFileWriteStore

Dojo core provides the ItemFileWriteStore store as an extension to ItemFileReadStore that adds on the dojo.data.api.Write and dojo.data.api.Notification API support to ItemFileReadStore. It was specifically created as a separate class so that if you only need read capability, you do not incur the download penalty of the write and notification API support if you won't use it. If your application needs to write to the ItemFileStore instead of just Read, then ItemFileWriteStore is the store you should instantiate. The input data format is identical to ItemFileReadStore.

The following dojo.data APIs are implemented by ItemFileWriteStore

• dojo.data.api.Read
• dojo.data.api.Write
• dojo.data.api.Identity
• dojo.data.api.Notification

Constructor Parameters

The constructor for ItemFileWriteStore takes the same parameters as ItemFileReadStore these are the following possible parameters in its keyword arguments:

url

The URL from which to load the JSON data. This is optional.

data

The JavaScript object that represents the stores contents, as defined by the previous structure. This is optional.

typeMap

A JavaScript associative map of data types to deserialize them. This is optional. See the Custom Data Type Mapping for more details.

Custom Data Type Mappings

The custom type mapping for the ItemFileWriteStore follows the same conventions as the ItemFileReadStore. The only caveat is, that for general purpose mappings, you must also provide a serialize function for mapping so the data can be rendered back out appropriately. For simple mapping, object.toString() is sufficient.

Simple Mapping: Direct Constructor

The direct constructor approach is the simplest way to map a type. This one assumes that the value stored in _value can be used as the parameter to the constructor for an object. When serializing this back to the ItemFileFormat, this assumes that object.toString() is sufficient for the _value value as shown in the following example:

var typeMap = {
                 "Color": dojo.Color,
                 ...
              };

General Purpose Mapping

The general purpose mapping is intended for cases in which you cannot directly pass the value of _value into a constructor. A good example of this is how Date is mapped internally in the ItemFileReadStore. This is used because ItemFileReadStore reads in the _value for a date as a serialized ISO string, which is not a format the general JavasScript Date object understands.

The following example shows date serialization and deserialization mapping:

var typeMap = {
                  "Date": {
                             type: Date,
                             deserialize: function(value){
                                 return dojo.date.stamp.fromISOString(value);
                             },
                             serialize: function(object){
                                 return dojo.date.stamp.toISOString(object);
                             }
                          }
              };

Query Syntax

The query syntax for ItemFileWriteStore is identical to the query syntax of ItemFileReadStore so see that section for more information.

Usage Examples

For these examples, we'll assume a datasource as defined by the following example data:

{ identifier: 'abbr',
  label: 'name',
  items: [
    { abbr:'ec', name:'Ecuador',           capital:'Quito' },
    { abbr:'eg', name:'Egypt',             capital:'Cairo' },
    { abbr:'sv', name:'El Salvador',       capital:'San Salvador' },
    { abbr:'gq', name:'Equatorial Guinea', capital:'Malabo' },
    { abbr:'er', name:'Eritrea',           capital:'Asmara' },
    { abbr:'ee', name:'Estonia',           capital:'Tallinn' },
    { abbr:'et', name:'Ethiopia',          capital:'Addis Ababa' }
]}

Example 1: Add in a new country

var store = new dojo.data.ItemFileWriteStore({url: "countries.json"});
var usa = store.newItem({abbr: 'us', name: 'United States of America', capital: 'Washington DC'});

function saveDone(){
    alert("Done saving.");
}
function saveFailed(){
    alert("Save failed.");
}
store.save({onComplete: saveDone, onError: saveFailed});

Example 2: Delete a country

var store = new dojo.data.ItemFileWriteStore({url: "countries.json"}); function saveDone(){ alert("Done saving."); } function saveFailed(){ alert("Save failed."); } var gotNames= function(items, request){ for (var i = 0; i < items.length; i++){ console.log("Deleted country: " + store.getLabel(item); store.deleteItem(items[i]); } store.save({onComplete: saveDone, onError: saveFailed}); } var request = store.fetch({query: {name:"Egypt"}, queryOptions: {ignoreCase: true}, onComplete: gotNames});

Custom Saving

The save method by itself only updates the in-memory copy. To write the store back to the server, you need to override the extension point "_saveCustom". In markup language, it'd look something like:

You could also extend ItemFileWriteStore using Dojo's inheritance facilities:

dojo.declare("CustomItemFileWriteStore", ItemFileWriteStore, {
        _saveCustom: function(saveCompleteCallback, saveFailedCallback){
                //  xhrPost/xhrPut your data back to your server (convert it to the server format first if need be)
                // 'this' keyword refers to the ItemFileWriteStore instance being extended
                saveCompleteCallback();
        }
});

Further examples

For further examples refer to the Using Datastores section of the Dojo book or refer to the test cases for dojo.data provided in the tests sub-directory of your dojo distribution.