Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / src / form / field / Date.js
1 /**
2  * @class Ext.form.field.Date
3  * @extends Ext.form.field.Picker
4
5 Provides a date input field with a {@link Ext.picker.Date date picker} dropdown and automatic date
6 validation.
7
8 This field recognizes and uses the JavaScript Date object as its main {@link #value} type. In addition,
9 it recognizes string values which are parsed according to the {@link #format} and/or {@link #altFormats}
10 configs. These may be reconfigured to use date formats appropriate for the user's locale.
11
12 The field may be limited to a certain range of dates by using the {@link #minValue}, {@link #maxValue},
13 {@link #disabledDays}, and {@link #disabledDates} config parameters. These configurations will be used both
14 in the field's validation, and in the date picker dropdown by preventing invalid dates from being selected.
15 {@img Ext.form.Date/Ext.form.Date.png Ext.form.Date component}
16 #Example usage:#
17
18     Ext.create('Ext.form.Panel', {
19         width: 300,
20         bodyPadding: 10,
21         title: 'Dates',
22         items: [{
23             xtype: 'datefield',
24             anchor: '100%',
25             fieldLabel: 'From',
26             name: 'from_date',
27             maxValue: new Date()  // limited to the current date or prior
28         }, {
29             xtype: 'datefield',
30             anchor: '100%',
31             fieldLabel: 'To',
32             name: 'to_date',
33             value: new Date()  // defaults to today
34         }],
35             renderTo: Ext.getBody()
36     });
37
38 #Date Formats Examples#
39
40 This example shows a couple of different date format parsing scenarios. Both use custom date format
41 configurations; the first one matches the configured `format` while the second matches the `altFormats`.
42
43     Ext.create('Ext.form.Panel', {
44         renderTo: Ext.getBody(),
45         width: 300,
46         bodyPadding: 10,
47         title: 'Dates',
48         items: [{
49             xtype: 'datefield',
50             anchor: '100%',
51             fieldLabel: 'Date',
52             name: 'date',
53             // The value matches the format; will be parsed and displayed using that format.
54             format: 'm d Y',
55             value: '2 4 1978'
56         }, {
57             xtype: 'datefield',
58             anchor: '100%',
59             fieldLabel: 'Date',
60             name: 'date',
61             // The value does not match the format, but does match an altFormat; will be parsed
62             // using the altFormat and displayed using the format.
63             format: 'm d Y',
64             altFormats: 'm,d,Y|m.d.Y',
65             value: '2.4.1978'
66         }]
67     });
68
69  * @constructor
70  * Create a new Date field
71  * @param {Object} config
72  * 
73  * @xtype datefield
74  * @markdown
75  * @docauthor Jason Johnston <jason@sencha.com>
76  */
77 Ext.define('Ext.form.field.Date', {
78     extend:'Ext.form.field.Picker',
79     alias: 'widget.datefield',
80     requires: ['Ext.picker.Date'],
81     alternateClassName: ['Ext.form.DateField', 'Ext.form.Date'],
82
83     /**
84      * @cfg {String} format
85      * The default date format string which can be overriden for localization support.  The format must be
86      * valid according to {@link Ext.Date#parse} (defaults to <tt>'m/d/Y'</tt>).
87      */
88     format : "m/d/Y",
89     /**
90      * @cfg {String} altFormats
91      * Multiple date formats separated by "<tt>|</tt>" to try when parsing a user input value and it
92      * does not match the defined format (defaults to
93      * <tt>'m/d/Y|n/j/Y|n/j/y|m/j/y|n/d/y|m/j/Y|n/d/Y|m-d-y|m-d-Y|m/d|m-d|md|mdy|mdY|d|Y-m-d|n-j|n/j'</tt>).
94      */
95     altFormats : "m/d/Y|n/j/Y|n/j/y|m/j/y|n/d/y|m/j/Y|n/d/Y|m-d-y|m-d-Y|m/d|m-d|md|mdy|mdY|d|Y-m-d|n-j|n/j",
96     /**
97      * @cfg {String} disabledDaysText
98      * The tooltip to display when the date falls on a disabled day (defaults to <tt>'Disabled'</tt>)
99      */
100     disabledDaysText : "Disabled",
101     /**
102      * @cfg {String} disabledDatesText
103      * The tooltip text to display when the date falls on a disabled date (defaults to <tt>'Disabled'</tt>)
104      */
105     disabledDatesText : "Disabled",
106     /**
107      * @cfg {String} minText
108      * The error text to display when the date in the cell is before <tt>{@link #minValue}</tt> (defaults to
109      * <tt>'The date in this field must be after {minValue}'</tt>).
110      */
111     minText : "The date in this field must be equal to or after {0}",
112     /**
113      * @cfg {String} maxText
114      * The error text to display when the date in the cell is after <tt>{@link #maxValue}</tt> (defaults to
115      * <tt>'The date in this field must be before {maxValue}'</tt>).
116      */
117     maxText : "The date in this field must be equal to or before {0}",
118     /**
119      * @cfg {String} invalidText
120      * The error text to display when the date in the field is invalid (defaults to
121      * <tt>'{value} is not a valid date - it must be in the format {format}'</tt>).
122      */
123     invalidText : "{0} is not a valid date - it must be in the format {1}",
124     /**
125      * @cfg {String} triggerCls
126      * An additional CSS class used to style the trigger button.  The trigger will always get the
127      * class <tt>'x-form-trigger'</tt> and <tt>triggerCls</tt> will be <b>appended</b> if specified
128      * (defaults to <tt>'x-form-date-trigger'</tt> which displays a calendar icon).
129      */
130     triggerCls : Ext.baseCSSPrefix + 'form-date-trigger',
131     /**
132      * @cfg {Boolean} showToday
133      * <tt>false</tt> to hide the footer area of the Date picker containing the Today button and disable
134      * the keyboard handler for spacebar that selects the current date (defaults to <tt>true</tt>).
135      */
136     showToday : true,
137     /**
138      * @cfg {Date/String} minValue
139      * The minimum allowed date. Can be either a Javascript date object or a string date in a
140      * valid format (defaults to undefined).
141      */
142     /**
143      * @cfg {Date/String} maxValue
144      * The maximum allowed date. Can be either a Javascript date object or a string date in a
145      * valid format (defaults to undefined).
146      */
147     /**
148      * @cfg {Array} disabledDays
149      * An array of days to disable, 0 based (defaults to undefined). Some examples:<pre><code>
150 // disable Sunday and Saturday:
151 disabledDays:  [0, 6]
152 // disable weekdays:
153 disabledDays: [1,2,3,4,5]
154      * </code></pre>
155      */
156     /**
157      * @cfg {Array} disabledDates
158      * An array of "dates" to disable, as strings. These strings will be used to build a dynamic regular
159      * expression so they are very powerful. Some examples:<pre><code>
160 // disable these exact dates:
161 disabledDates: ["03/08/2003", "09/16/2003"]
162 // disable these days for every year:
163 disabledDates: ["03/08", "09/16"]
164 // only match the beginning (useful if you are using short years):
165 disabledDates: ["^03/08"]
166 // disable every day in March 2006:
167 disabledDates: ["03/../2006"]
168 // disable every day in every March:
169 disabledDates: ["^03"]
170      * </code></pre>
171      * Note that the format of the dates included in the array should exactly match the {@link #format} config.
172      * In order to support regular expressions, if you are using a {@link #format date format} that has "." in
173      * it, you will have to escape the dot when restricting dates. For example: <tt>["03\\.08\\.03"]</tt>.
174      */
175     
176     /**
177      * @cfg {String} submitFormat The date format string which will be submitted to the server.  
178      * The format must be valid according to {@link Ext.Date#parse} (defaults to <tt>{@link #format}</tt>).
179      */
180
181     // in the absence of a time value, a default value of 12 noon will be used
182     // (note: 12 noon was chosen because it steers well clear of all DST timezone changes)
183     initTime: '12', // 24 hour format
184
185     initTimeFormat: 'H',
186
187     matchFieldWidth: false,
188     /**
189      * @cfg {Number} startDay
190      * Day index at which the week should begin, 0-based (defaults to 0, which is Sunday)
191      */
192     startDay: 0,
193     
194     initComponent : function(){
195         var me = this,
196             isString = Ext.isString,
197             min, max;
198
199         min = me.minValue;
200         max = me.maxValue;
201         if(isString(min)){
202             me.minValue = me.parseDate(min);
203         }
204         if(isString(max)){
205             me.maxValue = me.parseDate(max);
206         }
207         me.disabledDatesRE = null;
208         me.initDisabledDays();
209
210         me.callParent();
211     },
212
213     initValue: function() {
214         var me = this,
215             value = me.value;
216
217         // If a String value was supplied, try to convert it to a proper Date
218         if (Ext.isString(value)) {
219             me.value = me.rawToValue(value);
220         }
221
222         me.callParent();
223     },
224
225     // private
226     initDisabledDays : function(){
227         if(this.disabledDates){
228             var dd = this.disabledDates,
229                 len = dd.length - 1,
230                 re = "(?:";
231
232             Ext.each(dd, function(d, i){
233                 re += Ext.isDate(d) ? '^' + Ext.String.escapeRegex(d.dateFormat(this.format)) + '$' : dd[i];
234                 if (i !== len) {
235                     re += '|';
236                 }
237             }, this);
238             this.disabledDatesRE = new RegExp(re + ')');
239         }
240     },
241
242     /**
243      * Replaces any existing disabled dates with new values and refreshes the Date picker.
244      * @param {Array} disabledDates An array of date strings (see the <tt>{@link #disabledDates}</tt> config
245      * for details on supported values) used to disable a pattern of dates.
246      */
247     setDisabledDates : function(dd){
248         var me = this,
249             picker = me.picker;
250             
251         me.disabledDates = dd;
252         me.initDisabledDays();
253         if (picker) {
254             picker.setDisabledDates(me.disabledDatesRE);
255         }
256     },
257
258     /**
259      * Replaces any existing disabled days (by index, 0-6) with new values and refreshes the Date picker.
260      * @param {Array} disabledDays An array of disabled day indexes. See the <tt>{@link #disabledDays}</tt>
261      * config for details on supported values.
262      */
263     setDisabledDays : function(dd){
264         var picker = this.picker;
265             
266         this.disabledDays = dd;
267         if (picker) {
268             picker.setDisabledDays(dd);
269         }
270     },
271
272     /**
273      * Replaces any existing <tt>{@link #minValue}</tt> with the new value and refreshes the Date picker.
274      * @param {Date} value The minimum date that can be selected
275      */
276     setMinValue : function(dt){
277         var me = this,
278             picker = me.picker,
279             minValue = (Ext.isString(dt) ? me.parseDate(dt) : dt);
280             
281         me.minValue = minValue;
282         if (picker) {
283             picker.minText = Ext.String.format(me.minText, me.formatDate(me.minValue));
284             picker.setMinDate(minValue);
285         }
286     },
287
288     /**
289      * Replaces any existing <tt>{@link #maxValue}</tt> with the new value and refreshes the Date picker.
290      * @param {Date} value The maximum date that can be selected
291      */
292     setMaxValue : function(dt){
293         var me = this,
294             picker = me.picker,
295             maxValue = (Ext.isString(dt) ? me.parseDate(dt) : dt);
296             
297         me.maxValue = maxValue;
298         if (picker) {
299             picker.maxText = Ext.String.format(me.maxText, me.formatDate(me.maxValue));
300             picker.setMaxDate(maxValue);
301         }
302     },
303
304     /**
305      * Runs all of Date's validations and returns an array of any errors. Note that this first
306      * runs Text's validations, so the returned array is an amalgamation of all field errors.
307      * The additional validation checks are testing that the date format is valid, that the chosen
308      * date is within the min and max date constraints set, that the date chosen is not in the disabledDates
309      * regex and that the day chosed is not one of the disabledDays.
310      * @param {Mixed} value The value to get errors for (defaults to the current field value)
311      * @return {Array} All validation errors for this field
312      */
313     getErrors: function(value) {
314         var me = this,
315             format = Ext.String.format,
316             clearTime = Ext.Date.clearTime,
317             errors = me.callParent(arguments),
318             disabledDays = me.disabledDays,
319             disabledDatesRE = me.disabledDatesRE,
320             minValue = me.minValue,
321             maxValue = me.maxValue,
322             len = disabledDays ? disabledDays.length : 0,
323             i = 0,
324             svalue,
325             fvalue,
326             day,
327             time;
328
329         value = me.formatDate(value || me.processRawValue(me.getRawValue()));
330
331         if (value === null || value.length < 1) { // if it's blank and textfield didn't flag it then it's valid
332              return errors;
333         }
334
335         svalue = value;
336         value = me.parseDate(value);
337         if (!value) {
338             errors.push(format(me.invalidText, svalue, me.format));
339             return errors;
340         }
341
342         time = value.getTime();
343         if (minValue && time < clearTime(minValue).getTime()) {
344             errors.push(format(me.minText, me.formatDate(minValue)));
345         }
346
347         if (maxValue && time > clearTime(maxValue).getTime()) {
348             errors.push(format(me.maxText, me.formatDate(maxValue)));
349         }
350
351         if (disabledDays) {
352             day = value.getDay();
353
354             for(; i < len; i++) {
355                 if (day === disabledDays[i]) {
356                     errors.push(me.disabledDaysText);
357                     break;
358                 }
359             }
360         }
361
362         fvalue = me.formatDate(value);
363         if (disabledDatesRE && disabledDatesRE.test(fvalue)) {
364             errors.push(format(me.disabledDatesText, fvalue));
365         }
366
367         return errors;
368     },
369
370     rawToValue: function(rawValue) {
371         return this.parseDate(rawValue) || rawValue || null;
372     },
373
374     valueToRaw: function(value) {
375         return this.formatDate(this.parseDate(value));
376     },
377
378     /**
379      * Sets the value of the date field.  You can pass a date object or any string that can be
380      * parsed into a valid date, using <tt>{@link #format}</tt> as the date format, according
381      * to the same rules as {@link Ext.Date#parse} (the default format used is <tt>"m/d/Y"</tt>).
382      * <br />Usage:
383      * <pre><code>
384 //All of these calls set the same date value (May 4, 2006)
385
386 //Pass a date object:
387 var dt = new Date('5/4/2006');
388 dateField.setValue(dt);
389
390 //Pass a date string (default format):
391 dateField.setValue('05/04/2006');
392
393 //Pass a date string (custom format):
394 dateField.format = 'Y-m-d';
395 dateField.setValue('2006-05-04');
396 </code></pre>
397      * @param {String/Date} date The date or valid date string
398      * @return {Ext.form.field.Date} this
399      * @method setValue
400      */
401
402     /**
403      * Attempts to parse a given string value using a given {@link Ext.Date#parse date format}.
404      * @param {String} value The value to attempt to parse
405      * @param {String} format A valid date format (see {@link Ext.Date#parse})
406      * @return {Date} The parsed Date object, or null if the value could not be successfully parsed.
407      */
408     safeParse : function(value, format) {
409         var me = this,
410             utilDate = Ext.Date,
411             parsedDate,
412             result = null;
413             
414         if (utilDate.formatContainsHourInfo(format)) {
415             // if parse format contains hour information, no DST adjustment is necessary
416             result = utilDate.parse(value, format);
417         } else {
418             // set time to 12 noon, then clear the time
419             parsedDate = utilDate.parse(value + ' ' + me.initTime, format + ' ' + me.initTimeFormat);
420             if (parsedDate) {
421                 result = utilDate.clearTime(parsedDate);
422             }
423         }
424         return result;
425     },
426     
427     // @private
428     getSubmitValue: function() {
429         var me = this,
430             format = me.submitFormat || me.format,
431             value = me.getValue();
432             
433         return value ? Ext.Date.format(value, format) : null;
434     },
435
436     /**
437      * @private
438      */
439     parseDate : function(value) {
440         if(!value || Ext.isDate(value)){
441             return value;
442         }
443
444         var me = this,
445             val = me.safeParse(value, me.format),
446             altFormats = me.altFormats,
447             altFormatsArray = me.altFormatsArray,
448             i = 0,
449             len;
450
451         if (!val && altFormats) {
452             altFormatsArray = altFormatsArray || altFormats.split('|');
453             len = altFormatsArray.length;
454             for (; i < len && !val; ++i) {
455                 val = me.safeParse(value, altFormatsArray[i]);
456             }
457         }
458         return val;
459     },
460
461     // private
462     formatDate : function(date){
463         return Ext.isDate(date) ? Ext.Date.dateFormat(date, this.format) : date;
464     },
465
466     createPicker: function() {
467         var me = this,
468             format = Ext.String.format;
469
470         return Ext.create('Ext.picker.Date', {
471             ownerCt: me.ownerCt,
472             renderTo: document.body,
473             floating: true,
474             hidden: true,
475             focusOnShow: true,
476             minDate: me.minValue,
477             maxDate: me.maxValue,
478             disabledDatesRE: me.disabledDatesRE,
479             disabledDatesText: me.disabledDatesText,
480             disabledDays: me.disabledDays,
481             disabledDaysText: me.disabledDaysText,
482             format: me.format,
483             showToday: me.showToday,
484             startDay: me.startDay,
485             minText: format(me.minText, me.formatDate(me.minValue)),
486             maxText: format(me.maxText, me.formatDate(me.maxValue)),
487             listeners: {
488                 scope: me,
489                 select: me.onSelect
490             },
491             keyNavConfig: {
492                 esc: function() {
493                     me.collapse();
494                 }
495             }
496         });
497     },
498
499     onSelect: function(m, d) {
500         var me = this;
501         
502         me.setValue(d);
503         me.fireEvent('select', me, d);
504         me.collapse();
505     },
506
507     /**
508      * @private
509      * Sets the Date picker's value to match the current field value when expanding.
510      */
511     onExpand: function() {
512         var me = this,
513             value = me.getValue();
514         me.picker.setValue(Ext.isDate(value) ? value : new Date());
515     },
516
517     /**
518      * @private
519      * Focuses the field when collapsing the Date picker.
520      */
521     onCollapse: function() {
522         this.focus(false, 60);
523     },
524
525     // private
526     beforeBlur : function(){
527         var me = this,
528             v = me.parseDate(me.getRawValue()),
529             focusTask = me.focusTask;
530         
531         if (focusTask) {
532             focusTask.cancel();
533         }
534         
535         if (v) {
536             me.setValue(v);
537         }
538     }
539
540     /**
541      * @cfg {Boolean} grow @hide
542      */
543     /**
544      * @cfg {Number} growMin @hide
545      */
546     /**
547      * @cfg {Number} growMax @hide
548      */
549     /**
550      * @hide
551      * @method autoSize
552      */
553 });