1 | /*! |
---|
2 | * Ext JS Library 3.0.0 |
---|
3 | * Copyright(c) 2006-2009 Ext JS, LLC |
---|
4 | * licensing@extjs.com |
---|
5 | * http://www.extjs.com/license |
---|
6 | */ |
---|
7 | /** |
---|
8 | * @class Ext.data.DataReader |
---|
9 | * Abstract base class for reading structured data from a data source and converting |
---|
10 | * it into an object containing {@link Ext.data.Record} objects and metadata for use |
---|
11 | * by an {@link Ext.data.Store}. This class is intended to be extended and should not |
---|
12 | * be created directly. For existing implementations, see {@link Ext.data.ArrayReader}, |
---|
13 | * {@link Ext.data.JsonReader} and {@link Ext.data.XmlReader}. |
---|
14 | * @constructor Create a new DataReader |
---|
15 | * @param {Object} meta Metadata configuration options (implementation-specific). |
---|
16 | * @param {Array/Object} recordType |
---|
17 | * <p>Either an Array of {@link Ext.data.Field Field} definition objects (which |
---|
18 | * will be passed to {@link Ext.data.Record#create}, or a {@link Ext.data.Record Record} |
---|
19 | * constructor created using {@link Ext.data.Record#create}.</p> |
---|
20 | */ |
---|
21 | Ext.data.DataReader = function(meta, recordType){ |
---|
22 | /** |
---|
23 | * This DataReader's configured metadata as passed to the constructor. |
---|
24 | * @type Mixed |
---|
25 | * @property meta |
---|
26 | */ |
---|
27 | this.meta = meta; |
---|
28 | /** |
---|
29 | * @cfg {Array/Object} fields |
---|
30 | * <p>Either an Array of {@link Ext.data.Field Field} definition objects (which |
---|
31 | * will be passed to {@link Ext.data.Record#create}, or a {@link Ext.data.Record Record} |
---|
32 | * constructor created from {@link Ext.data.Record#create}.</p> |
---|
33 | */ |
---|
34 | this.recordType = Ext.isArray(recordType) ? |
---|
35 | Ext.data.Record.create(recordType) : recordType; |
---|
36 | }; |
---|
37 | |
---|
38 | Ext.data.DataReader.prototype = { |
---|
39 | |
---|
40 | /** |
---|
41 | * Abstract method, overridden in {@link Ext.data.JsonReader} |
---|
42 | */ |
---|
43 | buildExtractors : Ext.emptyFn, |
---|
44 | |
---|
45 | /** |
---|
46 | * Used for un-phantoming a record after a successful database insert. Sets the records pk along with new data from server. |
---|
47 | * You <b>must</b> return at least the database pk using the idProperty defined in your DataReader configuration. The incoming |
---|
48 | * data from server will be merged with the data in the local record. |
---|
49 | * In addition, you <b>must</b> return record-data from the server in the same order received. |
---|
50 | * Will perform a commit as well, un-marking dirty-fields. Store's "update" event will be suppressed. |
---|
51 | * @param {Record/Record[]} record The phantom record to be realized. |
---|
52 | * @param {Object/Object[]} data The new record data to apply. Must include the primary-key from database defined in idProperty field. |
---|
53 | */ |
---|
54 | realize: function(rs, data){ |
---|
55 | if (Ext.isArray(rs)) { |
---|
56 | for (var i = rs.length - 1; i >= 0; i--) { |
---|
57 | // recurse |
---|
58 | if (Ext.isArray(data)) { |
---|
59 | this.realize(rs.splice(i,1).shift(), data.splice(i,1).shift()); |
---|
60 | } |
---|
61 | else { |
---|
62 | // weird...rs is an array but data isn't?? recurse but just send in the whole invalid data object. |
---|
63 | // the else clause below will detect !this.isData and throw exception. |
---|
64 | this.realize(rs.splice(i,1).shift(), data); |
---|
65 | } |
---|
66 | } |
---|
67 | } |
---|
68 | else { |
---|
69 | // If rs is NOT an array but data IS, see if data contains just 1 record. If so extract it and carry on. |
---|
70 | if (Ext.isArray(data) && data.length == 1) { |
---|
71 | data = data.shift(); |
---|
72 | } |
---|
73 | if (!this.isData(data)) { |
---|
74 | // TODO: Let exception-handler choose to commit or not rather than blindly rs.commit() here. |
---|
75 | //rs.commit(); |
---|
76 | throw new Ext.data.DataReader.Error('realize', rs); |
---|
77 | } |
---|
78 | this.buildExtractors(); |
---|
79 | var values = this.extractValues(data, rs.fields.items, rs.fields.items.length); |
---|
80 | rs.phantom = false; // <-- That's what it's all about |
---|
81 | rs._phid = rs.id; // <-- copy phantom-id -> _phid, so we can remap in Store#onCreateRecords |
---|
82 | rs.id = data[this.meta.idProperty]; |
---|
83 | rs.data = values; |
---|
84 | rs.commit(); |
---|
85 | } |
---|
86 | }, |
---|
87 | |
---|
88 | /** |
---|
89 | * Used for updating a non-phantom or "real" record's data with fresh data from server after remote-save. |
---|
90 | * You <b>must</b> return a complete new record from the server. If you don't, your local record's missing fields |
---|
91 | * will be populated with the default values specified in your Ext.data.Record.create specification. Without a defaultValue, |
---|
92 | * local fields will be populated with empty string "". So return your entire record's data after both remote create and update. |
---|
93 | * In addition, you <b>must</b> return record-data from the server in the same order received. |
---|
94 | * Will perform a commit as well, un-marking dirty-fields. Store's "update" event will be suppressed as the record receives |
---|
95 | * a fresh new data-hash. |
---|
96 | * @param {Record/Record[]} rs |
---|
97 | * @param {Object/Object[]} data |
---|
98 | */ |
---|
99 | update : function(rs, data) { |
---|
100 | if (Ext.isArray(rs)) { |
---|
101 | for (var i=rs.length-1; i >= 0; i--) { |
---|
102 | if (Ext.isArray(data)) { |
---|
103 | this.update(rs.splice(i,1).shift(), data.splice(i,1).shift()); |
---|
104 | } |
---|
105 | else { |
---|
106 | // weird...rs is an array but data isn't?? recurse but just send in the whole data object. |
---|
107 | // the else clause below will detect !this.isData and throw exception. |
---|
108 | this.update(rs.splice(i,1).shift(), data); |
---|
109 | } |
---|
110 | } |
---|
111 | } |
---|
112 | else { |
---|
113 | // If rs is NOT an array but data IS, see if data contains just 1 record. If so extract it and carry on. |
---|
114 | if (Ext.isArray(data) && data.length == 1) { |
---|
115 | data = data.shift(); |
---|
116 | } |
---|
117 | if (!this.isData(data)) { |
---|
118 | // TODO: create custom Exception class to return record in thrown exception. Allow exception-handler the choice |
---|
119 | // to commit or not rather than blindly rs.commit() here. |
---|
120 | rs.commit(); |
---|
121 | throw new Ext.data.DataReader.Error('update', rs); |
---|
122 | } |
---|
123 | this.buildExtractors(); |
---|
124 | rs.data = this.extractValues(Ext.apply(rs.data, data), rs.fields.items, rs.fields.items.length); |
---|
125 | rs.commit(); |
---|
126 | } |
---|
127 | }, |
---|
128 | |
---|
129 | /** |
---|
130 | * Returns true if the supplied data-hash <b>looks</b> and quacks like data. Checks to see if it has a key |
---|
131 | * corresponding to idProperty defined in your DataReader config containing non-empty pk. |
---|
132 | * @param {Object} data |
---|
133 | * @return {Boolean} |
---|
134 | */ |
---|
135 | isData : function(data) { |
---|
136 | return (data && Ext.isObject(data) && !Ext.isEmpty(data[this.meta.idProperty])) ? true : false; |
---|
137 | } |
---|
138 | }; |
---|
139 | |
---|
140 | /** |
---|
141 | * @class Ext.data.DataReader.Error |
---|
142 | * @extends Ext.Error |
---|
143 | * General error class for Ext.data.DataReader |
---|
144 | */ |
---|
145 | Ext.data.DataReader.Error = Ext.extend(Ext.Error, { |
---|
146 | constructor : function(message, arg) { |
---|
147 | this.arg = arg; |
---|
148 | Ext.Error.call(this, message); |
---|
149 | }, |
---|
150 | name: 'Ext.data.DataReader' |
---|
151 | }); |
---|
152 | Ext.apply(Ext.data.DataReader.Error.prototype, { |
---|
153 | lang : { |
---|
154 | 'update': "#update received invalid data from server. Please see docs for DataReader#update and review your DataReader configuration.", |
---|
155 | 'realize': "#realize was called with invalid remote-data. Please see the docs for DataReader#realize and review your DataReader configuration.", |
---|
156 | 'invalid-response': "#readResponse received an invalid response from the server." |
---|
157 | } |
---|
158 | }); |
---|
159 | |
---|
160 | |
---|