pkgs/data-xml-debug.js

   1 /*!
   2  * Ext JS Library 3.2.1
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.data.XmlWriter
   9  * @extends Ext.data.DataWriter
  10  * DataWriter extension for writing an array or single {@link Ext.data.Record} object(s) in preparation for executing a remote CRUD action via XML.
  11  * XmlWriter uses an instance of {@link Ext.XTemplate} for maximum flexibility in defining your own custom XML schema if the default schema is not appropriate for your needs.
  12  * See the {@link #tpl} configuration-property.
  13  */
  14 Ext.data.XmlWriter = function(params) {
  15     Ext.data.XmlWriter.superclass.constructor.apply(this, arguments);
  16     // compile the XTemplate for rendering XML documents.
  17     this.tpl = (typeof(this.tpl) === 'string') ? new Ext.XTemplate(this.tpl).compile() : this.tpl.compile();
  18 };
  19 Ext.extend(Ext.data.XmlWriter, Ext.data.DataWriter, {
  20     /**
  21      * @cfg {String} documentRoot [xrequest] (Optional) The name of the XML document root-node.  <b>Note:</b>
  22      * this parameter is required </b>only when</b> sending extra {@link Ext.data.Store#baseParams baseParams} to the server
  23      * during a write-request -- if no baseParams are set, the {@link Ext.data.XmlReader#record} meta-property can
  24      * suffice as the XML document root-node for write-actions involving just a <b>single record</b>.  For requests
  25      * involving <b>multiple</b> records and <b>NO</b> baseParams, the {@link Ext.data.XmlWriter#root} property can
  26      * act as the XML document root.
  27      */
  28     documentRoot: 'xrequest',
  29     /**
  30      * @cfg {Boolean} forceDocumentRoot [false] Set to <tt>true</tt> to force XML documents having a root-node as defined
  31      * by {@link #documentRoot}, even with no baseParams defined.
  32      */
  33     forceDocumentRoot: false,
  34     /**
  35      * @cfg {String} root [records] The name of the containing element which will contain the nodes of an write-action involving <b>multiple</b> records.  Each
  36      * xml-record written to the server will be wrapped in an element named after {@link Ext.data.XmlReader#record} property.
  37      * eg:
  38 <code><pre>
  39 &lt;?xml version="1.0" encoding="UTF-8"?>
  40 &lt;user>&lt;first>Barney&lt;/first>&lt;/user>
  41 </code></pre>
  42      * However, when <b>multiple</b> records are written in a batch-operation, these records must be wrapped in a containing
  43      * Element.
  44      * eg:
  45 <code><pre>
  46 &lt;?xml version="1.0" encoding="UTF-8"?>
  47     &lt;records>
  48         &lt;first>Barney&lt;/first>&lt;/user>
  49         &lt;records>&lt;first>Barney&lt;/first>&lt;/user>
  50     &lt;/records>
  51 </code></pre>
  52      * Defaults to <tt>records</tt>.  Do not confuse the nature of this property with that of {@link #documentRoot}
  53      */
  54     root: 'records',
  55     /**
  56      * @cfg {String} xmlVersion [1.0] The <tt>version</tt> written to header of xml documents.
  57 <code><pre>&lt;?xml version="1.0" encoding="ISO-8859-15"?></pre></code>
  58      */
  59     xmlVersion : '1.0',
  60     /**
  61      * @cfg {String} xmlEncoding [ISO-8859-15] The <tt>encoding</tt> written to header of xml documents.
  62 <code><pre>&lt;?xml version="1.0" encoding="ISO-8859-15"?></pre></code>
  63      */
  64     xmlEncoding: 'ISO-8859-15',
  65     /**
  66      * @cfg {String/Ext.XTemplate} tpl The XML template used to render {@link Ext.data.Api#actions write-actions} to your server.
  67      * <p>One can easily provide his/her own custom {@link Ext.XTemplate#constructor template-definition} if the default does not suffice.</p>
  68      * <p>Defaults to:</p>
  69 <code><pre>
  70 &lt;?xml version="{version}" encoding="{encoding}"?>
  71     &lt;tpl if="documentRoot">&lt;{documentRoot}>
  72     &lt;tpl for="baseParams">
  73         &lt;tpl for=".">
  74             &lt;{name}>{value}&lt;/{name}>
  75         &lt;/tpl>
  76     &lt;/tpl>
  77     &lt;tpl if="records.length &gt; 1">&lt;{root}>',
  78     &lt;tpl for="records">
  79         &lt;{parent.record}>
  80         &lt;tpl for=".">
  81             &lt;{name}>{value}&lt;/{name}>
  82         &lt;/tpl>
  83         &lt;/{parent.record}>
  84     &lt;/tpl>
  85     &lt;tpl if="records.length &gt; 1">&lt;/{root}>&lt;/tpl>
  86     &lt;tpl if="documentRoot">&lt;/{documentRoot}>&lt;/tpl>
  87 </pre></code>
  88      * <p>Templates will be called with the following API</p>
  89      * <ul>
  90      * <li>{String} version [1.0] The xml version.</li>
  91      * <li>{String} encoding [ISO-8859-15] The xml encoding.</li>
  92      * <li>{String/false} documentRoot The XML document root-node name or <tt>false</tt> if not required.  See {@link #documentRoot} and {@link #forceDocumentRoot}.</li>
  93      * <li>{String} record The meta-data parameter defined on your {@link Ext.data.XmlReader#record} configuration represents the name of the xml-tag containing each record.</li>
  94      * <li>{String} root The meta-data parameter defined by {@link Ext.data.XmlWriter#root} configuration-parameter.  Represents the name of the xml root-tag when sending <b>multiple</b> records to the server.</li>
  95      * <li>{Array} records The records being sent to the server, ie: the subject of the write-action being performed.  The records parameter will be always be an array, even when only a single record is being acted upon.
  96      *     Each item within the records array will contain an array of field objects having the following properties:
  97      *     <ul>
  98      *         <li>{String} name The field-name of the record as defined by your {@link Ext.data.Record#create Ext.data.Record definition}.  The "mapping" property will be used, otherwise it will match the "name" property.  Use this parameter to define the XML tag-name of the property.</li>
  99      *         <li>{Mixed} value The record value of the field enclosed within XML tags specified by name property above.</li>
 100      *     </ul></li>
 101      * <li>{Array} baseParams.  The baseParams as defined upon {@link Ext.data.Store#baseParams}.  Note that the baseParams have been converted into an array of [{name : "foo", value: "bar"}, ...] pairs in the same manner as the <b>records</b> parameter above.  See {@link #documentRoot} and {@link #forceDocumentRoot}.</li>
 102      * </ul>
 103      */
 104     // Encoding the ? here in case it's being included by some kind of page that will parse it (eg. PHP)
 105     tpl: '<tpl for="."><\u003fxml version="{version}" encoding="{encoding}"\u003f><tpl if="documentRoot"><{documentRoot}><tpl for="baseParams"><tpl for="."><{name}>{value}</{name}</tpl></tpl></tpl><tpl if="records.length&gt;1"><{root}></tpl><tpl for="records"><{parent.record}><tpl for="."><{name}>{value}</{name}></tpl></{parent.record}></tpl><tpl if="records.length&gt;1"></{root}></tpl><tpl if="documentRoot"></{documentRoot}></tpl></tpl>',
 106
 107
 108     /**
 109      * XmlWriter implementation of the final stage of a write action.
 110      * @param {Object} params Transport-proxy's (eg: {@link Ext.Ajax#request}) params-object to write-to.
 111      * @param {Object} baseParams as defined by {@link Ext.data.Store#baseParams}.  The baseParms must be encoded by the extending class, eg: {@link Ext.data.JsonWriter}, {@link Ext.data.XmlWriter}.
 112      * @param {Object/Object[]} data Data-object representing the compiled Store-recordset.
 113      */
 114     render : function(params, baseParams, data) {
 115         baseParams = this.toArray(baseParams);
 116         params.xmlData = this.tpl.applyTemplate({
 117             version: this.xmlVersion,
 118             encoding: this.xmlEncoding,
 119             documentRoot: (baseParams.length > 0 || this.forceDocumentRoot === true) ? this.documentRoot : false,
 120             record: this.meta.record,
 121             root: this.root,
 122             baseParams: baseParams,
 123             records: (Ext.isArray(data[0])) ? data : [data]
 124         });
 125     },
 126
 127     /**
 128      * createRecord
 129      * @protected
 130      * @param {Ext.data.Record} rec
 131      * @return {Array} Array of <tt>name:value</tt> pairs for attributes of the {@link Ext.data.Record}.  See {@link Ext.data.DataWriter#toHash}.
 132      */
 133     createRecord : function(rec) {
 134         return this.toArray(this.toHash(rec));
 135     },
 136
 137     /**
 138      * updateRecord
 139      * @protected
 140      * @param {Ext.data.Record} rec
 141      * @return {Array} Array of {name:value} pairs for attributes of the {@link Ext.data.Record}.  See {@link Ext.data.DataWriter#toHash}.
 142      */
 143     updateRecord : function(rec) {
 144         return this.toArray(this.toHash(rec));
 145
 146     },
 147     /**
 148      * destroyRecord
 149      * @protected
 150      * @param {Ext.data.Record} rec
 151      * @return {Array} Array containing a attribute-object (name/value pair) representing the {@link Ext.data.DataReader#idProperty idProperty}.
 152      */
 153     destroyRecord : function(rec) {
 154         var data = {};
 155         data[this.meta.idProperty] = rec.id;
 156         return this.toArray(data);
 157     }
 158 });
 159 /**
 160  * @class Ext.data.XmlReader
 161  * @extends Ext.data.DataReader
 162  * <p>Data reader class to create an Array of {@link Ext.data.Record} objects from an XML document
 163  * based on mappings in a provided {@link Ext.data.Record} constructor.</p>
 164  * <p><b>Note</b>: that in order for the browser to parse a returned XML document, the Content-Type
 165  * header in the HTTP response must be set to "text/xml" or "application/xml".</p>
 166  * <p>Example code:</p>
 167  * <pre><code>
 168 var Employee = Ext.data.Record.create([
 169    {name: 'name', mapping: 'name'},     // "mapping" property not needed if it is the same as "name"
 170    {name: 'occupation'}                 // This field will use "occupation" as the mapping.
 171 ]);
 172 var myReader = new Ext.data.XmlReader({
 173    totalProperty: "results", // The element which contains the total dataset size (optional)
 174    record: "row",           // The repeated element which contains row information
 175    idProperty: "id"         // The element within the row that provides an ID for the record (optional)
 176    messageProperty: "msg"   // The element within the response that provides a user-feedback message (optional)
 177 }, Employee);
 178 </code></pre>
 179  * <p>
 180  * This would consume an XML file like this:
 181  * <pre><code>
 182 &lt;?xml version="1.0" encoding="UTF-8"?>
 183 &lt;dataset>
 184  &lt;results>2&lt;/results>
 185  &lt;row>
 186    &lt;id>1&lt;/id>
 187    &lt;name>Bill&lt;/name>
 188    &lt;occupation>Gardener&lt;/occupation>
 189  &lt;/row>
 190  &lt;row>
 191    &lt;id>2&lt;/id>
 192    &lt;name>Ben&lt;/name>
 193    &lt;occupation>Horticulturalist&lt;/occupation>
 194  &lt;/row>
 195 &lt;/dataset>
 196 </code></pre>
 197  * @cfg {String} totalProperty The DomQuery path from which to retrieve the total number of records
 198  * in the dataset. This is only needed if the whole dataset is not passed in one go, but is being
 199  * paged from the remote server.
 200  * @cfg {String} record The DomQuery path to the repeated element which contains record information.
 201  * @cfg {String} record The DomQuery path to the repeated element which contains record information.
 202  * @cfg {String} successProperty The DomQuery path to the success attribute used by forms.
 203  * @cfg {String} idPath The DomQuery path relative from the record element to the element that contains
 204  * a record identifier value.
 205  * @constructor
 206  * Create a new XmlReader.
 207  * @param {Object} meta Metadata configuration options
 208  * @param {Object} recordType Either an Array of field definition objects as passed to
 209  * {@link Ext.data.Record#create}, or a Record constructor object created using {@link Ext.data.Record#create}.
 210  */
 211 Ext.data.XmlReader = function(meta, recordType){
 212     meta = meta || {};
 213
 214     // backwards compat, convert idPath or id / success
 215     Ext.applyIf(meta, {
 216         idProperty: meta.idProperty || meta.idPath || meta.id,
 217         successProperty: meta.successProperty || meta.success
 218     });
 219
 220     Ext.data.XmlReader.superclass.constructor.call(this, meta, recordType || meta.fields);
 221 };
 222 Ext.extend(Ext.data.XmlReader, Ext.data.DataReader, {
 223     /**
 224      * This method is only used by a DataProxy which has retrieved data from a remote server.
 225      * @param {Object} response The XHR object which contains the parsed XML document.  The response is expected
 226      * to contain a property called <tt>responseXML</tt> which refers to an XML document object.
 227      * @return {Object} records A data block which is used by an {@link Ext.data.Store} as
 228      * a cache of Ext.data.Records.
 229      */
 230     read : function(response){
 231         var doc = response.responseXML;
 232         if(!doc) {
 233             throw {message: "XmlReader.read: XML Document not available"};
 234         }
 235         return this.readRecords(doc);
 236     },
 237
 238     /**
 239      * Create a data block containing Ext.data.Records from an XML document.
 240      * @param {Object} doc A parsed XML document.
 241      * @return {Object} records A data block which is used by an {@link Ext.data.Store} as
 242      * a cache of Ext.data.Records.
 243      */
 244     readRecords : function(doc){
 245         /**
 246          * After any data loads/reads, the raw XML Document is available for further custom processing.
 247          * @type XMLDocument
 248          */
 249         this.xmlData = doc;
 250
 251         var root    = doc.documentElement || doc,
 252             q       = Ext.DomQuery,
 253             totalRecords = 0,
 254             success = true;
 255
 256         if(this.meta.totalProperty){
 257             totalRecords = this.getTotal(root, 0);
 258         }
 259         if(this.meta.successProperty){
 260             success = this.getSuccess(root);
 261         }
 262
 263         var records = this.extractData(q.select(this.meta.record, root), true); // <-- true to return Ext.data.Record[]
 264
 265         // TODO return Ext.data.Response instance.  @see #readResponse
 266         return {
 267             success : success,
 268             records : records,
 269             totalRecords : totalRecords || records.length
 270         };
 271     },
 272
 273     /**
 274      * Decode an XML response from server.
 275      * @param {String} action [{@link Ext.data.Api#actions} create|read|update|destroy]
 276      * @param {Object} response HTTP Response object from browser.
 277      * @return {Ext.data.Response} An instance of {@link Ext.data.Response}
 278      */
 279     readResponse : function(action, response) {
 280         var q   = Ext.DomQuery,
 281         doc     = response.responseXML;
 282
 283         // create general Response instance.
 284         var res = new Ext.data.Response({
 285             action: action,
 286             success : this.getSuccess(doc),
 287             message: this.getMessage(doc),
 288             data: this.extractData(q.select(this.meta.record, doc) || q.select(this.meta.root, doc), false),
 289             raw: doc
 290         });
 291
 292         if (Ext.isEmpty(res.success)) {
 293             throw new Ext.data.DataReader.Error('successProperty-response', this.meta.successProperty);
 294         }
 295
 296         // Create actions from a response having status 200 must return pk
 297         if (action === Ext.data.Api.actions.create) {
 298             var def = Ext.isDefined(res.data);
 299             if (def && Ext.isEmpty(res.data)) {
 300                 throw new Ext.data.JsonReader.Error('root-empty', this.meta.root);
 301             }
 302             else if (!def) {
 303                 throw new Ext.data.JsonReader.Error('root-undefined-response', this.meta.root);
 304             }
 305         }
 306         return res;
 307     },
 308
 309     getSuccess : function() {
 310         return true;
 311     },
 312
 313     /**
 314      * build response-data extractor functions.
 315      * @private
 316      * @ignore
 317      */
 318     buildExtractors : function() {
 319         if(this.ef){
 320             return;
 321         }
 322         var s       = this.meta,
 323             Record  = this.recordType,
 324             f       = Record.prototype.fields,
 325             fi      = f.items,
 326             fl      = f.length;
 327
 328         if(s.totalProperty) {
 329             this.getTotal = this.createAccessor(s.totalProperty);
 330         }
 331         if(s.successProperty) {
 332             this.getSuccess = this.createAccessor(s.successProperty);
 333         }
 334         if (s.messageProperty) {
 335             this.getMessage = this.createAccessor(s.messageProperty);
 336         }
 337         this.getRoot = function(res) {
 338             return (!Ext.isEmpty(res[this.meta.record])) ? res[this.meta.record] : res[this.meta.root];
 339         };
 340         if (s.idPath || s.idProperty) {
 341             var g = this.createAccessor(s.idPath || s.idProperty);
 342             this.getId = function(rec) {
 343                 var id = g(rec) || rec.id;
 344                 return (id === undefined || id === '') ? null : id;
 345             };
 346         } else {
 347             this.getId = function(){return null;};
 348         }
 349         var ef = [];
 350         for(var i = 0; i < fl; i++){
 351             f = fi[i];
 352             var map = (f.mapping !== undefined && f.mapping !== null) ? f.mapping : f.name;
 353             ef.push(this.createAccessor(map));
 354         }
 355         this.ef = ef;
 356     },
 357
 358     /**
 359      * Creates a function to return some particular key of data from a response.
 360      * @param {String} key
 361      * @return {Function}
 362      * @private
 363      * @ignore
 364      */
 365     createAccessor : function(){
 366         var q = Ext.DomQuery;
 367         return function(key) {
 368             switch(key) {
 369                 case this.meta.totalProperty:
 370                     return function(root, def){
 371                         return q.selectNumber(key, root, def);
 372                     };
 373                     break;
 374                 case this.meta.successProperty:
 375                     return function(root, def) {
 376                         var sv = q.selectValue(key, root, true);
 377                         var success = sv !== false && sv !== 'false';
 378                         return success;
 379                     };
 380                     break;
 381                 default:
 382                     return function(root, def) {
 383                         return q.selectValue(key, root, def);
 384                     };
 385                     break;
 386             }
 387         };
 388     }(),
 389
 390     /**
 391      * extracts values and type-casts a row of data from server, extracted by #extractData
 392      * @param {Hash} data
 393      * @param {Ext.data.Field[]} items
 394      * @param {Number} len
 395      * @private
 396      * @ignore
 397      */
 398     extractValues : function(data, items, len) {
 399         var f, values = {};
 400         for(var j = 0; j < len; j++){
 401             f = items[j];
 402             var v = this.ef[j](data);
 403             values[f.name] = f.convert((v !== undefined) ? v : f.defaultValue, data);
 404         }
 405         return values;
 406     }
 407 });/**
 408  * @class Ext.data.XmlStore
 409  * @extends Ext.data.Store
 410  * <p>Small helper class to make creating {@link Ext.data.Store}s from XML data easier.
 411  * A XmlStore will be automatically configured with a {@link Ext.data.XmlReader}.</p>
 412  * <p>A store configuration would be something like:<pre><code>
 413 var store = new Ext.data.XmlStore({
 414     // store configs
 415     autoDestroy: true,
 416     storeId: 'myStore',
 417     url: 'sheldon.xml', // automatically configures a HttpProxy
 418     // reader configs
 419     record: 'Item', // records will have an "Item" tag
 420     idPath: 'ASIN',
 421     totalRecords: '@TotalResults'
 422     fields: [
 423         // set up the fields mapping into the xml doc
 424         // The first needs mapping, the others are very basic
 425         {name: 'Author', mapping: 'ItemAttributes > Author'},
 426         'Title', 'Manufacturer', 'ProductGroup'
 427     ]
 428 });
 429  * </code></pre></p>
 430  * <p>This store is configured to consume a returned object of the form:<pre><code>
 431 &#60?xml version="1.0" encoding="UTF-8"?>
 432 &#60ItemSearchResponse xmlns="http://webservices.amazon.com/AWSECommerceService/2009-05-15">
 433     &#60Items>
 434         &#60Request>
 435             &#60IsValid>True&#60/IsValid>
 436             &#60ItemSearchRequest>
 437                 &#60Author>Sidney Sheldon&#60/Author>
 438                 &#60SearchIndex>Books&#60/SearchIndex>
 439             &#60/ItemSearchRequest>
 440         &#60/Request>
 441         &#60TotalResults>203&#60/TotalResults>
 442         &#60TotalPages>21&#60/TotalPages>
 443         &#60Item>
 444             &#60ASIN>0446355453&#60/ASIN>
 445             &#60DetailPageURL>
 446                 http://www.amazon.com/
 447             &#60/DetailPageURL>
 448             &#60ItemAttributes>
 449                 &#60Author>Sidney Sheldon&#60/Author>
 450                 &#60Manufacturer>Warner Books&#60/Manufacturer>
 451                 &#60ProductGroup>Book&#60/ProductGroup>
 452                 &#60Title>Master of the Game&#60/Title>
 453             &#60/ItemAttributes>
 454         &#60/Item>
 455     &#60/Items>
 456 &#60/ItemSearchResponse>
 457  * </code></pre>
 458  * An object literal of this form could also be used as the {@link #data} config option.</p>
 459  * <p><b>Note:</b> Although not listed here, this class accepts all of the configuration options of
 460  * <b>{@link Ext.data.XmlReader XmlReader}</b>.</p>
 461  * @constructor
 462  * @param {Object} config
 463  * @xtype xmlstore
 464  */
 465 Ext.data.XmlStore = Ext.extend(Ext.data.Store, {
 466     /**
 467      * @cfg {Ext.data.DataReader} reader @hide
 468      */
 469     constructor: function(config){
 470         Ext.data.XmlStore.superclass.constructor.call(this, Ext.apply(config, {
 471             reader: new Ext.data.XmlReader(config)
 472         }));
 473     }
 474 });
 475 Ext.reg('xmlstore', Ext.data.XmlStore);