docs/source/Field3.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-data-Field'>/**
  19 </span> * @author Ed Spencer
  20  *
  21  * Fields are used to define what a Model is. They aren't instantiated directly - instead, when we create a class that
  22  * extends {@link Ext.data.Model}, it will automatically create a Field instance for each field configured in a {@link
  23  * Ext.data.Model Model}. For example, we might set up a model like this:
  24  *
  25  *     Ext.define('User', {
  26  *         extend: 'Ext.data.Model',
  27  *         fields: [
  28  *             'name', 'email',
  29  *             {name: 'age', type: 'int'},
  30  *             {name: 'gender', type: 'string', defaultValue: 'Unknown'}
  31  *         ]
  32  *     });
  33  *
  34  * Four fields will have been created for the User Model - name, email, age and gender. Note that we specified a couple
  35  * of different formats here; if we only pass in the string name of the field (as with name and email), the field is set
  36  * up with the 'auto' type. It's as if we'd done this instead:
  37  *
  38  *     Ext.define('User', {
  39  *         extend: 'Ext.data.Model',
  40  *         fields: [
  41  *             {name: 'name', type: 'auto'},
  42  *             {name: 'email', type: 'auto'},
  43  *             {name: 'age', type: 'int'},
  44  *             {name: 'gender', type: 'string', defaultValue: 'Unknown'}
  45  *         ]
  46  *     });
  47  *
  48  * # Types and conversion
  49  *
  50  * The {@link #type} is important - it's used to automatically convert data passed to the field into the correct format.
  51  * In our example above, the name and email fields used the 'auto' type and will just accept anything that is passed
  52  * into them. The 'age' field had an 'int' type however, so if we passed 25.4 this would be rounded to 25.
  53  *
  54  * Sometimes a simple type isn't enough, or we want to perform some processing when we load a Field's data. We can do
  55  * this using a {@link #convert} function. Here, we're going to create a new field based on another:
  56  *
  57  *     Ext.define('User', {
  58  *         extend: 'Ext.data.Model',
  59  *         fields: [
  60  *             'name', 'email',
  61  *             {name: 'age', type: 'int'},
  62  *             {name: 'gender', type: 'string', defaultValue: 'Unknown'},
  63  *
  64  *             {
  65  *                 name: 'firstName',
  66  *                 convert: function(value, record) {
  67  *                     var fullName  = record.get('name'),
  68  *                         splits    = fullName.split(&quot; &quot;),
  69  *                         firstName = splits[0];
  70  *
  71  *                     return firstName;
  72  *                 }
  73  *             }
  74  *         ]
  75  *     });
  76  *
  77  * Now when we create a new User, the firstName is populated automatically based on the name:
  78  *
  79  *     var ed = Ext.create('User', {name: 'Ed Spencer'});
  80  *
  81  *     console.log(ed.get('firstName')); //logs 'Ed', based on our convert function
  82  *
  83  * In fact, if we log out all of the data inside ed, we'll see this:
  84  *
  85  *     console.log(ed.data);
  86  *
  87  *     //outputs this:
  88  *     {
  89  *         age: 0,
  90  *         email: &quot;&quot;,
  91  *         firstName: &quot;Ed&quot;,
  92  *         gender: &quot;Unknown&quot;,
  93  *         name: &quot;Ed Spencer&quot;
  94  *     }
  95  *
  96  * The age field has been given a default of zero because we made it an int type. As an auto field, email has defaulted
  97  * to an empty string. When we registered the User model we set gender's {@link #defaultValue} to 'Unknown' so we see
  98  * that now. Let's correct that and satisfy ourselves that the types work as we expect:
  99  *
 100  *     ed.set('gender', 'Male');
 101  *     ed.get('gender'); //returns 'Male'
 102  *
 103  *     ed.set('age', 25.4);
 104  *     ed.get('age'); //returns 25 - we wanted an int, not a float, so no decimal places allowed
 105  */
 106 Ext.define('Ext.data.Field', {
 107     requires: ['Ext.data.Types', 'Ext.data.SortTypes'],
 108     alias: 'data.field',
 109
 110     constructor : function(config) {
 111         if (Ext.isString(config)) {
 112             config = {name: config};
 113         }
 114         Ext.apply(this, config);
 115
 116         var types = Ext.data.Types,
 117             st = this.sortType,
 118             t;
 119
 120         if (this.type) {
 121             if (Ext.isString(this.type)) {
 122                 this.type = types[this.type.toUpperCase()] || types.AUTO;
 123             }
 124         } else {
 125             this.type = types.AUTO;
 126         }
 127
 128         // named sortTypes are supported, here we look them up
 129         if (Ext.isString(st)) {
 130             this.sortType = Ext.data.SortTypes[st];
 131         } else if(Ext.isEmpty(st)) {
 132             this.sortType = this.type.sortType;
 133         }
 134
 135         if (!this.convert) {
 136             this.convert = this.type.convert;
 137         }
 138     },
 139
 140 <span id='Ext-data-Field-cfg-name'>    /**
 141 </span>     * @cfg {String} name
 142      *
 143      * The name by which the field is referenced within the Model. This is referenced by, for example, the `dataIndex`
 144      * property in column definition objects passed to {@link Ext.grid.property.HeaderContainer}.
 145      *
 146      * Note: In the simplest case, if no properties other than `name` are required, a field definition may consist of
 147      * just a String for the field name.
 148      */
 149
 150 <span id='Ext-data-Field-cfg-type'>    /**
 151 </span>     * @cfg {String/Object} type
 152      *
 153      * The data type for automatic conversion from received data to the *stored* value if
 154      * `{@link Ext.data.Field#convert convert}` has not been specified. This may be specified as a string value.
 155      * Possible values are
 156      *
 157      * - auto (Default, implies no conversion)
 158      * - string
 159      * - int
 160      * - float
 161      * - boolean
 162      * - date
 163      *
 164      * This may also be specified by referencing a member of the {@link Ext.data.Types} class.
 165      *
 166      * Developers may create their own application-specific data types by defining new members of the {@link
 167      * Ext.data.Types} class.
 168      */
 169
 170 <span id='Ext-data-Field-cfg-convert'>    /**
 171 </span>     * @cfg {Function} convert
 172      *
 173      * A function which converts the value provided by the Reader into an object that will be stored in the Model.
 174      * It is passed the following parameters:
 175      *
 176      * - **v** : Mixed
 177      *
 178      *   The data value as read by the Reader, if undefined will use the configured `{@link Ext.data.Field#defaultValue
 179      *   defaultValue}`.
 180      *
 181      * - **rec** : Ext.data.Model
 182      *
 183      *   The data object containing the Model as read so far by the Reader. Note that the Model may not be fully populated
 184      *   at this point as the fields are read in the order that they are defined in your
 185      *   {@link Ext.data.Model#fields fields} array.
 186      *
 187      * Example of convert functions:
 188      *
 189      *     function fullName(v, record){
 190      *         return record.name.last + ', ' + record.name.first;
 191      *     }
 192      *
 193      *     function location(v, record){
 194      *         return !record.city ? '' : (record.city + ', ' + record.state);
 195      *     }
 196      *
 197      *     Ext.define('Dude', {
 198      *         extend: 'Ext.data.Model',
 199      *         fields: [
 200      *             {name: 'fullname',  convert: fullName},
 201      *             {name: 'firstname', mapping: 'name.first'},
 202      *             {name: 'lastname',  mapping: 'name.last'},
 203      *             {name: 'city', defaultValue: 'homeless'},
 204      *             'state',
 205      *             {name: 'location',  convert: location}
 206      *         ]
 207      *     });
 208      *
 209      *     // create the data store
 210      *     var store = Ext.create('Ext.data.Store', {
 211      *         reader: {
 212      *             type: 'json',
 213      *             model: 'Dude',
 214      *             idProperty: 'key',
 215      *             root: 'daRoot',
 216      *             totalProperty: 'total'
 217      *         }
 218      *     });
 219      *
 220      *     var myData = [
 221      *         { key: 1,
 222      *           name: { first: 'Fat',    last:  'Albert' }
 223      *           // notice no city, state provided in data object
 224      *         },
 225      *         { key: 2,
 226      *           name: { first: 'Barney', last:  'Rubble' },
 227      *           city: 'Bedrock', state: 'Stoneridge'
 228      *         },
 229      *         { key: 3,
 230      *           name: { first: 'Cliff',  last:  'Claven' },
 231      *           city: 'Boston',  state: 'MA'
 232      *         }
 233      *     ];
 234      */
 235
 236 <span id='Ext-data-Field-cfg-dateFormat'>    /**
 237 </span>     * @cfg {String} dateFormat
 238      *
 239      * Used when converting received data into a Date when the {@link #type} is specified as `&quot;date&quot;`.
 240      *
 241      * A format string for the {@link Ext.Date#parse Ext.Date.parse} function, or &quot;timestamp&quot; if the value provided by
 242      * the Reader is a UNIX timestamp, or &quot;time&quot; if the value provided by the Reader is a javascript millisecond
 243      * timestamp. See {@link Ext.Date}.
 244      */
 245     dateFormat: null,
 246
 247 <span id='Ext-data-Field-cfg-useNull'>    /**
 248 </span>     * @cfg {Boolean} useNull
 249      *
 250      * Use when converting received data into a Number type (either int or float). If the value cannot be
 251      * parsed, null will be used if useNull is true, otherwise the value will be 0. Defaults to false.
 252      */
 253     useNull: false,
 254
 255 <span id='Ext-data-Field-cfg-defaultValue'>    /**
 256 </span>     * @cfg {Object} defaultValue
 257      *
 258      * The default value used **when a Model is being created by a {@link Ext.data.reader.Reader Reader}**
 259      * when the item referenced by the `{@link Ext.data.Field#mapping mapping}` does not exist in the data object
 260      * (i.e. undefined). Defaults to &quot;&quot;.
 261      */
 262     defaultValue: &quot;&quot;,
 263
 264 <span id='Ext-data-Field-cfg-mapping'>    /**
 265 </span>     * @cfg {String/Number} mapping
 266      *
 267      * (Optional) A path expression for use by the {@link Ext.data.reader.Reader} implementation that is creating the
 268      * {@link Ext.data.Model Model} to extract the Field value from the data object. If the path expression is the same
 269      * as the field name, the mapping may be omitted.
 270      *
 271      * The form of the mapping expression depends on the Reader being used.
 272      *
 273      * - {@link Ext.data.reader.Json}
 274      *
 275      *   The mapping is a string containing the javascript expression to reference the data from an element of the data
 276      *   item's {@link Ext.data.reader.Json#root root} Array. Defaults to the field name.
 277      *
 278      * - {@link Ext.data.reader.Xml}
 279      *
 280      *   The mapping is an {@link Ext.DomQuery} path to the data item relative to the DOM element that represents the
 281      *   {@link Ext.data.reader.Xml#record record}. Defaults to the field name.
 282      *
 283      * - {@link Ext.data.reader.Array}
 284      *
 285      *   The mapping is a number indicating the Array index of the field's value. Defaults to the field specification's
 286      *   Array position.
 287      *
 288      * If a more complex value extraction strategy is required, then configure the Field with a {@link #convert}
 289      * function. This is passed the whole row object, and may interrogate it in whatever way is necessary in order to
 290      * return the desired data.
 291      */
 292     mapping: null,
 293
 294 <span id='Ext-data-Field-cfg-sortType'>    /**
 295 </span>     * @cfg {Function} sortType
 296      *
 297      * A function which converts a Field's value to a comparable value in order to ensure correct sort ordering.
 298      * Predefined functions are provided in {@link Ext.data.SortTypes}. A custom sort example:
 299      *
 300      *     // current sort     after sort we want
 301      *     // +-+------+          +-+------+
 302      *     // |1|First |          |1|First |
 303      *     // |2|Last  |          |3|Second|
 304      *     // |3|Second|          |2|Last  |
 305      *     // +-+------+          +-+------+
 306      *
 307      *     sortType: function(value) {
 308      *        switch (value.toLowerCase()) // native toLowerCase():
 309      *        {
 310      *           case 'first': return 1;
 311      *           case 'second': return 2;
 312      *           default: return 3;
 313      *        }
 314      *     }
 315      */
 316     sortType : null,
 317
 318 <span id='Ext-data-Field-cfg-sortDir'>    /**
 319 </span>     * @cfg {String} sortDir
 320      *
 321      * Initial direction to sort (`&quot;ASC&quot;` or `&quot;DESC&quot;`). Defaults to `&quot;ASC&quot;`.
 322      */
 323     sortDir : &quot;ASC&quot;,
 324
 325 <span id='Ext-data-Field-cfg-allowBlank'>    /**
 326 </span>     * @cfg {Boolean} allowBlank
 327      * @private
 328      *
 329      * Used for validating a {@link Ext.data.Model model}. Defaults to true. An empty value here will cause
 330      * {@link Ext.data.Model}.{@link Ext.data.Model#isValid isValid} to evaluate to false.
 331      */
 332     allowBlank : true,
 333
 334 <span id='Ext-data-Field-cfg-persist'>    /**
 335 </span>     * @cfg {Boolean} persist
 336      *
 337      * False to exclude this field from the {@link Ext.data.Model#modified} fields in a model. This will also exclude
 338      * the field from being written using a {@link Ext.data.writer.Writer}. This option is useful when model fields are
 339      * used to keep state on the client but do not need to be persisted to the server. Defaults to true.
 340      */
 341     persist: true
 342 });
 343 </pre>
 344 </body>
 345 </html>