docs/source/Time.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="../prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../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-form-field-Time-method-constructor'><span id='Ext-form-field-Time'>/**
  19 </span></span> * @class Ext.form.field.Time
  20  * @extends Ext.form.field.Picker
  21  * &lt;p&gt;Provides a time input field with a time dropdown and automatic time validation.&lt;/p&gt;
  22  * &lt;p&gt;This field recognizes and uses JavaScript Date objects as its main {@link #value} type (only the time
  23  * portion of the date is used; the month/day/year are ignored). In addition, it recognizes string values which
  24  * are parsed according to the {@link #format} and/or {@link #altFormats} configs. These may be reconfigured
  25  * to use time formats appropriate for the user's locale.&lt;/p&gt;
  26  * &lt;p&gt;The field may be limited to a certain range of times by using the {@link #minValue} and {@link #maxValue}
  27  * configs, and the interval between time options in the dropdown can be changed with the {@link #increment} config.&lt;/p&gt;
  28  * {@img Ext.form.Time/Ext.form.Time.png Ext.form.Time component}
  29  * &lt;p&gt;Example usage:&lt;/p&gt;
  30  * &lt;pre&gt;&lt;code&gt;
  31 Ext.create('Ext.form.Panel', {
  32     title: 'Time Card',
  33     width: 300,
  34     bodyPadding: 10,
  35     renderTo: Ext.getBody(),
  36     items: [{
  37         xtype: 'timefield',
  38         name: 'in',
  39         fieldLabel: 'Time In',
  40         minValue: '6:00 AM',
  41         maxValue: '8:00 PM',
  42         increment: 30,
  43         anchor: '100%'
  44     }, {
  45         xtype: 'timefield',
  46         name: 'out',
  47         fieldLabel: 'Time Out',
  48         minValue: '6:00 AM',
  49         maxValue: '8:00 PM',
  50         increment: 30,
  51         anchor: '100%'
  52    }]
  53 });
  54 &lt;/code&gt;&lt;/pre&gt;
  55  * @constructor
  56  * Create a new Time field
  57  * @param {Object} config
  58  * @xtype timefield
  59  */
  60 Ext.define('Ext.form.field.Time', {
  61     extend:'Ext.form.field.Picker',
  62     alias: 'widget.timefield',
  63     requires: ['Ext.form.field.Date', 'Ext.picker.Time', 'Ext.view.BoundListKeyNav', 'Ext.Date'],
  64     alternateClassName: ['Ext.form.TimeField', 'Ext.form.Time'],
  65
  66 <span id='Ext-form-field-Time-cfg-triggerCls'>    /**
  67 </span>     * @cfg {String} triggerCls
  68      * An additional CSS class used to style the trigger button.  The trigger will always get the
  69      * {@link #triggerBaseCls} by default and &lt;tt&gt;triggerCls&lt;/tt&gt; will be &lt;b&gt;appended&lt;/b&gt; if specified.
  70      * Defaults to &lt;tt&gt;'x-form-time-trigger'&lt;/tt&gt; for the Time field trigger.
  71      */
  72     triggerCls: Ext.baseCSSPrefix + 'form-time-trigger',
  73
  74 <span id='Ext-form-field-Time-cfg-minValue'>    /**
  75 </span>     * @cfg {Date/String} minValue
  76      * The minimum allowed time. Can be either a Javascript date object with a valid time value or a string
  77      * time in a valid format -- see {@link #format} and {@link #altFormats} (defaults to undefined).
  78      */
  79
  80 <span id='Ext-form-field-Time-cfg-maxValue'>    /**
  81 </span>     * @cfg {Date/String} maxValue
  82      * The maximum allowed time. Can be either a Javascript date object with a valid time value or a string
  83      * time in a valid format -- see {@link #format} and {@link #altFormats} (defaults to undefined).
  84      */
  85
  86 <span id='Ext-form-field-Time-cfg-minText'>    /**
  87 </span>     * @cfg {String} minText
  88      * The error text to display when the entered time is before {@link #minValue} (defaults to
  89      * 'The time in this field must be equal to or after {0}').
  90      */
  91     minText : &quot;The time in this field must be equal to or after {0}&quot;,
  92
  93 <span id='Ext-form-field-Time-cfg-maxText'>    /**
  94 </span>     * @cfg {String} maxText
  95      * The error text to display when the entered time is after {@link #maxValue} (defaults to
  96      * 'The time in this field must be equal to or before {0}').
  97      */
  98     maxText : &quot;The time in this field must be equal to or before {0}&quot;,
  99
 100 <span id='Ext-form-field-Time-cfg-invalidText'>    /**
 101 </span>     * @cfg {String} invalidText
 102      * The error text to display when the time in the field is invalid (defaults to
 103      * '{value} is not a valid time').
 104      */
 105     invalidText : &quot;{0} is not a valid time&quot;,
 106
 107 <span id='Ext-form-field-Time-cfg-format'>    /**
 108 </span>     * @cfg {String} format
 109      * The default time format string which can be overriden for localization support.  The format must be
 110      * valid according to {@link Ext.Date#parse} (defaults to 'g:i A', e.g., '3:15 PM').  For 24-hour time
 111      * format try 'H:i' instead.
 112      */
 113     format : &quot;g:i A&quot;,
 114
 115 <span id='Ext-form-field-Time-cfg-submitFormat'>    /**
 116 </span>     * @cfg {String} submitFormat The date format string which will be submitted to the server.
 117      * The format must be valid according to {@link Ext.Date#parse} (defaults to &lt;tt&gt;{@link #format}&lt;/tt&gt;).
 118      */
 119
 120 <span id='Ext-form-field-Time-cfg-altFormats'>    /**
 121 </span>     * @cfg {String} altFormats
 122      * Multiple date formats separated by &quot;|&quot; to try when parsing a user input value and it doesn't match the defined
 123      * format (defaults to 'g:ia|g:iA|g:i a|g:i A|h:i|g:i|H:i|ga|ha|gA|h a|g a|g A|gi|hi|gia|hia|g|H|gi a|hi a|giA|hiA|gi A|hi A').
 124      */
 125     altFormats : &quot;g:ia|g:iA|g:i a|g:i A|h:i|g:i|H:i|ga|ha|gA|h a|g a|g A|gi|hi|gia|hia|g|H|gi a|hi a|giA|hiA|gi A|hi A&quot;,
 126
 127 <span id='Ext-form-field-Time-cfg-increment'>    /**
 128 </span>     * @cfg {Number} increment
 129      * The number of minutes between each time value in the list (defaults to 15).
 130      */
 131     increment: 15,
 132
 133 <span id='Ext-form-field-Time-cfg-pickerMaxHeight'>    /**
 134 </span>     * @cfg {Number} pickerMaxHeight
 135      * The maximum height of the {@link Ext.picker.Time} dropdown. Defaults to 300.
 136      */
 137     pickerMaxHeight: 300,
 138
 139 <span id='Ext-form-field-Time-cfg-selectOnTab'>    /**
 140 </span>     * @cfg {Boolean} selectOnTab
 141      * Whether the Tab key should select the currently highlighted item. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
 142      */
 143     selectOnTab: true,
 144
 145 <span id='Ext-form-field-Time-property-initDate'>    /**
 146 </span>     * @private
 147      * This is the date to use when generating time values in the absence of either minValue
 148      * or maxValue.  Using the current date causes DST issues on DST boundary dates, so this is an
 149      * arbitrary &quot;safe&quot; date that can be any date aside from DST boundary dates.
 150      */
 151     initDate: '1/1/2008',
 152     initDateFormat: 'j/n/Y',
 153
 154
 155     initComponent: function() {
 156         var me = this,
 157             min = me.minValue,
 158             max = me.maxValue;
 159         if (min) {
 160             me.setMinValue(min);
 161         }
 162         if (max) {
 163             me.setMaxValue(max);
 164         }
 165         this.callParent();
 166     },
 167
 168     initValue: function() {
 169         var me = this,
 170             value = me.value;
 171
 172         // If a String value was supplied, try to convert it to a proper Date object
 173         if (Ext.isString(value)) {
 174             me.value = me.rawToValue(value);
 175         }
 176
 177         me.callParent();
 178     },
 179
 180 <span id='Ext-form-field-Time-method-setMinValue'>    /**
 181 </span>     * Replaces any existing {@link #minValue} with the new time and refreshes the picker's range.
 182      * @param {Date/String} value The minimum time that can be selected
 183      */
 184     setMinValue: function(value) {
 185         var me = this,
 186             picker = me.picker;
 187         me.setLimit(value, true);
 188         if (picker) {
 189             picker.setMinValue(me.minValue);
 190         }
 191     },
 192
 193 <span id='Ext-form-field-Time-method-setMaxValue'>    /**
 194 </span>     * Replaces any existing {@link #maxValue} with the new time and refreshes the picker's range.
 195      * @param {Date/String} value The maximum time that can be selected
 196      */
 197     setMaxValue: function(value) {
 198         var me = this,
 199             picker = me.picker;
 200         me.setLimit(value, false);
 201         if (picker) {
 202             picker.setMaxValue(me.maxValue);
 203         }
 204     },
 205
 206 <span id='Ext-form-field-Time-method-setLimit'>    /**
 207 </span>     * @private
 208      * Updates either the min or max value. Converts the user's value into a Date object whose
 209      * year/month/day is set to the {@link #initDate} so that only the time fields are significant.
 210      */
 211     setLimit: function(value, isMin) {
 212         var me = this,
 213             d, val;
 214         if (Ext.isString(value)) {
 215             d = me.parseDate(value);
 216         }
 217         else if (Ext.isDate(value)) {
 218             d = value;
 219         }
 220         if (d) {
 221             val = Ext.Date.clearTime(new Date(me.initDate));
 222             val.setHours(d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
 223             me[isMin ? 'minValue' : 'maxValue'] = val;
 224         }
 225     },
 226
 227     rawToValue: function(rawValue) {
 228         return this.parseDate(rawValue) || rawValue || null;
 229     },
 230
 231     valueToRaw: function(value) {
 232         return this.formatDate(this.parseDate(value));
 233     },
 234
 235 <span id='Ext-form-field-Time-method-getErrors'>    /**
 236 </span>     * Runs all of Time's validations and returns an array of any errors. Note that this first
 237      * runs Text's validations, so the returned array is an amalgamation of all field errors.
 238      * The additional validation checks are testing that the time format is valid, that the chosen
 239      * time is within the {@link #minValue} and {@link #maxValue} constraints set.
 240      * @param {Mixed} value The value to get errors for (defaults to the current field value)
 241      * @return {Array} All validation errors for this field
 242      */
 243     getErrors: function(value) {
 244         var me = this,
 245             format = Ext.String.format,
 246             errors = me.callParent(arguments),
 247             minValue = me.minValue,
 248             maxValue = me.maxValue,
 249             date;
 250
 251         value = me.formatDate(value || me.processRawValue(me.getRawValue()));
 252
 253         if (value === null || value.length &lt; 1) { // if it's blank and textfield didn't flag it then it's valid
 254              return errors;
 255         }
 256
 257         date = me.parseDate(value);
 258         if (!date) {
 259             errors.push(format(me.invalidText, value, me.format));
 260             return errors;
 261         }
 262
 263         if (minValue &amp;&amp; date &lt; minValue) {
 264             errors.push(format(me.minText, me.formatDate(minValue)));
 265         }
 266
 267         if (maxValue &amp;&amp; date &gt; maxValue) {
 268             errors.push(format(me.maxText, me.formatDate(maxValue)));
 269         }
 270
 271         return errors;
 272     },
 273
 274     formatDate: function() {
 275         return Ext.form.field.Date.prototype.formatDate.apply(this, arguments);
 276     },
 277
 278 <span id='Ext-form-field-Time-method-parseDate'>    /**
 279 </span>     * @private
 280      * Parses an input value into a valid Date object.
 281      * @param {String/Date} value
 282      */
 283     parseDate: function(value) {
 284         if (!value || Ext.isDate(value)) {
 285             return value;
 286         }
 287
 288         var me = this,
 289             val = me.safeParse(value, me.format),
 290             altFormats = me.altFormats,
 291             altFormatsArray = me.altFormatsArray,
 292             i = 0,
 293             len;
 294
 295         if (!val &amp;&amp; altFormats) {
 296             altFormatsArray = altFormatsArray || altFormats.split('|');
 297             len = altFormatsArray.length;
 298             for (; i &lt; len &amp;&amp; !val; ++i) {
 299                 val = me.safeParse(value, altFormatsArray[i]);
 300             }
 301         }
 302         return val;
 303     },
 304
 305     safeParse: function(value, format){
 306         var me = this,
 307             utilDate = Ext.Date,
 308             parsedDate,
 309             result = null;
 310
 311         if (utilDate.formatContainsDateInfo(format)) {
 312             // assume we've been given a full date
 313             result = utilDate.parse(value, format);
 314         } else {
 315             // Use our initial safe date
 316             parsedDate = utilDate.parse(me.initDate + ' ' + value, me.initDateFormat + ' ' + format);
 317             if (parsedDate) {
 318                 result = parsedDate;
 319             }
 320         }
 321         return result;
 322     },
 323
 324     // @private
 325     getSubmitValue: function() {
 326         var me = this,
 327             format = me.submitFormat || me.format,
 328             value = me.getValue();
 329
 330         return value ? Ext.Date.format(value, format) : null;
 331     },
 332
 333 <span id='Ext-form-field-Time-method-createPicker'>    /**
 334 </span>     * @private
 335      * Creates the {@link Ext.picker.Time}
 336      */
 337     createPicker: function() {
 338         var me = this,
 339             picker = Ext.create('Ext.picker.Time', {
 340                 selModel: {
 341                     mode: 'SINGLE'
 342                 },
 343                 floating: true,
 344                 hidden: true,
 345                 minValue: me.minValue,
 346                 maxValue: me.maxValue,
 347                 increment: me.increment,
 348                 format: me.format,
 349                 ownerCt: this.ownerCt,
 350                 renderTo: document.body,
 351                 maxHeight: me.pickerMaxHeight,
 352                 focusOnToFront: false
 353             });
 354
 355         me.mon(picker.getSelectionModel(), {
 356             selectionchange: me.onListSelect,
 357             scope: me
 358         });
 359
 360         return picker;
 361     },
 362
 363 <span id='Ext-form-field-Time-method-onExpand'>    /**
 364 </span>     * @private
 365      * Enables the key nav for the Time picker when it is expanded.
 366      * TODO this is largely the same logic as ComboBox, should factor out.
 367      */
 368     onExpand: function() {
 369         var me = this,
 370             keyNav = me.pickerKeyNav,
 371             selectOnTab = me.selectOnTab,
 372             picker = me.getPicker(),
 373             lastSelected = picker.getSelectionModel().lastSelected,
 374             itemNode;
 375
 376         if (!keyNav) {
 377             keyNav = me.pickerKeyNav = Ext.create('Ext.view.BoundListKeyNav', this.inputEl, {
 378                 boundList: picker,
 379                 forceKeyDown: true,
 380                 tab: function(e) {
 381                     if (selectOnTab) {
 382                         this.selectHighlighted(e);
 383                         me.triggerBlur();
 384                     }
 385                     // Tab key event is allowed to propagate to field
 386                     return true;
 387                 }
 388             });
 389             // stop tab monitoring from Ext.form.field.Trigger so it doesn't short-circuit selectOnTab
 390             if (selectOnTab) {
 391                 me.ignoreMonitorTab = true;
 392             }
 393         }
 394         Ext.defer(keyNav.enable, 1, keyNav); //wait a bit so it doesn't react to the down arrow opening the picker
 395
 396         // Highlight the last selected item and scroll it into view
 397         if (lastSelected) {
 398             itemNode = picker.getNode(lastSelected);
 399             if (itemNode) {
 400                 picker.highlightItem(itemNode);
 401                 picker.el.scrollChildIntoView(itemNode, false);
 402             }
 403         }
 404     },
 405
 406 <span id='Ext-form-field-Time-method-onCollapse'>    /**
 407 </span>     * @private
 408      * Disables the key nav for the Time picker when it is collapsed.
 409      */
 410     onCollapse: function() {
 411         var me = this,
 412             keyNav = me.pickerKeyNav;
 413         if (keyNav) {
 414             keyNav.disable();
 415             me.ignoreMonitorTab = false;
 416         }
 417     },
 418
 419 <span id='Ext-form-field-Time-method-onListSelect'>    /**
 420 </span>     * @private
 421      * Handles a time being selected from the Time picker.
 422      */
 423     onListSelect: function(list, recordArray) {
 424         var me = this,
 425             record = recordArray[0],
 426             val = record ? record.get('date') : null;
 427         me.setValue(val);
 428         me.fireEvent('select', me, val);
 429         me.picker.clearHighlight();
 430         me.collapse();
 431         me.inputEl.focus();
 432     }
 433 });
 434
 435 </pre>
 436 </body>
 437 </html>