src/data/Types.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @class Ext.data.Types
  17  * <p>This is s static class containing the system-supplied data types which may be given to a {@link Ext.data.Field Field}.<p/>
  18  * <p>The properties in this class are used as type indicators in the {@link Ext.data.Field Field} class, so to
  19  * test whether a Field is of a certain type, compare the {@link Ext.data.Field#type type} property against properties
  20  * of this class.</p>
  21  * <p>Developers may add their own application-specific data types to this class. Definition names must be UPPERCASE.
  22  * each type definition must contain three properties:</p>
  23  * <div class="mdetail-params"><ul>
  24  * <li><code>convert</code> : <i>Function</i><div class="sub-desc">A function to convert raw data values from a data block into the data
  25  * to be stored in the Field. The function is passed the collowing parameters:
  26  * <div class="mdetail-params"><ul>
  27  * <li><b>v</b> : Mixed<div class="sub-desc">The data value as read by the Reader, if undefined will use
  28  * the configured <tt>{@link Ext.data.Field#defaultValue defaultValue}</tt>.</div></li>
  29  * <li><b>rec</b> : Mixed<div class="sub-desc">The data object containing the row as read by the Reader.
  30  * Depending on the Reader type, this could be an Array ({@link Ext.data.reader.Array ArrayReader}), an object
  31  * ({@link Ext.data.reader.Json JsonReader}), or an XML element.</div></li>
  32  * </ul></div></div></li>
  33  * <li><code>sortType</code> : <i>Function</i> <div class="sub-desc">A function to convert the stored data into comparable form, as defined by {@link Ext.data.SortTypes}.</div></li>
  34  * <li><code>type</code> : <i>String</i> <div class="sub-desc">A textual data type name.</div></li>
  35  * </ul></div>
  36  * <p>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
  37  * which contained the properties <code>lat</code> and <code>long</code>, you would define a new data type like this:</p>
  38  *<pre><code>
  39 // Add a new Field data type which stores a VELatLong object in the Record.
  40 Ext.data.Types.VELATLONG = {
  41     convert: function(v, data) {
  42         return new VELatLong(data.lat, data.long);
  43     },
  44     sortType: function(v) {
  45         return v.Latitude;  // When sorting, order by latitude
  46     },
  47     type: 'VELatLong'
  48 };
  49 </code></pre>
  50  * <p>Then, when declaring a Model, use <pre><code>
  51 var types = Ext.data.Types; // allow shorthand type access
  52 Ext.define('Unit',
  53     extend: 'Ext.data.Model',
  54     fields: [
  55         { name: 'unitName', mapping: 'UnitName' },
  56         { name: 'curSpeed', mapping: 'CurSpeed', type: types.INT },
  57         { name: 'latitude', mapping: 'lat', type: types.FLOAT },
  58         { name: 'latitude', mapping: 'lat', type: types.FLOAT },
  59         { name: 'position', type: types.VELATLONG }
  60     ]
  61 });
  62 </code></pre>
  63  * @singleton
  64  */
  65 Ext.define('Ext.data.Types', {
  66     singleton: true,
  67     requires: ['Ext.data.SortTypes']
  68 }, function() {
  69     var st = Ext.data.SortTypes;
  70
  71     Ext.apply(Ext.data.Types, {
  72         /**
  73          * @type Regexp
  74          * @property stripRe
  75          * A regular expression for stripping non-numeric characters from a numeric value. Defaults to <tt>/[\$,%]/g</tt>.
  76          * This should be overridden for localization.
  77          */
  78         stripRe: /[\$,%]/g,
  79
  80         /**
  81          * @type Object.
  82          * @property AUTO
  83          * This data type means that no conversion is applied to the raw data before it is placed into a Record.
  84          */
  85         AUTO: {
  86             convert: function(v) {
  87                 return v;
  88             },
  89             sortType: st.none,
  90             type: 'auto'
  91         },
  92
  93         /**
  94          * @type Object.
  95          * @property 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         /**
 108          * @type Object.
 109          * @property INT
 110          * This data type means that the raw data is converted into an integer before it is placed into a Record.
 111          * <p>The synonym <code>INTEGER</code> is equivalent.</p>
 112          */
 113         INT: {
 114             convert: function(v) {
 115                 return v !== undefined && v !== null && v !== '' ?
 116                     parseInt(String(v).replace(Ext.data.Types.stripRe, ''), 10) : (this.useNull ? null : 0);
 117             },
 118             sortType: st.none,
 119             type: 'int'
 120         },
 121
 122         /**
 123          * @type Object.
 124          * @property FLOAT
 125          * This data type means that the raw data is converted into a number before it is placed into a Record.
 126          * <p>The synonym <code>NUMBER</code> is equivalent.</p>
 127          */
 128         FLOAT: {
 129             convert: function(v) {
 130                 return v !== undefined && v !== null && v !== '' ?
 131                     parseFloat(String(v).replace(Ext.data.Types.stripRe, ''), 10) : (this.useNull ? null : 0);
 132             },
 133             sortType: st.none,
 134             type: 'float'
 135         },
 136
 137         /**
 138          * @type Object.
 139          * @property BOOL
 140          * <p>This data type means that the raw data is converted into a boolean before it is placed into
 141          * a Record. The string "true" and the number 1 are converted to boolean <code>true</code>.</p>
 142          * <p>The synonym <code>BOOLEAN</code> is equivalent.</p>
 143          */
 144         BOOL: {
 145             convert: function(v) {
 146                 if (this.useNull && v === undefined || v === null || v === '') {
 147                     return null;
 148                 }
 149                 return v === true || v === 'true' || v == 1;
 150             },
 151             sortType: st.none,
 152             type: 'bool'
 153         },
 154
 155         /**
 156          * @type Object.
 157          * @property DATE
 158          * This data type means that the raw data is converted into a Date before it is placed into a Record.
 159          * The date format is specified in the constructor of the {@link Ext.data.Field} to which this type is
 160          * being applied.
 161          */
 162         DATE: {
 163             convert: function(v) {
 164                 var df = this.dateFormat;
 165                 if (!v) {
 166                     return null;
 167                 }
 168                 if (Ext.isDate(v)) {
 169                     return v;
 170                 }
 171                 if (df) {
 172                     if (df == 'timestamp') {
 173                         return new Date(v*1000);
 174                     }
 175                     if (df == 'time') {
 176                         return new Date(parseInt(v, 10));
 177                     }
 178                     return Ext.Date.parse(v, df);
 179                 }
 180
 181                 var parsed = Date.parse(v);
 182                 return parsed ? new Date(parsed) : null;
 183             },
 184             sortType: st.asDate,
 185             type: 'date'
 186         }
 187     });
 188
 189     Ext.apply(Ext.data.Types, {
 190         /**
 191          * @type Object.
 192          * @property BOOLEAN
 193          * <p>This data type means that the raw data is converted into a boolean before it is placed into
 194          * a Record. The string "true" and the number 1 are converted to boolean <code>true</code>.</p>
 195          * <p>The synonym <code>BOOL</code> is equivalent.</p>
 196          */
 197         BOOLEAN: this.BOOL,
 198
 199         /**
 200          * @type Object.
 201          * @property INTEGER
 202          * This data type means that the raw data is converted into an integer before it is placed into a Record.
 203          * <p>The synonym <code>INT</code> is equivalent.</p>
 204          */
 205         INTEGER: this.INT,
 206
 207         /**
 208          * @type Object.
 209          * @property NUMBER
 210          * This data type means that the raw data is converted into a number before it is placed into a Record.
 211          * <p>The synonym <code>FLOAT</code> is equivalent.</p>
 212          */
 213         NUMBER: this.FLOAT
 214     });
 215 });
 216