Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Types.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-Types'>/**
19 </span> * @class Ext.data.Types
20  * &lt;p&gt;This is a static class containing the system-supplied data types which may be given to a {@link Ext.data.Field Field}.&lt;p/&gt;
21  * &lt;p&gt;The properties in this class are used as type indicators in the {@link Ext.data.Field Field} class, so to
22  * test whether a Field is of a certain type, compare the {@link Ext.data.Field#type type} property against properties
23  * of this class.&lt;/p&gt;
24  * &lt;p&gt;Developers may add their own application-specific data types to this class. Definition names must be UPPERCASE.
25  * each type definition must contain three properties:&lt;/p&gt;
26  * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
27  * &lt;li&gt;&lt;code&gt;convert&lt;/code&gt; : &lt;i&gt;Function&lt;/i&gt;&lt;div class=&quot;sub-desc&quot;&gt;A function to convert raw data values from a data block into the data
28  * to be stored in the Field. The function is passed the collowing parameters:
29  * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
30  * &lt;li&gt;&lt;b&gt;v&lt;/b&gt; : Mixed&lt;div class=&quot;sub-desc&quot;&gt;The data value as read by the Reader, if undefined will use
31  * the configured &lt;tt&gt;{@link Ext.data.Field#defaultValue defaultValue}&lt;/tt&gt;.&lt;/div&gt;&lt;/li&gt;
32  * &lt;li&gt;&lt;b&gt;rec&lt;/b&gt; : Mixed&lt;div class=&quot;sub-desc&quot;&gt;The data object containing the row as read by the Reader.
33  * Depending on the Reader type, this could be an Array ({@link Ext.data.reader.Array ArrayReader}), an object
34  * ({@link Ext.data.reader.Json JsonReader}), or an XML element.&lt;/div&gt;&lt;/li&gt;
35  * &lt;/ul&gt;&lt;/div&gt;&lt;/div&gt;&lt;/li&gt;
36  * &lt;li&gt;&lt;code&gt;sortType&lt;/code&gt; : &lt;i&gt;Function&lt;/i&gt; &lt;div class=&quot;sub-desc&quot;&gt;A function to convert the stored data into comparable form, as defined by {@link Ext.data.SortTypes}.&lt;/div&gt;&lt;/li&gt;
37  * &lt;li&gt;&lt;code&gt;type&lt;/code&gt; : &lt;i&gt;String&lt;/i&gt; &lt;div class=&quot;sub-desc&quot;&gt;A textual data type name.&lt;/div&gt;&lt;/li&gt;
38  * &lt;/ul&gt;&lt;/div&gt;
39  * &lt;p&gt;For example, to create a VELatLong field (See the Microsoft Bing Mapping API) containing the latitude/longitude value of a datapoint on a map from a JsonReader data block
40  * which contained the properties &lt;code&gt;lat&lt;/code&gt; and &lt;code&gt;long&lt;/code&gt;, you would define a new data type like this:&lt;/p&gt;
41  *&lt;pre&gt;&lt;code&gt;
42 // Add a new Field data type which stores a VELatLong object in the Record.
43 Ext.data.Types.VELATLONG = {
44     convert: function(v, data) {
45         return new VELatLong(data.lat, data.long);
46     },
47     sortType: function(v) {
48         return v.Latitude;  // When sorting, order by latitude
49     },
50     type: 'VELatLong'
51 };
52 &lt;/code&gt;&lt;/pre&gt;
53  * &lt;p&gt;Then, when declaring a Model, use: &lt;pre&gt;&lt;code&gt;
54 var types = Ext.data.Types; // allow shorthand type access
55 Ext.define('Unit',
56     extend: 'Ext.data.Model',
57     fields: [
58         { name: 'unitName', mapping: 'UnitName' },
59         { name: 'curSpeed', mapping: 'CurSpeed', type: types.INT },
60         { name: 'latitude', mapping: 'lat', type: types.FLOAT },
61         { name: 'longitude', mapping: 'long', type: types.FLOAT },
62         { name: 'position', type: types.VELATLONG }
63     ]
64 });
65 &lt;/code&gt;&lt;/pre&gt;
66  * @singleton
67  */
68 Ext.define('Ext.data.Types', {
69     singleton: true,
70     requires: ['Ext.data.SortTypes']
71 }, function() {
72     var st = Ext.data.SortTypes;
73
74     Ext.apply(Ext.data.Types, {
75 <span id='Ext-data-Types-property-stripRe'>        /**
76 </span>         * @property {RegExp} stripRe
77          * A regular expression for stripping non-numeric characters from a numeric value. Defaults to &lt;tt&gt;/[\$,%]/g&lt;/tt&gt;.
78          * This should be overridden for localization.
79          */
80         stripRe: /[\$,%]/g,
81
82 <span id='Ext-data-Types-property-AUTO'>        /**
83 </span>         * @property {Object} AUTO
84          * This data type means that no conversion is applied to the raw data before it is placed into a Record.
85          */
86         AUTO: {
87             convert: function(v) {
88                 return v;
89             },
90             sortType: st.none,
91             type: 'auto'
92         },
93
94 <span id='Ext-data-Types-property-STRING'>        /**
95 </span>         * @property {Object} STRING
96          * This data type means that the raw data is converted into a String before it is placed into a Record.
97          */
98         STRING: {
99             convert: function(v) {
100                 var defaultValue = this.useNull ? null : '';
101                 return (v === undefined || v === null) ? defaultValue : String(v);
102             },
103             sortType: st.asUCString,
104             type: 'string'
105         },
106
107 <span id='Ext-data-Types-property-INT'>        /**
108 </span>         * @property {Object} INT
109          * This data type means that the raw data is converted into an integer before it is placed into a Record.
110          * &lt;p&gt;The synonym &lt;code&gt;INTEGER&lt;/code&gt; is equivalent.&lt;/p&gt;
111          */
112         INT: {
113             convert: function(v) {
114                 return v !== undefined &amp;&amp; v !== null &amp;&amp; v !== '' ?
115                     parseInt(String(v).replace(Ext.data.Types.stripRe, ''), 10) : (this.useNull ? null : 0);
116             },
117             sortType: st.none,
118             type: 'int'
119         },
120
121 <span id='Ext-data-Types-property-FLOAT'>        /**
122 </span>         * @property {Object} FLOAT
123          * This data type means that the raw data is converted into a number before it is placed into a Record.
124          * &lt;p&gt;The synonym &lt;code&gt;NUMBER&lt;/code&gt; is equivalent.&lt;/p&gt;
125          */
126         FLOAT: {
127             convert: function(v) {
128                 return v !== undefined &amp;&amp; v !== null &amp;&amp; v !== '' ?
129                     parseFloat(String(v).replace(Ext.data.Types.stripRe, ''), 10) : (this.useNull ? null : 0);
130             },
131             sortType: st.none,
132             type: 'float'
133         },
134
135 <span id='Ext-data-Types-property-BOOL'>        /**
136 </span>         * @property {Object} BOOL
137          * &lt;p&gt;This data type means that the raw data is converted into a boolean before it is placed into
138          * a Record. The string &quot;true&quot; and the number 1 are converted to boolean &lt;code&gt;true&lt;/code&gt;.&lt;/p&gt;
139          * &lt;p&gt;The synonym &lt;code&gt;BOOLEAN&lt;/code&gt; is equivalent.&lt;/p&gt;
140          */
141         BOOL: {
142             convert: function(v) {
143                 if (this.useNull &amp;&amp; (v === undefined || v === null || v === '')) {
144                     return null;
145                 }
146                 return v === true || v === 'true' || v == 1;
147             },
148             sortType: st.none,
149             type: 'bool'
150         },
151
152 <span id='Ext-data-Types-property-DATE'>        /**
153 </span>         * @property {Object} DATE
154          * This data type means that the raw data is converted into a Date before it is placed into a Record.
155          * The date format is specified in the constructor of the {@link Ext.data.Field} to which this type is
156          * being applied.
157          */
158         DATE: {
159             convert: function(v) {
160                 var df = this.dateFormat,
161                     parsed;
162
163                 if (!v) {
164                     return null;
165                 }
166                 if (Ext.isDate(v)) {
167                     return v;
168                 }
169                 if (df) {
170                     if (df == 'timestamp') {
171                         return new Date(v*1000);
172                     }
173                     if (df == 'time') {
174                         return new Date(parseInt(v, 10));
175                     }
176                     return Ext.Date.parse(v, df);
177                 }
178
179                 parsed = Date.parse(v);
180                 return parsed ? new Date(parsed) : null;
181             },
182             sortType: st.asDate,
183             type: 'date'
184         }
185     });
186
187     Ext.apply(Ext.data.Types, {
188 <span id='Ext-data-Types-property-BOOLEAN'>        /**
189 </span>         * @property {Object} BOOLEAN
190          * &lt;p&gt;This data type means that the raw data is converted into a boolean before it is placed into
191          * a Record. The string &quot;true&quot; and the number 1 are converted to boolean &lt;code&gt;true&lt;/code&gt;.&lt;/p&gt;
192          * &lt;p&gt;The synonym &lt;code&gt;BOOL&lt;/code&gt; is equivalent.&lt;/p&gt;
193          */
194         BOOLEAN: this.BOOL,
195
196 <span id='Ext-data-Types-property-INTEGER'>        /**
197 </span>         * @property {Object} INTEGER
198          * This data type means that the raw data is converted into an integer before it is placed into a Record.
199          * &lt;p&gt;The synonym &lt;code&gt;INT&lt;/code&gt; is equivalent.&lt;/p&gt;
200          */
201         INTEGER: this.INT,
202
203 <span id='Ext-data-Types-property-NUMBER'>        /**
204 </span>         * @property {Object} NUMBER
205          * This data type means that the raw data is converted into a number before it is placed into a Record.
206          * &lt;p&gt;The synonym &lt;code&gt;FLOAT&lt;/code&gt; is equivalent.&lt;/p&gt;
207          */
208         NUMBER: this.FLOAT
209     });
210 });
211 </pre>
212 </body>
213 </html>