Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / output / Ext.data.Record.html
index c1b390d..a95a8b4 100644 (file)
@@ -1,4 +1,4 @@
-<div class="body-wrap" xmlns:ext="http://www.extjs.com"><div class="top-tools"><a class="inner-link" href="#Ext.data.Record-props"><img src="resources/images/default/s.gif" class="item-icon icon-prop">Properties</a>&#13;<a class="inner-link" href="#Ext.data.Record-methods"><img src="resources/images/default/s.gif" class="item-icon icon-method">Methods</a>&#13;<a class="inner-link" href="#Ext.data.Record-events"><img src="resources/images/default/s.gif" class="item-icon icon-event">Events</a>&#13;<a class="bookmark" href="../docs/?class=Ext.data.Record"><img src="resources/images/default/s.gif" class="item-icon icon-fav">Direct Link</a>&#13;</div><h1>Class <a href="source/Record.html#cls-Ext.data.Record">Ext.data.Record</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">Record.js</td></tr><tr><td class="label">Class:</td><td class="hd-info"><a href="source/Record.html#cls-Ext.data.Record">Record</a></td></tr><tr><td class="label">Extends:</td><td class="hd-info">Object</td></tr></table><div class="description"><p>Instances of this class encapsulate both Record <em>definition</em> information, and Record
+<div class="body-wrap" xmlns:ext="http://www.extjs.com"><div class="top-tools"><a class="inner-link" href="#Ext.data.Record-props"><img src="../resources/images/default/s.gif" class="item-icon icon-prop">Properties</a>&#13;<a class="inner-link" href="#Ext.data.Record-methods"><img src="../resources/images/default/s.gif" class="item-icon icon-method">Methods</a>&#13;<a class="inner-link" href="#Ext.data.Record-events"><img src="../resources/images/default/s.gif" class="item-icon icon-event">Events</a>&#13;<a class="bookmark" href="../docs/?class=Ext.data.Record"><img src="../resources/images/default/s.gif" class="item-icon icon-fav">Direct Link</a>&#13;</div><h1>Class <a href="source/Record.html#cls-Ext.data.Record">Ext.data.Record</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"><a href="source/Record.html#cls-Ext.data.Record">Record.js</a></td></tr><tr><td class="label">Class:</td><td class="hd-info"><a href="source/Record.html#cls-Ext.data.Record">Record</a></td></tr><tr><td class="label">Extends:</td><td class="hd-info">Object</td></tr></table><div class="description"><p>Instances of this class encapsulate both Record <em>definition</em> information, and Record
 <em>value</em> information for use in <a href="output/Ext.data.Store.html" ext:cls="Ext.data.Store">Ext.data.Store</a> objects, or any code which needs
 to access Records cached in an <a href="output/Ext.data.Store.html" ext:cls="Ext.data.Store">Ext.data.Store</a> object.</p>
 <p>Constructors for this class are generated by passing an Array of field definition objects to <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">create</a>.
@@ -17,20 +17,26 @@ is represented by a property of that name in this object. Note that unless you s
 with <a href="output/Ext.data.Field.html#Ext.data.Field-name" ext:member="name" ext:cls="Ext.data.Field">name</a> "id" in the Record definition, this will <b>not</b> contain
 an <tt>id</tt> property.</div></div></td><td class="msource">Record</td></tr><tr class="property-row  "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Record-dirty"></a><b><a href="source/Record.html#prop-Ext.data.Record-dirty">dirty</a></b> : Boolean<div class="mdesc">Readonly flag - true if this Record has been modified.</div></td><td class="msource">Record</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.Record-fields"></a><b><a href="source/Record.html#prop-Ext.data.Record-fields">fields</a></b> : Ext.util.MixedCollection<div class="mdesc"><div class="short">This property is stored in the Record definition's prototype
 A MixedCollection containing the defined Fields for this...</div><div class="long"><p><b>This property is stored in the Record definition's <u>prototype</u></b></p>
-A MixedCollection containing the defined <a href="output/Ext.data.Field.html" ext:cls="Ext.data.Field">Field</a>s for this Record.  Read-only.</div></div></td><td class="msource">Record</td></tr><tr class="property-row  "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Record-id"></a><b><a href="source/Record.html#prop-Ext.data.Record-id">id</a></b> : Object<div class="mdesc">The unique ID of the Record <a href="output/Ext.data.Record.html#Ext.data.Record-Record" ext:member="Record" ext:cls="Ext.data.Record">as specified at construction time</a>.</div></td><td class="msource">Record</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.Record-modified"></a><b><a href="source/Record.html#prop-Ext.data.Record-modified">modified</a></b> : Object<div class="mdesc"><div class="short">This object contains a key and value storing the original values of all modified
+A MixedCollection containing the defined <a href="output/Ext.data.Field.html" ext:cls="Ext.data.Field">Field</a>s for this Record.  Read-only.</div></div></td><td class="msource">Record</td></tr><tr class="property-row  "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Record-id"></a><b><a href="source/Record.html#prop-Ext.data.Record-id">id</a></b> : Object<div class="mdesc">The unique ID of the Record <a href="output/Ext.data.Record.html#Ext.data.Record-Record" ext:member="Record" ext:cls="Ext.data.Record">as specified at construction time</a>.</div></td><td class="msource">Record</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.Record-json"></a><b><a href="source/Record.html#prop-Ext.data.Record-json">json</a></b> : Array|Object<div class="mdesc"><div class="short">Only present if this Record was created by an ArrayReader or a JsonReader.
+The Array or object which was the source o...</div><div class="long"><p><b>Only present if this Record was created by an <a href="output/Ext.data.ArrayReader.html" ext:cls="Ext.data.ArrayReader">ArrayReader</a> or a <a href="output/Ext.data.JsonReader.html" ext:cls="Ext.data.JsonReader">JsonReader</a></b>.</p>
+<p>The Array or object which was the source of the data for this Record.</p></div></div></td><td class="msource">Record</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.Record-modified"></a><b><a href="source/Record.html#prop-Ext.data.Record-modified">modified</a></b> : Object<div class="mdesc"><div class="short">This object contains a key and value storing the original values of all modified
 fields or is null if no fields have ...</div><div class="long">This object contains a key and value storing the original values of all modified
-fields or is null if no fields have been modified.</div></div></td><td class="msource">Record</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.Record-phantom"></a><b><a href="source/Record.html#prop-Ext.data.Record-phantom">phantom</a></b> : Boolean<div class="mdesc"><div class="short">false when the record does not yet exist in a server-side database (see
-markDirty).  Any record which has a real data...</div><div class="long"><tt>false</tt> when the record does not yet exist in a server-side database (see
+fields or is null if no fields have been modified.</div></div></td><td class="msource">Record</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.Record-node"></a><b><a href="source/Record.html#prop-Ext.data.Record-node">node</a></b> : XMLElement<div class="mdesc"><div class="short">Only present if this Record was created by an XmlReader.
+The XML element which was the source of the data for this Re...</div><div class="long"><p><b>Only present if this Record was created by an <a href="output/Ext.data.XmlReader.html" ext:cls="Ext.data.XmlReader">XmlReader</a></b>.</p>
+<p>The XML element which was the source of the data for this Record.</p></div></div></td><td class="msource">Record</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.Record-phantom"></a><b><a href="source/Record.html#prop-Ext.data.Record-phantom">phantom</a></b> : Boolean<div class="mdesc"><div class="short">true when the record does not yet exist in a server-side database (see
+markDirty).  Any record which has a real datab...</div><div class="long"><tt>true</tt> when the record does not yet exist in a server-side database (see
 <a href="output/Ext.data.Record.html#Ext.data.Record-markDirty" ext:member="markDirty" ext:cls="Ext.data.Record">markDirty</a>).  Any record which has a real database pk set as its id property
 is NOT a phantom -- it's real.</div></div></td><td class="msource">Record</td></tr><tr class="property-row  "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Record-store"></a><b><a href="source/Record.html#prop-Ext.data.Record-store">store</a></b> : Ext.data.Store<div class="mdesc">The <a href="output/Ext.data.Store.html" ext:cls="Ext.data.Store">Ext.data.Store</a> to which this Record belongs.</div></td><td class="msource">Record</td></tr></tbody></table><a id="Ext.data.Record-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.Record-Record"></a><b><a href="source/Record.html#cls-Ext.data.Record">Record</a></b>(&nbsp;<span title="Optional" class="optional">[<code>Object&nbsp;data</code>]</span>,&nbsp;<span title="Optional" class="optional">[<code>Object&nbsp;id</code>]</span>&nbsp;)
     <div class="mdesc"><div class="short">This constructor should not be used to create Record objects. Instead, use create to
-generate a subclass of Ext.data....</div><div class="long">This constructor should not be used to create Record objects. Instead, use <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">create</a> to
-generate a subclass of Ext.data.Record configured with information about its constituent fields.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>data</code> : Object<div class="sub-desc">(Optional) An object, the properties of which provide values for the new Record's
+generate a subclass of Ext.data....</div><div class="long"><p>This constructor should not be used to create Record objects. Instead, use <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">create</a> to
+generate a subclass of Ext.data.Record configured with information about its constituent fields.<p>
+<p><b>The generated constructor has the same signature as this constructor.</b></p><div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>data</code> : Object<div class="sub-desc">(Optional) An object, the properties of which provide values for the new Record's
 fields. If not specified the <code><a href="output/Ext.data.Field.html#Ext.data.Field-defaultValue" ext:member="defaultValue" ext:cls="Ext.data.Field">defaultValue</a></code>
-for each field will be assigned.</div></li><li><code>id</code> : Object<div class="sub-desc">(Optional) The id of the Record. This id should be unique, and is used by the
-<a href="output/Ext.data.Store.html" ext:cls="Ext.data.Store">Ext.data.Store</a> object which owns the Record to index its collection of Records. If
-an <code>id</code> is not specified a <b><code><a href="output/Ext.data.Record.html#Ext.data.Record-phantom" ext:member="phantom" ext:cls="Ext.data.Record">phantom</a></code></b> Record will be created
-with an <a href="output/Ext.data.Record.html#Ext.data.Record-Record.id" ext:member="Record.id" ext:cls="Ext.data.Record">automatically generated id</a>.</div></li></ul><strong>Returns:</strong><ul><li>void</li></ul></div></div></div></td><td class="msource">Record</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.Record-Record.id"></a><b><a href="source/Record.html#method-Ext.data.Record-Record.id">Record.id</a></b>(&nbsp;<code>Record&nbsp;rec</code>&nbsp;)
+for each field will be assigned.</div></li><li><code>id</code> : Object<div class="sub-desc">(Optional) The id of the Record. The id is used by the
+<a href="output/Ext.data.Store.html" ext:cls="Ext.data.Store">Ext.data.Store</a> object which owns the Record to index its collection
+of Records (therefore this id should be unique within each store). If an
+<code>id</code> is not specified a <b><code><a href="output/Ext.data.Record.html#Ext.data.Record-phantom" ext:member="phantom" ext:cls="Ext.data.Record">phantom</a></code></b>
+Record will be created with an <a href="output/Ext.data.Record.html#Ext.data.Record-Record.id" ext:member="Record.id" ext:cls="Ext.data.Record">automatically generated id</a>.</div></li></ul><strong>Returns:</strong><ul><li>void</li></ul></div></div></div></td><td class="msource">Record</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.Record-Record.id"></a><b><a href="source/Record.html#method-Ext.data.Record-Record.id">Record.id</a></b>(&nbsp;<code>Record&nbsp;rec</code>&nbsp;)
     :
                                         String<div class="mdesc"><div class="short">Generates a sequential id. This method is typically called when a record is created
 and no id has been specified. The...</div><div class="long">Generates a sequential id. This method is typically called when a record is <a href="output/Ext.data.Record.html#Ext.data.Record-create" ext:member="create" ext:cls="Ext.data.Record">create</a>d
@@ -57,11 +63,12 @@ Commits all changes made to the Record since either creation, or the last commit
 to have their code notified of commit operations.</p><div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>silent</code> : Boolean<div class="sub-desc">(optional) True to skip notification of the owning
 store of the change (defaults to false)</div></li></ul><strong>Returns:</strong><ul><li>void</li></ul></div></div></div></td><td class="msource">Record</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.Record-copy"></a><b><a href="source/Record.html#method-Ext.data.Record-copy">copy</a></b>(&nbsp;<span title="Optional" class="optional">[<code>String&nbsp;id</code>]</span>&nbsp;)
     :
-                                        Record<div class="mdesc"><div class="short">Creates a copy of this Record.</div><div class="long">Creates a copy of this Record.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>id</code> : String<div class="sub-desc">(optional) A new Record id, defaults to <a href="output/Ext.data.Record.html#Ext.data.Record-Record.id" ext:member="Record.id" ext:cls="Ext.data.Record">autogenerating an id</a>.
-Note: if an <code>id</code> is not specified the copy created will be a
-<code><a href="output/Ext.data.Record.html#Ext.data.Record-phantom" ext:member="phantom" ext:cls="Ext.data.Record">phantom</a></code> Record.</div></li></ul><strong>Returns:</strong><ul><li><code>Record</code><div class="sub-desc"></div></li></ul></div></div></div></td><td class="msource">Record</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.Record-create"></a><b><a href="source/Record.html#method-Ext.data.Record-create">create</a></b>(&nbsp;<code>Array&nbsp;o</code>&nbsp;)
+                                        Record<div class="mdesc"><div class="short">Creates a copy (clone) of this Record.</div><div class="long">Creates a copy (clone) of this Record.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>id</code> : String<div class="sub-desc">(optional) A new Record id, defaults to the id
+of the record being copied. See <code><a href="output/Ext.data.Record.html#Ext.data.Record-id" ext:member="id" ext:cls="Ext.data.Record">id</a></code>. 
+To generate a phantom record with a new id use:<pre><code><b>var</b> rec = record.copy(); <i>// clone the record</i>
+Ext.data.Record.id(rec); <i>// automatically generate a unique sequential id</i></code></pre></div></li></ul><strong>Returns:</strong><ul><li><code>Record</code><div class="sub-desc"></div></li></ul></div></div></div></td><td class="msource">Record</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.Record-create"></a><b><a href="source/Record.html#method-Ext.data.Record-create">create</a></b>(&nbsp;<code>Array&nbsp;o</code>&nbsp;)
     :
-                                        function<div class="mdesc"><div class="short">&lt;static&gt;&nbsp;Generate a constructor for a specific Record layout.</div><div class="long">&lt;static&gt;&nbsp;Generate a constructor for a specific Record layout.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>o</code> : Array<div class="sub-desc">An Array of <b><a href="output/Ext.data.Field.html" ext:cls="Ext.data.Field">Field</a></b> definition objects.
+                                        Function<div class="mdesc"><div class="short">&lt;static&gt;&nbsp;Generate a constructor for a specific Record layout.</div><div class="long">&lt;static&gt;&nbsp;Generate a constructor for a specific Record layout.<div class="mdetail-params"><strong>Parameters:</strong><ul><li><code>o</code> : Array<div class="sub-desc">An Array of <b><a href="output/Ext.data.Field.html" ext:cls="Ext.data.Field">Field</a></b> definition objects.
 The constructor generated by this method may be used to create new Record instances. The data
 object must contain properties named after the <a href="output/Ext.data.Field.html" ext:cls="Ext.data.Field">field</a>
 <b><tt><a href="output/Ext.data.Field.html#Ext.data.Field-name" ext:member="name" ext:cls="Ext.data.Field">Ext.data.Field.name</a>s</tt></b>.  Example usage:<pre><code><i>// create a Record constructor from a description of the fields</i>
@@ -90,8 +97,8 @@ object must contain properties named after the <a href="output/Ext.data.Field.ht
     },
     id <i>// optionally specify the id of the record otherwise <a href="output/Ext.data.Record.html#Ext.data.Record-Record.id" ext:member="Record.id" ext:cls="Ext.data.Record">one is auto-assigned</a></i>
 );
-myStore.<a href="output/Ext.data.Store.html#Ext.data.Store-add" ext:member="add" ext:cls="Ext.data.Store">add</a>(myNewRecord);</code></pre></div></li></ul><strong>Returns:</strong><ul><li><code>function</code><div class="sub-desc">A constructor which is used to create new Records according
-to the definition. The constructor has the same signature as {@link #Ext.data.Record}.</div></li></ul></div></div></div></td><td class="msource">Record</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.Record-endEdit"></a><b><a href="source/Record.html#method-Ext.data.Record-endEdit">endEdit</a></b>()
+myStore.<a href="output/Ext.data.Store.html#Ext.data.Store-add" ext:member="add" ext:cls="Ext.data.Store">add</a>(myNewRecord);</code></pre></div></li></ul><strong>Returns:</strong><ul><li><code>Function</code><div class="sub-desc">A constructor which is used to create new Records according
+to the definition. The constructor has the same signature as {@link #Record}.</div></li></ul></div></div></div></td><td class="msource">Record</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.Record-endEdit"></a><b><a href="source/Record.html#method-Ext.data.Record-endEdit">endEdit</a></b>()
     :
                                         void<div class="mdesc"><div class="short">End an edit. If any data was modified, the containing store is notified
 (ie, the store's update event will fire).</div><div class="long">End an edit. If any data was modified, the containing store is notified
@@ -150,7 +157,7 @@ rec.<a href="output/Ext.data.Record.html#Ext.data.Record-commit" ext:member="com
 
 <i>// update the record <b>in</b> the store, bypass setting dirty flag,</i>
 <i>// and <b>do</b> not store the change <b>in</b> the <a href="output/Ext.data.Store.html#Ext.data.Store-getModifiedRecords" ext:member="getModifiedRecords" ext:cls="Ext.data.Store">modified records</a></i>
-rec.<a href="output/Ext.data.Record.html#Ext.data.Record-data" ext:member="data" ext:cls="Ext.data.Record">data</a>[<em>'firstname'</em>] = <em>'Wilma'</em>); <i>// updates record, but not the view</i>
+rec.<a href="output/Ext.data.Record.html#Ext.data.Record-data" ext:member="data" ext:cls="Ext.data.Record">data</a>[<em>'firstname'</em>] = <em>'Wilma'</em>; <i>// updates record, but not the view</i>
 rec.<a href="output/Ext.data.Record.html#Ext.data.Record-commit" ext:member="commit" ext:cls="Ext.data.Record">commit</a>(); <i>// updates the view</i></code></pre>
 <b>Notes</b>:<div class="mdetail-params"><ul>
 <li>If the store has a writer and <code>autoSave=true</code>, each set()