git.roojs.org Git - roojs1/blob - Roo/data/Record.js

   1 /*
   2  * Based on:
   3  * Ext JS Library 1.1.1
   4  * Copyright(c) 2006-2007, Ext JS, LLC.
   5  *
   6  * Originally Released Under LGPL - original licence link has changed is not relivant.
   7  *
   8  * Fork - LGPL
   9  * <script type="text/javascript">
  10  */
  11
  12 /**
  13 * @class Roo.data.Record
  14  * Instances of this class encapsulate both record <em>definition</em> information, and record
  15  * <em>value</em> information for use in {@link Roo.data.Store} objects, or any code which needs
  16  * to access Records cached in an {@link Roo.data.Store} object.<br>
  17  * <p>
  18  * Constructors for this class are generated by passing an Array of field definition objects to {@link #create}.
  19  * Instances are usually only created by {@link Roo.data.Reader} implementations when processing unformatted data
  20  * objects.<br>
  21  * <p>
  22  * Record objects generated by this constructor inherit all the methods of Roo.data.Record listed below.
  23  * @constructor
  24  * This constructor should not be used to create Record objects. Instead, use the constructor generated by
  25  * {@link #create}. The parameters are the same.
  26  * @param {Array} data An associative Array of data values keyed by the field name.
  27  * @param {Object} id (Optional) The id of the record. This id should be unique, and is used by the
  28  * {@link Roo.data.Store} object which owns the Record to index its collection of Records. If
  29  * not specified an integer id is generated.
  30  */
  31 Roo.data.Record = function(data, id){
  32     this.id = (id || id === 0) ? id : ++Roo.data.Record.AUTO_ID;
  33     this.data = data;
  34 };
  35
  36 /**
  37  * Generate a constructor for a specific record layout.
  38  * @param {Array} o An Array of field definition objects which specify field names, and optionally,
  39  * data types, and a mapping for an {@link Roo.data.Reader} to extract the field's value from a data object.
  40  * Each field definition object may contain the following properties: <ul>
  41  * <li><b>name</b> : String<p style="margin-left:1em">The name by which the field is referenced within the Record. This is referenced by,
  42  * for example the <em>dataIndex</em> property in column definition objects passed to {@link Roo.grid.ColumnModel}</p></li>
  43  * <li><b>mapping</b> : String<p style="margin-left:1em">(Optional) A path specification for use by the {@link Roo.data.Reader} implementation
  44  * that is creating the Record to access the data value from the data object. If an {@link Roo.data.JsonReader}
  45  * is being used, then this is a string containing the javascript expression to reference the data relative to
  46  * the record item's root. If an {@link Roo.data.XmlReader} is being used, this is an {@link Roo.DomQuery} path
  47  * to the data item relative to the record element. If the mapping expression is the same as the field name,
  48  * this may be omitted.</p></li>
  49  * <li><b>type</b> : String<p style="margin-left:1em">(Optional) The data type for conversion to displayable value. Possible values are
  50  * <ul><li>auto (Default, implies no conversion)</li>
  51  * <li>string</li>
  52  * <li>int</li>
  53  * <li>float</li>
  54  * <li>boolean</li>
  55  * <li>date</li></ul></p></li>
  56  * <li><b>sortType</b> : Mixed<p style="margin-left:1em">(Optional) A member of {@link Roo.data.SortTypes}.</p></li>
  57  * <li><b>sortDir</b> : String<p style="margin-left:1em">(Optional) Initial direction to sort. "ASC" or "DESC"</p></li>
  58  * <li><b>convert</b> : Function<p style="margin-left:1em">(Optional) A function which converts the value provided
  59  * by the Reader into an object that will be stored in the Record. It is passed the
  60  * following parameters:<ul>
  61  * <li><b>v</b> : Mixed<p style="margin-left:1em">The data value as read by the Reader.</p></li>
  62  * </ul></p></li>
  63  * <li><b>dateFormat</b> : String<p style="margin-left:1em">(Optional) A format String for the Date.parseDate function.</p></li>
  64  * </ul>
  65  * <br>usage:<br><pre><code>
  66 var TopicRecord = Roo.data.Record.create(
  67     {name: 'title', mapping: 'topic_title'},
  68     {name: 'author', mapping: 'username'},
  69     {name: 'totalPosts', mapping: 'topic_replies', type: 'int'},
  70     {name: 'lastPost', mapping: 'post_time', type: 'date'},
  71     {name: 'lastPoster', mapping: 'user2'},
  72     {name: 'excerpt', mapping: 'post_text'}
  73 );
  74
  75 var myNewRecord = new TopicRecord({
  76     title: 'Do my job please',
  77     author: 'noobie',
  78     totalPosts: 1,
  79     lastPost: new Date(),
  80     lastPoster: 'Animal',
  81     excerpt: 'No way dude!'
  82 });
  83 myStore.add(myNewRecord);
  84 </code></pre>
  85  * @method create
  86  * @static
  87  */
  88 Roo.data.Record.create = function(o){
  89     var f = function(){
  90         f.superclass.constructor.apply(this, arguments);
  91     };
  92     Roo.extend(f, Roo.data.Record);
  93     var p = f.prototype;
  94     p.fields = new Roo.util.MixedCollection(false, function(field){
  95         return field.name;
  96     });
  97     for(var i = 0, len = o.length; i < len; i++){
  98         p.fields.add(new Roo.data.Field(o[i]));
  99     }
 100     f.getField = function(name){
 101         return p.fields.get(name);
 102     };
 103     return f;
 104 };
 105
 106 Roo.data.Record.AUTO_ID = 1000;
 107 Roo.data.Record.EDIT = 'edit';
 108 Roo.data.Record.REJECT = 'reject';
 109 Roo.data.Record.COMMIT = 'commit';
 110
 111 Roo.data.Record.prototype = {
 112     /**
 113      * Readonly flag - true if this record has been modified.
 114      * @type Boolean
 115      */
 116     dirty : false,
 117     editing : false,
 118     error: null,
 119     modified: null,
 120
 121     // private
 122     join : function(store){
 123         this.store = store;
 124     },
 125
 126     /**
 127      * Set the named field to the specified value.
 128      * @param {String} name The name of the field to set.
 129      * @param {Object} value The value to set the field to.
 130      */
 131     set : function(name, value){
 132         if(this.data[name] == value){
 133             return;
 134         }
 135         this.dirty = true;
 136         if(!this.modified){
 137             this.modified = {};
 138         }
 139         if(typeof this.modified[name] == 'undefined'){
 140             this.modified[name] = this.data[name];
 141         }
 142         this.data[name] = value;
 143         if(!this.editing){
 144             this.store.afterEdit(this);
 145         }
 146     },
 147
 148     /**
 149      * Get the value of the named field.
 150      * @param {String} name The name of the field to get the value of.
 151      * @return {Object} The value of the field.
 152      */
 153     get : function(name){
 154         return this.data[name];
 155     },
 156
 157     // private
 158     beginEdit : function(){
 159         this.editing = true;
 160         this.modified = {};
 161     },
 162
 163     // private
 164     cancelEdit : function(){
 165         this.editing = false;
 166         delete this.modified;
 167     },
 168
 169     // private
 170     endEdit : function(){
 171         this.editing = false;
 172         if(this.dirty && this.store){
 173             this.store.afterEdit(this);
 174         }
 175     },
 176
 177     /**
 178      * Usually called by the {@link Roo.data.Store} which owns the Record.
 179      * Rejects all changes made to the Record since either creation, or the last commit operation.
 180      * Modified fields are reverted to their original values.
 181      * <p>
 182      * Developers should subscribe to the {@link Roo.data.Store#update} event to have their code notified
 183      * of reject operations.
 184      */
 185     reject : function(){
 186         var m = this.modified;
 187         for(var n in m){
 188             if(typeof m[n] != "function"){
 189                 this.data[n] = m[n];
 190             }
 191         }
 192         this.dirty = false;
 193         delete this.modified;
 194         this.editing = false;
 195         if(this.store){
 196             this.store.afterReject(this);
 197         }
 198     },
 199
 200     /**
 201      * Usually called by the {@link Roo.data.Store} which owns the Record.
 202      * Commits all changes made to the Record since either creation, or the last commit operation.
 203      * <p>
 204      * Developers should subscribe to the {@link Roo.data.Store#update} event to have their code notified
 205      * of commit operations.
 206      */
 207     commit : function(){
 208         this.dirty = false;
 209         delete this.modified;
 210         this.editing = false;
 211         if(this.store){
 212             this.store.afterCommit(this);
 213         }
 214     },
 215
 216     // private
 217     hasError : function(){
 218         return this.error != null;
 219     },
 220
 221     // private
 222     clearError : function(){
 223         this.error = null;
 224     },
 225
 226     /**
 227      * Creates a copy of this record.
 228      * @param {String} id (optional) A new record id if you don't want to use this record's id
 229      * @return {Record}
 230      */
 231     copy : function(newId) {
 232         return new this.constructor(Roo.apply({}, this.data), newId || this.id);
 233     }
 234 };