# Class Ext.data.DataWriter

Package: | Ext.data
Defined In: | DataWriter.js
Class: | DataWriter
Subclasses: | JsonWriter, XmlWriter
Extends: | Object

Ext.data.DataWriter facilitates create, update, and destroy actions between an Ext.data.Store and a server-side framework. A Writer enabled Store will automatically manage the Ajax requests to perform CRUD actions on a Store.

Ext.data.DataWriter is an abstract base class which is intended to be extended and should not be created directly. For existing implementations, see Ext.data.JsonWriter.

Creating a writer is simple:

    var writer = new Ext.data.JsonWriter({
        encode: false   // <--- false causes data to be printed to jsonData config-property of Ext.Ajax#reqeust
    });

Same old JsonReader as Ext-2.x:

    var reader = new Ext.data.JsonReader({idProperty: 'id'}, [{name: 'first'}, {name: 'last'}, {name: 'email'}]);

The proxy for a writer enabled store can be configured with a simple `url`:

    // Create a standard HttpProxy instance.
    var proxy = new Ext.data.HttpProxy({
        url: 'app.php/users'    // <--- Supports "provides"-type urls, such as '/users.json', '/products.xml' (Hello Rails/Merb)
    });

For finer grained control, the proxy may also be configured with an `API`:

    // Maximum flexibility with the API-configuration
    var proxy = new Ext.data.HttpProxy({
        api: {
            read    : 'app.php/users/read',
            create  : 'app.php/users/create',
            update  : 'app.php/users/update',
            destroy : {  // <--- Supports object-syntax as well
                url: 'app.php/users/destroy',
                method: "DELETE"
            }
        }
    });

Pulling it all together into a Writer-enabled Store:

    var store = new Ext.data.Store({
        proxy: proxy,
        reader: reader,
        writer: writer,
        autoLoad: true,
        autoSave: true  // -- Cell-level updates.
    });

Initiating write-actions automatically, using the existing Ext2.0 Store/Record API:

    var rec = store.getAt(0);
    rec.set('email', 'foo@bar.com');  // <--- Immediately initiates an UPDATE action through configured proxy.

    store.remove(rec);  // <---- Immediately initiates a DESTROY action through configured proxy.

For record/batch updates, use the Store-configuration autoSave:false

    var store = new Ext.data.Store({
        proxy: proxy,
        reader: reader,
        writer: writer,
        autoLoad: true,
        autoSave: false  // -- disable cell-updates
    });

    var urec = store.getAt(0);
    urec.set('email', 'foo@bar.com');

    var drec = store.getAt(1);
    store.remove(drec);

    // Push the button!
    store.save();

## Config Options

Config Options | Defined By
--- | ---
| createRecord : Function Abstract method that should be implemented in all subclasses (e.g.: JsonWriter.createRecord) | DataWriter
| destroyRecord : Function Abstract method that should be implemented in all subclasses (e.g.: JsonWriter.destroyRecord) | DataWriter
| listful : Boolean false by default. Set true to have the DataWriter always write HTTP params as a list, even when acting upon a single... `false` by default. Set `true` to have the DataWriter always write HTTP params as a list, even when acting upon a single record. | DataWriter
| updateRecord : Function Abstract method that should be implemented in all subclasses (e.g.: JsonWriter.updateRecord | DataWriter
| writeAllFields : Boolean false by default. Set true to have DataWriter return ALL fields of a modified record -- not just those that changed.... `false` by default. Set `true` to have DataWriter return ALL fields of a modified record -- not just those that changed. `false` to have DataWriter only request modified fields from a record. | DataWriter

## Public Properties

This class has no public properties.

## Public Methods

Method | Defined By
--- | ---
| DataWriter( Object meta, Object recordType ) Create a new DataWriter Create a new DataWriter Parameters: `meta` : Object Metadata configuration options (implementation-specific) `recordType` : Object Either an Array of field definition objects as specified in Ext.data.Record.create, or an Ext.data.Record object created using Ext.data.Record.create. Returns: void | DataWriter
| apply( Object params, Object baseParams, String action, Record/Record[] rs ) : void Compiles a Store recordset into a data-format defined by an extension such as Ext.data.JsonWriter or Ext.data.XmlWrit... Compiles a Store recordset into a data-format defined by an extension such as Ext.data.JsonWriter or Ext.data.XmlWriter in preparation for a server-write action. The first two params are similar similar in nature to Ext.apply, Where the first parameter is the receiver of paramaters and the second, baseParams, the source. Parameters: `params` : Object The request-params receiver. `baseParams` : Object as defined by Ext.data.Store.baseParams. The baseParms must be encoded by the extending class, eg: Ext.data.JsonWriter, Ext.data.XmlWriter. `action` : String [create|update|destroy] `rs` : Record/Record[] The recordset to write, the subject(s) of the write action. Returns: void | DataWriter
| render( String action, Record[] rs, Object params, Object data ) : void abstract method meant to be overridden by all DataWriter extensions. It's the extension's job to apply the "data" to... abstract method meant to be overridden by all DataWriter extensions. It's the extension's job to apply the "data" to the "params". The data-object provided to render is populated with data according to the meta-info defined in the user's DataReader config, Parameters: `action` : String [Ext.data.Api.actions.create|read|update|destroy] `rs` : Record[] Store recordset `params` : Object Http params to be sent to server. `data` : Object object populated according to DataReader meta-data. Returns: void | DataWriter
| toArray( Hash data ) : [Object] Converts a Hashed Ext.data.Record to fields-array array suitable for encoding to xml via XTemplate, eg: &lt;tpl for="... Converts a Hashed Ext.data.Record to fields-array array suitable for encoding to xml via XTemplate, eg: `
    <tpl for="."><{name}>{value}</{name}</tpl>
` eg, non-phantom: `
    {id: 1, first: 'foo', last: 'bar'} --> [{name: 'id', value: 1}, {name: 'first', value: 'foo'}, {name: 'last', value: 'bar'}]
` Phantom records will have had their idProperty omitted in toHash if determined to be auto-generated. Non AUTOINCREMENT pks should have been protected. Parameters: `data` : Hash Hashed by Ext.data.DataWriter#toHash Returns: `[Object]` Array of attribute-objects. | DataWriter
| toHash( Ext.data.Record rec, Object config ) : Object Converts a Record to a hash, taking into account the state of the Ext.data.Record along with configuration properties... Converts a Record to a hash, taking into account the state of the Ext.data.Record along with configuration properties related to its rendering, such as writeAllFields, phantom, getChanges and idProperty Parameters: `rec` : Ext.data.Record The Record from which to create a hash. `config` : Object NOT YET IMPLEMENTED. Will implement an exlude/only configuration for fine-control over which fields do/don't get rendered. Returns: `Object` | DataWriter

## Public Events

This class has no public events.