docs/api/Ext.data.Field.html

   1 <!DOCTYPE html><html><head><title>Ext.data.Field | Ext JS 4.0 Documentation</title><script type="text/javascript" src="../ext-all.js"></script><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../scrollbars.css" type="text/css"><link rel="stylesheet" href="../docs.css" type="text/css"><link id="styleCss" rel="stylesheet" href="../style.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script><link rel="stylesheet" href="../prettify.css" type="text/css"><!-- link(rel: 'stylesheet', href: req.baseURL + '/css/ext4.css', type: 'text/css')--><link rel="shortcut icon" type="image/ico" href="../favicon.ico"><!--[if IE]>
   2 <style type="text/css">.head-band { display: none; }
   3 .header { border: 0; top: 0; left: 0px; background: url(../header.gif) repeat-x; }
   4 .doc-tab .members .member a.more { background-color: #efefef; }
   5 </style><link rel="stylesheet" href="/new/css/ie.css" type="text/css"><![endif]-->
   6 </head><body id="ext-body" class="iScroll"><div id="notice" class="notice">For up to date documentation and features, visit
   7 <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a></div><div class="wrapper"><div class="head-band"></div><div class="header"><h2><a href="../index.html">Sencha Documentation</a></h2></div><div id="search"><form><input type="text" placeholder="Search" id="search-field" autocomplete="off" name="q"></form><div id="search-box"></div></div><div id="treePanel"></div><div id="container"><script type="text/javascript">
   8
   9     req = {
  10         liveURL: '.',
  11         standAloneMode: true,
  12         origDocClass: 'Ext.data.Field',
  13         docClass: 'Ext.data.Field',
  14         docReq: 'Ext.data.Field',
  15         version: '4.0',
  16         baseURL: '.',
  17         baseDocURL: '.',
  18         baseProdURL: '.'
  19     };
  20
  21     clsInfo = {};
  22
  23
  24
  25 </script>
  26
  27 <script type="text/javascript" src="../search.js"></script>
  28 <!--script type="text/javascript" src="/new/javascripts/app/examples.js"></script-->
  29 <script type="text/javascript" src="../class_tree.js"></script>
  30 <script type="text/javascript" src="../class_doc.js"></script>
  31 <script type="text/javascript">
  32     req.source = 'Field3.html#Ext-data.Field';
  33     clsInfo = {"methods":[],"cfgs":["convert","dateFormat","defaultValue","mapping","name","persist","sortDir","sortType","type","useNull"],"properties":[],"events":[],"subclasses":[]};
  34     Ext.onReady(function() {
  35         Ext.create('Docs.classPanel');
  36     });
  37 </script><div id="top-block" class="top-block"><h1 id="clsTitle" class="cls"><a href="../source/Field3.html#Ext-data.Field" target="_blank">Ext.data.Field</a></h1></div><div id="docContent"><div id="doc-overview-content"><div class="lft"><p>Fields are used to define what a Model is. They aren't instantiated directly - instead, when we create a class
  38 that extends <a href="Ext.data.Model.html" rel="Ext.data.Model" class="docClass">Ext.data.Model</a>, it will automatically create a Field instance for each field configured in a
  39 <a href="Ext.data.Model.html" rel="Ext.data.Model" class="docClass">Model</a>. For example, we might set up a model like this:</p>
  40
  41
  42
  43
  44 <pre class="prettyprint"><code>Ext.define('User', {
  45     extend: 'Ext.data.Model',
  46     fields: [
  47         'name', 'email',
  48         {name: 'age', type: 'int'},
  49         {name: 'gender', type: 'string', defaultValue: 'Unknown'}
  50     ]
  51 });
  52 </code></pre>
  53
  54
  55
  56
  57 <p>Four fields will have been created for the User Model - name, email, age and gender. Note that we specified a
  58 couple of different formats here; if we only pass in the string name of the field (as with name and email), the
  59 field is set up with the 'auto' type. It's as if we'd done this instead:</p>
  60
  61
  62
  63
  64 <pre class="prettyprint"><code>Ext.define('User', {
  65     extend: 'Ext.data.Model',
  66     fields: [
  67         {name: 'name', type: 'auto'},
  68         {name: 'email', type: 'auto'},
  69         {name: 'age', type: 'int'},
  70         {name: 'gender', type: 'string', defaultValue: 'Unknown'}
  71     ]
  72 });
  73 </code></pre>
  74
  75
  76
  77
  78 <p><u>Types and conversion</u></p>
  79
  80
  81
  82
  83 <p>The <a href="Ext.data.Field.html#type" rel="Ext.data.Field#type" class="docClass">type</a> is important - it's used to automatically convert data passed to the field into the correct
  84 format. In our example above, the name and email fields used the 'auto' type and will just accept anything that is
  85 passed into them. The 'age' field had an 'int' type however, so if we passed 25.4 this would be rounded to 25.</p>
  86
  87
  88
  89
  90 <p>Sometimes a simple type isn't enough, or we want to perform some processing when we load a Field's data. We can
  91 do this using a <a href="Ext.data.Field.html#convert" rel="Ext.data.Field#convert" class="docClass">convert</a> function. Here, we're going to create a new field based on another:</p>
  92
  93
  94 <p><code></p>
  95
  96 <pre class="prettyprint">Ext.define('User', {
  97     extend: 'Ext.data.Model',
  98     fields: [
  99         'name', 'email',
 100         {name: 'age', type: 'int'},
 101         {name: 'gender', type: 'string', defaultValue: 'Unknown'},
 102
 103         {
 104             name: 'firstName',
 105             convert: function(value, record) {
 106                 var fullName  = record.get('name'),
 107                     splits    = fullName.split(" "),
 108                     firstName = splits[0];
 109
 110                 return firstName;
 111             }
 112         }
 113     ]
 114 });
 115 </code></pre>
 116
 117
 118
 119
 120 <p>Now when we create a new User, the firstName is populated automatically based on the name:</p>
 121
 122
 123 <p><code></p>
 124
 125 <pre class="prettyprint">var ed = Ext.ModelManager.create({name: 'Ed Spencer'}, 'User');
 126
 127 console.log(ed.get('firstName')); //logs 'Ed', based on our convert function
 128 </code></pre>
 129
 130
 131
 132
 133 <p>In fact, if we log out all of the data inside ed, we'll see this:</p>
 134
 135
 136 <p><code></p>
 137
 138 <pre class="prettyprint">console.log(ed.data);
 139
 140 //outputs this:
 141 {
 142     age: 0,
 143     email: "",
 144     firstName: "Ed",
 145     gender: "Unknown",
 146     name: "Ed Spencer"
 147 }
 148 </code></pre>
 149
 150
 151
 152
 153 <p>The age field has been given a default of zero because we made it an int type. As an auto field, email has
 154 defaulted to an empty string. When we registered the User model we set gender's <a href="Ext.data.Field.html#defaultValue" rel="Ext.data.Field#defaultValue" class="docClass">defaultValue</a> to 'Unknown'
 155 so we see that now. Let's correct that and satisfy ourselves that the types work as we expect:</p>
 156
 157
 158 <p><code></p>
 159
 160 <pre class="prettyprint">ed.set('gender', 'Male');
 161 ed.get('gender'); //returns 'Male'
 162
 163 ed.set('age', 25.4);
 164 ed.get('age'); //returns 25 - we wanted an int, not a float, so no decimal places allowed
 165 </code></pre>
 166
 167 <div class="members"><div class="m-cfgs"><div class="definedBy">Defined By</div><a name="configs"></a><h3 class="cfg p">Config Options</h3><h4 class="cfgGroup">Other Configs</h4><div id="config-convert" class="member f ni"><a href="Ext.data.Field.html#config-convert" rel="config-convert" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-convert" class="viewSource">view source</a></div><a name="convert"></a><a name="config-convert"></a><a href="Ext.data.Field.html#" rel="config-convert" class="cls expand">convert</a><span> : Function</span></div><div class="description"><div class="short">(Optional) A function which converts the value provided by the Reader into an object that will be stored
 168 in the Model...</div><div class="long"><p>(Optional) A function which converts the value provided by the Reader into an object that will be stored
 169 in the Model. It is passed the following parameters:<div class="mdetail-params"><ul>
 170 <li><b>v</b> : Mixed<div class="sub-desc">The data value as read by the Reader, if undefined will use
 171 the configured <code><a href="Ext.data.Field.html#defaultValue" rel="Ext.data.Field#defaultValue" class="docClass">defaultValue</a></code>.</div></li>
 172 <li><b>rec</b> : Ext.data.Model<div class="sub-desc">The data object containing the Model as read so far by the
 173 Reader. Note that the Model may not be fully populated at this point as the fields are read in the order that
 174 they are defined in your <a href="Ext.data.Field.html#fields" rel="Ext.data.Field#fields" class="docClass">fields</a> array.</div></li>
 175 </ul></div></p>
 176
 177 <pre><code>// example of convert function
 178 function fullName(v, record){
 179     return record.name.last + ', ' + record.name.first;
 180 }
 181
 182 function location(v, record){
 183     return !record.city ? '' : (record.city + ', ' + record.state);
 184 }
 185
 186 Ext.define('Dude', {
 187     extend: 'Ext.data.Model',
 188     fields: [
 189         {name: 'fullname',  convert: fullName},
 190         {name: 'firstname', mapping: 'name.first'},
 191         {name: 'lastname',  mapping: 'name.last'},
 192         {name: 'city', defaultValue: 'homeless'},
 193         'state',
 194         {name: 'location',  convert: location}
 195     ]
 196 });
 197
 198 // create the data store
 199 var store = new Ext.data.Store({
 200     reader: {
 201         type: 'json',
 202         model: 'Dude',
 203         idProperty: 'key',
 204         root: 'daRoot',
 205         totalProperty: 'total'
 206     }
 207 });
 208
 209 var myData = [
 210     { key: 1,
 211       name: { first: 'Fat',    last:  'Albert' }
 212       // notice no city, state provided in data object
 213     },
 214     { key: 2,
 215       name: { first: 'Barney', last:  'Rubble' },
 216       city: 'Bedrock', state: 'Stoneridge'
 217     },
 218     { key: 3,
 219       name: { first: 'Cliff',  last:  'Claven' },
 220       city: 'Boston',  state: 'MA'
 221     }
 222 ];
 223 </code></pre>
 224
 225 </div></div></div><div id="config-dateFormat" class="member ni"><a href="Ext.data.Field.html#config-dateFormat" rel="config-dateFormat" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-dateFormat" class="viewSource">view source</a></div><a name="dateFormat"></a><a name="config-dateFormat"></a><a href="Ext.data.Field.html#" rel="config-dateFormat" class="cls expand">dateFormat</a><span> : String</span></div><div class="description"><div class="short">(Optional) Used when converting received data into a Date when the type is specified as "date".
 226
 227
 228 A format string for...</div><div class="long"><p>(Optional) Used when converting received data into a Date when the <a href="Ext.data.Field.html#type" rel="Ext.data.Field#type" class="docClass">type</a> is specified as <code>"date"</code>.</p>
 229
 230
 231 <p>A format string for the <a href="Ext.Date.html#parse" rel="Ext.Date#parse" class="docClass">Ext.Date.parse</a> function, or "timestamp" if the
 232 value provided by the Reader is a UNIX timestamp, or "time" if the value provided by the Reader is a
 233 javascript millisecond timestamp. See <a href="Date.html" rel="Date" class="docClass">Date</a></p>
 234
 235 </div></div></div><div id="config-defaultValue" class="member ni"><a href="Ext.data.Field.html#config-defaultValue" rel="config-defaultValue" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-defaultValue" class="viewSource">view source</a></div><a name="defaultValue"></a><a name="config-defaultValue"></a><a href="Ext.data.Field.html#" rel="config-defaultValue" class="cls expand">defaultValue</a><span> : Mixed</span></div><div class="description"><div class="short">(Optional) The default value used when a Model is being created by a Reader
 236 when the item referenced by the mapping d...</div><div class="long"><p>(Optional) The default value used <b>when a Model is being created by a <a href="Ext.data.reader.Reader.html" rel="Ext.data.reader.Reader" class="docClass">Reader</a></b>
 237 when the item referenced by the <code><a href="Ext.data.Field.html#mapping" rel="Ext.data.Field#mapping" class="docClass">mapping</a></code> does not exist in the data
 238 object (i.e. undefined). (defaults to "")</p>
 239 </div></div></div><div id="config-mapping" class="member ni"><a href="Ext.data.Field.html#config-mapping" rel="config-mapping" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-mapping" class="viewSource">view source</a></div><a name="mapping"></a><a name="config-mapping"></a><a href="Ext.data.Field.html#" rel="config-mapping" class="cls expand">mapping</a><span> : String/Number</span></div><div class="description"><div class="short">(Optional) A path expression for use by the Ext.data.reader.Reader implementation
 240 that is creating the Model to extra...</div><div class="long"><p>(Optional) A path expression for use by the <a href="Ext.data.reader.Reader.html" rel="Ext.data.reader.Reader" class="docClass">Ext.data.reader.Reader</a> implementation
 241 that is creating the <a href="Ext.data.Model.html" rel="Ext.data.Model" class="docClass">Model</a> to extract the Field value from the data object.
 242 If the path expression is the same as the field name, the mapping may be omitted.</p>
 243
 244
 245 <p>The form of the mapping expression depends on the Reader being used.</p>
 246
 247
 248 <div class="mdetail-params"><ul>
 249 <li><a href="Ext.data.reader.Json.html" rel="Ext.data.reader.Json" class="docClass">Ext.data.reader.Json</a><div class="sub-desc">The mapping is a string containing the javascript
 250 expression to reference the data from an element of the data item's <a href="Ext.data.reader.Json.html#root" rel="Ext.data.reader.Json#root" class="docClass">root</a> Array. Defaults to the field name.</div></li>
 251 <li><a href="Ext.data.reader.Xml.html" rel="Ext.data.reader.Xml" class="docClass">Ext.data.reader.Xml</a><div class="sub-desc">The mapping is an <a href="Ext.DomQuery.html" rel="Ext.DomQuery" class="docClass">Ext.DomQuery</a> path to the data
 252 item relative to the DOM element that represents the <a href="Ext.data.reader.Xml.html#record" rel="Ext.data.reader.Xml#record" class="docClass">record</a>. Defaults to the field name.</div></li>
 253 <li><a href="Ext.data.reader.Array.html" rel="Ext.data.reader.Array" class="docClass">Ext.data.reader.Array</a><div class="sub-desc">The mapping is a number indicating the Array index
 254 of the field's value. Defaults to the field specification's Array position.</div></li>
 255 </ul></div>
 256
 257
 258 <p>If a more complex value extraction strategy is required, then configure the Field with a <a href="Ext.data.Field.html#convert" rel="Ext.data.Field#convert" class="docClass">convert</a>
 259 function. This is passed the whole row object, and may interrogate it in whatever way is necessary in order to
 260 return the desired data.</p>
 261
 262 </div></div></div><div id="config-name" class="member ni"><a href="Ext.data.Field.html#config-name" rel="config-name" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-name" class="viewSource">view source</a></div><a name="name"></a><a name="config-name"></a><a href="Ext.data.Field.html#" rel="config-name" class="cls expand">name</a><span> : String</span></div><div class="description"><div class="short">The name by which the field is referenced within the Model. This is referenced by, for example,
 263 the dataIndex propert...</div><div class="long"><p>The name by which the field is referenced within the Model. This is referenced by, for example,
 264 the <code>dataIndex</code> property in column definition objects passed to <a href="Ext.grid.property.HeaderContainer.html" rel="Ext.grid.property.HeaderContainer" class="docClass">Ext.grid.property.HeaderContainer</a>.</p>
 265
 266 <p>Note: In the simplest case, if no properties other than <code>name</code> are required, a field
 267 definition may consist of just a String for the field name.</p>
 268
 269 </div></div></div><div id="config-persist" class="member ni"><a href="Ext.data.Field.html#config-persist" rel="config-persist" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-persist" class="viewSource">view source</a></div><a name="persist"></a><a name="config-persist"></a><a href="Ext.data.Field.html#" rel="config-persist" class="cls expand">persist</a><span> : Boolean</span></div><div class="description"><div class="short">False to exclude this field from the Ext.data.Model.modified fields in a model. This
 270 will also exclude the field from...</div><div class="long"><p>False to exclude this field from the <a href="Ext.data.Model.html#modified" rel="Ext.data.Model#modified" class="docClass">Ext.data.Model.modified</a> fields in a model. This
 271 will also exclude the field from being written using a <a href="Ext.data.writer.Writer.html" rel="Ext.data.writer.Writer" class="docClass">Ext.data.writer.Writer</a>. This option
 272 is useful when model fields are used to keep state on the client but do not need to be persisted
 273 to the server. Defaults to <tt>true</tt>.</p>
 274 </div></div></div><div id="config-sortDir" class="member ni"><a href="Ext.data.Field.html#config-sortDir" rel="config-sortDir" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-sortDir" class="viewSource">view source</a></div><a name="sortDir"></a><a name="config-sortDir"></a><a href="Ext.data.Field.html#" rel="config-sortDir" class="cls expand">sortDir</a><span> : String</span></div><div class="description"><div class="short"><p>(Optional) Initial direction to sort (<code>"ASC"</code> or  <code>"DESC"</code>).  Defaults to
 275 <code>"ASC"</code>.</p>
 276 </div><div class="long"><p>(Optional) Initial direction to sort (<code>"ASC"</code> or  <code>"DESC"</code>).  Defaults to
 277 <code>"ASC"</code>.</p>
 278 </div></div></div><div id="config-sortType" class="member ni"><a href="Ext.data.Field.html#config-sortType" rel="config-sortType" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-sortType" class="viewSource">view source</a></div><a name="sortType"></a><a name="config-sortType"></a><a href="Ext.data.Field.html#" rel="config-sortType" class="cls expand">sortType</a><span> : Function</span></div><div class="description"><div class="short">(Optional) A function which converts a Field's value to a comparable value in order to ensure
 279 correct sort ordering. ...</div><div class="long"><p>(Optional) A function which converts a Field's value to a comparable value in order to ensure
 280 correct sort ordering. Predefined functions are provided in <a href="Ext.data.SortTypes.html" rel="Ext.data.SortTypes" class="docClass">Ext.data.SortTypes</a>. A custom
 281 sort example:</p>
 282
 283 <pre><code>// current sort     after sort we want
 284 // +-+------+          +-+------+
 285 // |1|First |          |1|First |
 286 // |2|Last  |          |3|Second|
 287 // |3|Second|          |2|Last  |
 288 // +-+------+          +-+------+
 289
 290 sortType: function(value) {
 291    switch (value.toLowerCase()) // native toLowerCase():
 292    {
 293       case 'first': return 1;
 294       case 'second': return 2;
 295       default: return 3;
 296    }
 297 }
 298 </code></pre>
 299
 300 </div></div></div><div id="config-type" class="member ni"><a href="Ext.data.Field.html#config-type" rel="config-type" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-type" class="viewSource">view source</a></div><a name="type"></a><a name="config-type"></a><a href="Ext.data.Field.html#" rel="config-type" class="cls expand">type</a><span> : Mixed</span></div><div class="description"><div class="short">(Optional) The data type for automatic conversion from received data to the stored value if convert
 301 has not been spec...</div><div class="long"><p>(Optional) The data type for automatic conversion from received data to the <i>stored</i> value if <code><a href="Ext.data.Field.html#convert" rel="Ext.data.Field#convert" class="docClass">convert</a></code>
 302 has not been specified. This may be specified as a string value. Possible values are</p>
 303
 304 <div class="mdetail-params"><ul>
 305 <li>auto (Default, implies no conversion)</li>
 306 <li>string</li>
 307 <li>int</li>
 308 <li>float</li>
 309 <li>boolean</li>
 310 <li>date</li></ul></div>
 311
 312
 313 <p>This may also be specified by referencing a member of the <a href="Ext.data.Types.html" rel="Ext.data.Types" class="docClass">Ext.data.Types</a> class.</p>
 314
 315
 316 <p>Developers may create their own application-specific data types by defining new members of the
 317 <a href="Ext.data.Types.html" rel="Ext.data.Types" class="docClass">Ext.data.Types</a> class.</p>
 318
 319 </div></div></div><div id="config-useNull" class="member ni"><a href="Ext.data.Field.html#config-useNull" rel="config-useNull" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Field.html" class="definedIn docClass">Ext.data.Field</a><br/><a href="../source/Field3.html#Ext-data.Field-cfg-useNull" class="viewSource">view source</a></div><a name="useNull"></a><a name="config-useNull"></a><a href="Ext.data.Field.html#" rel="config-useNull" class="cls expand">useNull</a><span> : Boolean</span></div><div class="description"><div class="short">(Optional) Use when converting received data into a Number type (either int or float). If the value cannot be parsed,...</div><div class="long"><p>(Optional) Use when converting received data into a Number type (either int or float). If the value cannot be parsed,
 320 null will be used if useNull is true, otherwise the value will be 0. Defaults to <tt>false</tt>
 321
 322 </div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>