← Back to branch summary

~cdparra/gelee/trunk

« back to all changes in this revision

Viewing changes to webui/ecosystem/workspace/extjs/docs/output/Ext.data.JsonReader.html

  • Committer: parra
  • Date: 2010-03-15 15:56:56 UTC
  • Revision ID: svn-v4:ac5bba68-f036-4e09-846e-8f32731cc928:trunk/gelee:1448
merged gelee at svn

Show diffs side-by-side

added added

removed removed

Lines of Context:
webui/ecosystem/workspace/extjs/docs/output/Ext.data.JsonReader.html
 
1
<div class="body-wrap" xmlns:ext="http://www.extjs.com"><div class="top-tools"><a class="inner-link" href="#Ext.data.JsonReader-props"><img src="resources/images/default/s.gif" class="item-icon icon-prop">Properties</a>&#13;<a class="inner-link" href="#Ext.data.JsonReader-methods"><img src="resources/images/default/s.gif" class="item-icon icon-method">Methods</a>&#13;<a class="inner-link" href="#Ext.data.JsonReader-events"><img src="resources/images/default/s.gif" class="item-icon icon-event">Events</a>&#13;<a class="inner-link" href="#Ext.data.JsonReader-configs"><img src="resources/images/default/s.gif" class="item-icon icon-config">Config Options</a>&#13;<a class="bookmark" href="../docs/?class=Ext.data.JsonReader"><img src="resources/images/default/s.gif" class="item-icon icon-fav">Direct Link</a>&#13;</div><div class="inheritance res-block"><pre class="res-block-inner"><a href="output/Ext.data.DataReader.html" ext:member="" ext:cls="Ext.data.DataReader">DataReader</a>&#13;&nbsp;&nbsp;<img src="resources/elbow-end.gif">JsonReader</pre></div><h1>Class <a href="source/JsonReader.html#cls-Ext.data.JsonReader">Ext.data.JsonReader</a></h1><table cellspacing="0"><tr><td class="label">Package:</td><td class="hd-info">Ext.data</td></tr><tr><td class="label">Defined In:</td><td class="hd-info">JsonReader.js</td></tr><tr><td class="label">Class:</td><td class="hd-info"><a href="source/JsonReader.html#cls-Ext.data.JsonReader">JsonReader</a></td></tr><tr><td class="label">Subclasses:</td><td class="hd-info"><a href="output/Ext.data.ArrayReader.html" ext:cls="Ext.data.ArrayReader">ArrayReader</a></td></tr><tr><td class="label">Extends:</td><td class="hd-info"><a href="output/Ext.data.DataReader.html" ext:cls="Ext.data.DataReader" ext:member="">DataReader</a></td></tr></table><div class="description"><p>Data reader class to create an Array of <a href="output/Ext.data.Record.html" ext:cls="Ext.data.Record">Ext.data.Record</a> objects from a JSON response
 
2
based on mappings in a provided <a href="output/Ext.data.Record.html" ext:cls="Ext.data.Record">Ext.data.Record</a> constructor.</p>
 
3
<p>Example code:</p>
 
4
<pre><code><b>var</b> Employee = Ext.data.Record.create([
 
5
    {name: <em>'firstname'</em>},                  <i>// map the Record<em>'s <em>"firstname"</em> field to the row object'</em>s key of the same name</i>
 
6
    {name: <em>'job'</em>, mapping: <em>'occupation'</em>}  <i>// map the Record<em>'s <em>"job"</em> field to the row object'</em>s <em>"occupation"</em> key</i>
 
7
]);
 
8
<b>var</b> myReader = <b>new</b> Ext.data.JsonReader(
 
9
    {                             <i>// The metadata property, <b>with</b> configuration options:</i>
 
10
        totalProperty: <em>"results"</em>, <i>//   the property which contains the total dataset size (optional)</i>
 
11
        root: <em>"rows"</em>,             <i>//   the property which contains an Array of record data objects</i>
 
12
        idProperty: <em>"id"</em>          <i>//   the property within each row object that provides an ID <b>for</b> the record (optional)</i>
 
13
    },
 
14
    Employee  <i>// <a href="output/Ext.data.Record.html" ext:cls="Ext.data.Record">Ext.data.Record</a> constructor that provides mapping <b>for</b> JSON object</i>
 
15
);</code></pre>
 
16
<p>This would consume a JSON data object of the form:</p><pre><code>{
 
17
    results: 2,  <i>// Reader<em>'s configured totalProperty</i>
 
18
    rows: [      <i>// Reader'</em>s configured root</i>
 
19
        { id: 1, firstname: <em>'Bill'</em>, occupation: <em>'Gardener'</em> },         <i>// a row object</i>
 
20
        { id: 2, firstname: <em>'Ben'</em> , occupation: <em>'Horticulturalist'</em> }  <i>// another row object</i>
 
21
    ]
 
22
}</code></pre>
 
23
<p><b><u>Automatic configuration using metaData</u></b></p>
 
24
<p>It is possible to change a JsonReader's metadata at any time by including a <b><tt>metaData</tt></b>
 
25
property in the JSON data object. If the JSON data object has a <b><tt>metaData</tt></b> property, a
 
26
<a href="output/Ext.data.Store.html" ext:cls="Ext.data.Store">Store</a> object using this Reader will reconfigure itself to use the newly provided
 
27
field definition and fire its <a href="output/Ext.data.Store.html#Ext.data.Store-metachange" ext:member="metachange" ext:cls="Ext.data.Store">metachange</a> event. The metachange event
 
28
handler may interrogate the <b><tt>metaData</tt></b> property to perform any configuration required.
 
29
Note that reconfiguring a Store potentially invalidates objects which may refer to Fields or Records
 
30
which no longer exist.</p>
 
31
<p>The <b><tt>metaData</tt></b> property in the JSON data object may contain:</p>
 
32
<div class="mdetail-params"><ul>
 
33
<li>any of the configuration options for this class</li>
 
34
<li>a <b><tt><a href="output/Ext.data.Record.html#Ext.data.Record-fields" ext:member="fields" ext:cls="Ext.data.Record">fields</a></tt></b> property which the JsonReader will
 
35
use as an argument to the <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">data Record create method</a> in order to
 
36
configure the layout of the Records it will produce.</li>
 
37
<li>a <b><tt><a href="output/Ext.data.Store.html#Ext.data.Store-sortInfo" ext:member="sortInfo" ext:cls="Ext.data.Store">sortInfo</a></tt></b> property which the JsonReader will
 
38
use to set the <a href="output/Ext.data.Store.html" ext:cls="Ext.data.Store">Ext.data.Store</a>'s <a href="output/Ext.data.Store.html#Ext.data.Store-sortInfo" ext:member="sortInfo" ext:cls="Ext.data.Store">sortInfo</a> property</li>
 
39
<li>any user-defined properties needed</li>
 
40
</ul></div>
 
41
<p>To use this facility to send the same data as the example above (without having to code the creation
 
42
of the Record constructor), you would create the JsonReader like this:</p><pre><code><b>var</b> myReader = <b>new</b> Ext.data.JsonReader();</code></pre>
 
43
<p>The first data packet from the server would configure the reader by containing a
 
44
<b><tt>metaData</tt></b> property <b>and</b> the data. For example, the JSON data object might take
 
45
the form:</p>
 
46
<pre><code>{
 
47
    metaData: {
 
48
        idProperty: <em>'id'</em>,
 
49
        root: <em>'rows'</em>,
 
50
        totalProperty: <em>'results'</em>,
 
51
        fields: [
 
52
            {name: <em>'name'</em>},
 
53
            {name: <em>'job'</em>, mapping: <em>'occupation'</em>}
 
54
        ],
 
55
        sortInfo: {field: <em>'name'</em>, direction:<em>'ASC'</em>}, <i>// used by store to set its sortInfo</i>
 
56
        foo: <em>'bar'</em> <i>// custom property</i>
 
57
    },
 
58
    results: 2,
 
59
    rows: [ <i>// an Array</i>
 
60
        { <em>'id'</em>: 1, <em>'name'</em>: <em>'Bill'</em>, occupation: <em>'Gardener'</em> },
 
61
        { <em>'id'</em>: 2, <em>'name'</em>: <em>'Ben'</em>, occupation: <em>'Horticulturalist'</em> }
 
62
    ]
 
63
}</code></pre></div><div class="hr"></div><a id="Ext.data.JsonReader-configs"></a><h2>Config Options</h2><table cellspacing="0" class="member-table"><tbody><tr><th colspan="2" class="sig-header">Config Options</th><th class="msource-header">Defined By</th></tr><tr class="config-row expandable inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.DataReader-fields"></a><b><a href="source/DataReader.html#cfg-Ext.data.DataReader-fields">fields</a></b> : Array/Object<div class="mdesc"><div class="short">Either an Array of Field definition objects (which&#13;
 
64
will be passed to Ext.data.Record.create, or a Record&#13;
 
65
constructo...</div><div class="long"><p>Either an Array of <a href="output/Ext.data.Field.html" ext:cls="Ext.data.Field">Field</a> definition objects (which
 
66
will be passed to <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">Ext.data.Record.create</a>, or a <a href="output/Ext.data.Record.html" ext:cls="Ext.data.Record">Record</a>
 
67
constructor created from <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">Ext.data.Record.create</a>.</p></div></div></td><td class="msource"><a href="output/Ext.data.DataReader.html#fields" ext:member="#fields" ext:cls="Ext.data.DataReader">DataReader</a></td></tr><tr class="config-row  "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-idProperty"></a><b><a href="source/JsonReader.html#cfg-Ext.data.JsonReader-idProperty">idProperty</a></b> : String<div class="mdesc">[id] Name of the property within a row object that contains a record identifier value.  Defaults to <tt>id</tt></div></td><td class="msource">JsonReader</td></tr><tr class="config-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-root"></a><b><a href="source/JsonReader.html#cfg-Ext.data.JsonReader-root">root</a></b> : String<div class="mdesc"><div class="short">[undefined] Required.  The name of the property
 
68
which contains the Array of row objects.  Defaults to undefined.
 
69
An e...</div><div class="long">[undefined] <b>Required</b>.  The name of the property
 
70
which contains the Array of row objects.  Defaults to <tt>undefined</tt>.
 
71
An exception will be thrown if the root property is undefined. The data packet
 
72
value for this property should be an empty array to clear the data or show
 
73
no data.</div></div></td><td class="msource">JsonReader</td></tr><tr class="config-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-successProperty"></a><b><a href="source/JsonReader.html#cfg-Ext.data.JsonReader-successProperty">successProperty</a></b> : String<div class="mdesc"><div class="short">[success] Name of the property from which to
 
74
retrieve the success attribute. Defaults to success.  See
 
75
Ext.data.DataP...</div><div class="long">[success] Name of the property from which to
 
76
retrieve the success attribute. Defaults to <tt>success</tt>.  See
 
77
<a href="output/Ext.data.DataProxy.html" ext:cls="Ext.data.DataProxy">Ext.data.DataProxy</a>.<a href="output/Ext.data.DataProxy.html#Ext.data.DataProxy-exception" ext:member="exception" ext:cls="Ext.data.DataProxy">exception</a>
 
78
for additional information.</div></div></td><td class="msource">JsonReader</td></tr><tr class="config-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-totalProperty"></a><b><a href="source/JsonReader.html#cfg-Ext.data.JsonReader-totalProperty">totalProperty</a></b> : String<div class="mdesc"><div class="short">[total] Name of the property from which to retrieve the total number of records
 
79
in the dataset. This is only needed i...</div><div class="long">[total] Name of the property from which to retrieve the total number of records
 
80
in the dataset. This is only needed if the whole dataset is not passed in one go, but is being
 
81
paged from the remote server.  Defaults to <tt>total</tt>.</div></div></td><td class="msource">JsonReader</td></tr></tbody></table><a id="Ext.data.JsonReader-props"></a><h2>Public Properties</h2><table cellspacing="0" class="member-table"><tbody><tr><th colspan="2" class="sig-header">Property</th><th class="msource-header">Defined By</th></tr><tr class="property-row  inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.DataReader-buildExtractors"></a><b><a href="source/DataReader.html#prop-Ext.data.DataReader-buildExtractors">buildExtractors</a></b> : Object<div class="mdesc">Abstract method, overridden in <a href="output/Ext.data.JsonReader.html" ext:cls="Ext.data.JsonReader">Ext.data.JsonReader</a></div></td><td class="msource"><a href="output/Ext.data.DataReader.html#buildExtractors" ext:member="#buildExtractors" ext:cls="Ext.data.DataReader">DataReader</a></td></tr><tr class="property-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-jsonData"></a><b><a href="source/JsonReader.html#prop-Ext.data.JsonReader-jsonData">jsonData</a></b> : Object<div class="mdesc"><div class="short">After any data loads, the raw JSON data is available for further custom processing.  If no data is
 
82
loaded or there is...</div><div class="long">After any data loads, the raw JSON data is available for further custom processing.  If no data is
 
83
loaded or there is a load exception this property will be undefined.</div></div></td><td class="msource">JsonReader</td></tr><tr class="property-row  "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-meta"></a><b><a href="source/JsonReader.html#prop-Ext.data.JsonReader-meta">meta</a></b> : Mixed<div class="mdesc">This JsonReader's metadata as passed to the constructor, or as passed in
 
84
the last data packet's <b><tt>metaData</tt></b> property.</div></td><td class="msource">JsonReader</td></tr></tbody></table><a id="Ext.data.JsonReader-methods"></a><h2>Public Methods</h2><table cellspacing="0" class="member-table"><tbody><tr><th colspan="2" class="sig-header">Method</th><th class="msource-header">Defined By</th></tr><tr class="method-row expandable"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-JsonReader"></a><b><a href="source/JsonReader.html#cls-Ext.data.JsonReader">JsonReader</a></b>(&nbsp;<code>Object&nbsp;meta</code>,&nbsp;<code>Array/Object&nbsp;recordType</code>&nbsp;)
 
85
    <div class="mdesc"><div class="short">Create a new JsonReader</div><div class="long">Create a new JsonReader<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>meta</code> : Object<div class="sub-desc">Metadata configuration options.</div></li><li><code>recordType</code> : Array/Object<div class="sub-desc"><p>Either an Array of <a href="output/Ext.data.Field.html" ext:cls="Ext.data.Field">Field</a> definition objects (which
 
86
will be passed to <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">Ext.data.Record.create</a>, or a <a href="output/Ext.data.Record.html" ext:cls="Ext.data.Record">Record</a>
 
87
constructor created from <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">Ext.data.Record.create</a>.</p></div></li></ul><strong>Returns:</strong><ul><li>void</li></ul></div></div></div></td><td class="msource">JsonReader</td></tr><tr class="method-row expandable inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.DataReader-isData"></a><b><a href="source/DataReader.html#method-Ext.data.DataReader-isData">isData</a></b>(&nbsp;<code>Object&nbsp;data</code>&nbsp;)
 
88
    :
 
89
                                        Boolean<div class="mdesc"><div class="short">Returns true if the supplied data-hash looks and quacks like data.  Checks to see if it has a key&#13;
 
90
corresponding to i...</div><div class="long">Returns true if the supplied data-hash <b>looks</b> and quacks like data.  Checks to see if it has a key
 
91
corresponding to idProperty defined in your DataReader config containing non-empty pk.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>data</code> : Object<div class="sub-desc"></div></li></ul><strong>Returns:</strong><ul><li><code>Boolean</code><div class="sub-desc"></div></li></ul></div></div></div></td><td class="msource"><a href="output/Ext.data.DataReader.html#isData" ext:member="#isData" ext:cls="Ext.data.DataReader">DataReader</a></td></tr><tr class="method-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-read"></a><b><a href="source/JsonReader.html#method-Ext.data.JsonReader-read">read</a></b>(&nbsp;<code>Object&nbsp;response</code>&nbsp;)
 
92
    :
 
93
                                        Object<div class="mdesc"><div class="short">This method is only used by a DataProxy which has retrieved data from a remote server.</div><div class="long">This method is only used by a DataProxy which has retrieved data from a remote server.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>response</code> : Object<div class="sub-desc">The XHR object which contains the JSON data in its responseText.</div></li></ul><strong>Returns:</strong><ul><li><code>Object</code><div class="sub-desc">data A data block which is used by an Ext.data.Store object as
 
94
a cache of Ext.data.Records.</div></li></ul></div></div></div></td><td class="msource">JsonReader</td></tr><tr class="method-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-readRecords"></a><b><a href="source/JsonReader.html#method-Ext.data.JsonReader-readRecords">readRecords</a></b>(&nbsp;<code>Object&nbsp;o</code>&nbsp;)
 
95
    :
 
96
                                        Object<div class="mdesc"><div class="short">Create a data block containing Ext.data.Records from a JSON object.</div><div class="long">Create a data block containing Ext.data.Records from a JSON object.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>o</code> : Object<div class="sub-desc">An object which contains an Array of row objects in the property specified
 
97
in the config as 'root, and optionally a property, specified in the config as 'totalProperty'
 
98
which contains the total size of the dataset.</div></li></ul><strong>Returns:</strong><ul><li><code>Object</code><div class="sub-desc">data A data block which is used by an Ext.data.Store object as
 
99
a cache of Ext.data.Records.</div></li></ul></div></div></div></td><td class="msource">JsonReader</td></tr><tr class="method-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.JsonReader-readResponse"></a><b><a href="source/JsonReader.html#method-Ext.data.JsonReader-readResponse">readResponse</a></b>(&nbsp;<code>String&nbsp;action</code>,&nbsp;<code>Object&nbsp;response</code>&nbsp;)
 
100
    :
 
101
                                        void<div class="mdesc"><div class="short">Decode a json response from server.</div><div class="long">Decode a json response from server.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>action</code> : String<div class="sub-desc">[Ext.data.Api.actions.create|read|update|destroy]</div></li><li><code>response</code> : Object<div class="sub-desc"></div></li></ul><strong>Returns:</strong><ul><li>void</li></ul></div></div></div></td><td class="msource">JsonReader</td></tr><tr class="method-row expandable inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.DataReader-realize"></a><b><a href="source/DataReader.html#method-Ext.data.DataReader-realize">realize</a></b>(&nbsp;<code>Record/Record[]&nbsp;record</code>,&nbsp;<code>Object/Object[]&nbsp;data</code>&nbsp;)
 
102
    :
 
103
                                        void<div class="mdesc"><div class="short">Used for un-phantoming a record after a successful database insert.  Sets the records pk along with new data from ser...</div><div class="long">Used for un-phantoming a record after a successful database insert.  Sets the records pk along with new data from server.
 
104
You <b>must</b> return at least the database pk using the idProperty defined in your DataReader configuration.  The incoming
 
105
data from server will be merged with the data in the local record.
 
106
In addition, you <b>must</b> return record-data from the server in the same order received.
 
107
Will perform a commit as well, un-marking dirty-fields.  Store's "update" event will be suppressed.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>record</code> : Record/Record[]<div class="sub-desc">The phantom record to be realized.</div></li><li><code>data</code> : Object/Object[]<div class="sub-desc">The new record data to apply.  Must include the primary-key from database defined in idProperty field.</div></li></ul><strong>Returns:</strong><ul><li>void</li></ul></div></div></div></td><td class="msource"><a href="output/Ext.data.DataReader.html#realize" ext:member="#realize" ext:cls="Ext.data.DataReader">DataReader</a></td></tr><tr class="method-row expandable inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.DataReader-update"></a><b><a href="source/DataReader.html#method-Ext.data.DataReader-update">update</a></b>(&nbsp;<code>Record/Record[]&nbsp;rs</code>,&nbsp;<code>Object/Object[]&nbsp;data</code>&nbsp;)
 
108
    :
 
109
                                        void<div class="mdesc"><div class="short">Used for updating a non-phantom or "real" record's data with fresh data from server after remote-save.&#13;
 
110
If returning ...</div><div class="long">Used for updating a non-phantom or "real" record's data with fresh data from server after remote-save.
 
111
If returning data from multiple-records after a batch-update, you <b>must</b> return record-data from the server in
 
112
the same order received.  Will perform a commit as well, un-marking dirty-fields.  Store's "update" event will be
 
113
suppressed as the record receives fresh new data-hash<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>rs</code> : Record/Record[]<div class="sub-desc"></div></li><li><code>data</code> : Object/Object[]<div class="sub-desc"></div></li></ul><strong>Returns:</strong><ul><li>void</li></ul></div></div></div></td><td class="msource"><a href="output/Ext.data.DataReader.html#update" ext:member="#update" ext:cls="Ext.data.DataReader">DataReader</a></td></tr></tbody></table><a id="Ext.data.JsonReader-events"></a><h2>Public Events</h2><div class="no-members">This class has no public events.</div></div>
 
 
b'\\ No newline at end of file'