Properties Methods Events Config Options Direct Link

    DataReader
      JsonReader

# Class Ext.data.JsonReader

Package: | Ext.data
Defined In: | JsonReader.js
Class: | JsonReader
Subclasses: | ArrayReader
Extends: | DataReader

Data reader class to create an Array of Ext.data.Record objects from a JSON response based on mappings in a provided Ext.data.Record constructor.

Example code:

    var Employee = Ext.data.Record.create([
        {name: 'firstname'},                  // map the Record's "firstname" field to the row object's key of the same name
        {name: 'job', mapping: 'occupation'}  // map the Record's "job" field to the row object's "occupation" key
    ]);
    var myReader = new Ext.data.JsonReader(
        {                             // The metadata property, with configuration options:
            totalProperty: "results", //   the property which contains the total dataset size (optional)
            root: "rows",             //   the property which contains an Array of record data objects
            idProperty: "id"          //   the property within each row object that provides an ID for the record (optional)
        },
        Employee  // Ext.data.Record constructor that provides mapping for JSON object
    );

This would consume a JSON data object of the form:

    {
        results: 2,  // Reader's configured totalProperty
        rows: [      // Reader's configured root
            { id: 1, firstname: 'Bill', occupation: 'Gardener' },         // a row object
            { id: 2, firstname: 'Ben' , occupation: 'Horticulturalist' }  // another row object
        ]
    }

Automatic configuration using metaData

It is possible to change a JsonReader's metadata at any time by including a `metaData` property in the JSON data object. If the JSON data object has a `metaData` property, a Store object using this Reader will reconfigure itself to use the newly provided field definition and fire its metachange event. The metachange event handler may interrogate the `metaData` property to perform any configuration required. Note that reconfiguring a Store potentially invalidates objects which may refer to Fields or Records which no longer exist.

The `metaData` property in the JSON data object may contain:

- any of the configuration options for this class
- a `fields` property which the JsonReader will use as an argument to the data Record create method in order to configure the layout of the Records it will produce.
- a `sortInfo` property which the JsonReader will use to set the Ext.data.Store's sortInfo property
- any user-defined properties needed

To use this facility to send the same data as the example above (without having to code the creation of the Record constructor), you would create the JsonReader like this:

    var myReader = new Ext.data.JsonReader();

The first data packet from the server would configure the reader by containing a `metaData` property and the data. For example, the JSON data object might take the form:

    {
        metaData: {
            idProperty: 'id',
            root: 'rows',
            totalProperty: 'results',
            fields: [
                {name: 'name'},
                {name: 'job', mapping: 'occupation'}
            ],
            sortInfo: {field: 'name', direction:'ASC'}, // used by store to set its sortInfo
            foo: 'bar' // custom property
        },
        results: 2,
        rows: [ // an Array
            { 'id': 1, 'name': 'Bill', occupation: 'Gardener' },
            { 'id': 2, 'name': 'Ben', occupation: 'Horticulturalist' }
        ]
    }

## Config Options

Config Options | Defined By
--- | ---
| fields : Array/Object Either an Array of Field definition objects (which will be passed to Ext.data.Record.create, or a Record constructo... Either an Array of Field definition objects (which will be passed to Ext.data.Record.create, or a Record constructor created from Ext.data.Record.create. | DataReader
| idProperty : String [id] Name of the property within a row object that contains a record identifier value. Defaults to `id` | JsonReader
| root : String [undefined] Required. The name of the property which contains the Array of row objects. Defaults to undefined. An e... [undefined] Required. The name of the property which contains the Array of row objects. Defaults to `undefined`. An exception will be thrown if the root property is undefined. The data packet value for this property should be an empty array to clear the data or show no data. | JsonReader
| successProperty : String [success] Name of the property from which to retrieve the success attribute. Defaults to success. See Ext.data.DataP... [success] Name of the property from which to retrieve the success attribute. Defaults to `success`. See Ext.data.DataProxy.exception for additional information. | JsonReader
| totalProperty : String [total] Name of the property from which to retrieve the total number of records in the dataset. This is only needed i... [total] Name of the property from which to retrieve the total number of records in the dataset. This is only needed if the whole dataset is not passed in one go, but is being paged from the remote server. Defaults to `total`. | JsonReader

## Public Properties

Property | Defined By
--- | ---
| buildExtractors : Object Abstract method, overridden in Ext.data.JsonReader | DataReader
| jsonData : Object After any data loads, the raw JSON data is available for further custom processing. If no data is loaded or there is... After any data loads, the raw JSON data is available for further custom processing. If no data is loaded or there is a load exception this property will be undefined. | JsonReader
| meta : Mixed This JsonReader's metadata as passed to the constructor, or as passed in the last data packet's `metaData` property. | JsonReader

## Public Methods

Method | Defined By
--- | ---
| JsonReader( `Object meta`, `Array/Object recordType` ) Create a new JsonReader Create a new JsonReader Parameters: `meta` : Object Metadata configuration options. `recordType` : Array/Object Either an Array of Field definition objects (which will be passed to Ext.data.Record.create, or a Record constructor created from Ext.data.Record.create. Returns: void | JsonReader
| isData( `Object data` ) : Boolean Returns true if the supplied data-hash looks and quacks like data. Checks to see if it has a key corresponding to i... Returns true if the supplied data-hash looks and quacks like data. Checks to see if it has a key corresponding to idProperty defined in your DataReader config containing non-empty pk. Parameters: `data` : Object Returns: `Boolean` | DataReader
| read( `Object response` ) : Object This method is only used by a DataProxy which has retrieved data from a remote server. This method is only used by a DataProxy which has retrieved data from a remote server. Parameters: `response` : Object The XHR object which contains the JSON data in its responseText. Returns: `Object` data A data block which is used by an Ext.data.Store object as a cache of Ext.data.Records. | JsonReader
| readRecords( `Object o` ) : Object Create a data block containing Ext.data.Records from a JSON object. Create a data block containing Ext.data.Records from a JSON object. Parameters: `o` : Object An object which contains an Array of row objects in the property specified in the config as 'root, and optionally a property, specified in the config as 'totalProperty' which contains the total size of the dataset. Returns: `Object` data A data block which is used by an Ext.data.Store object as a cache of Ext.data.Records. | JsonReader
| readResponse( `String action`, `Object response` ) : void Decode a json response from server. Decode a json response from server. Parameters: `action` : String [Ext.data.Api.actions.create|read|update|destroy] `response` : Object Returns: void | JsonReader
| realize( `Record/Record[] record`, `Object/Object[] data` ) : void Used for un-phantoming a record after a successful database insert. Sets the records pk along with new data from ser... Used for un-phantoming a record after a successful database insert. Sets the records pk along with new data from server. You must return at least the database pk using the idProperty defined in your DataReader configuration. The incoming data from server will be merged with the data in the local record. In addition, you must return record-data from the server in the same order received. Will perform a commit as well, un-marking dirty-fields. Store's "update" event will be suppressed. Parameters: `record` : Record/Record[] The phantom record to be realized. `data` : Object/Object[] The new record data to apply. Must include the primary-key from database defined in idProperty field. Returns: void | DataReader
| update( `Record/Record[] rs`, `Object/Object[] data` ) : void Used for updating a non-phantom or "real" record's data with fresh data from server after remote-save. If returning ... Used for updating a non-phantom or "real" record's data with fresh data from server after remote-save. If returning data from multiple-records after a batch-update, you must return record-data from the server in the same order received. Will perform a commit as well, un-marking dirty-fields. Store's "update" event will be suppressed as the record receives fresh new data-hash Parameters: `rs` : Record/Record[] `data` : Object/Object[] Returns: void | DataReader

## Public Events

This class has no public events.