Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / 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>