X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/0494b8d9b9bb03ab6c22b34dae81261e3cd7e3e6..7a654f8d43fdb43d78b63d90528bed6e86b608cc:/docs/source/Time.html?ds=sidebyside diff --git a/docs/source/Time.html b/docs/source/Time.html new file mode 100644 index 00000000..3805e0e3 --- /dev/null +++ b/docs/source/Time.html @@ -0,0 +1,418 @@ +Sencha Documentation Project
/**
+ * @class Ext.form.field.Time
+ * @extends Ext.form.field.Picker
+ * <p>Provides a time input field with a time dropdown and automatic time validation.</p>
+ * <p>This field recognizes and uses JavaScript Date objects as its main {@link #value} type (only the time
+ * portion of the date is used; the month/day/year are ignored). In addition, it recognizes string values which
+ * are parsed according to the {@link #format} and/or {@link #altFormats} configs. These may be reconfigured
+ * to use time formats appropriate for the user's locale.</p>
+ * <p>The field may be limited to a certain range of times by using the {@link #minValue} and {@link #maxValue}
+ * configs, and the interval between time options in the dropdown can be changed with the {@link #increment} config.</p>
+ * {@img Ext.form.Time/Ext.form.Time.png Ext.form.Time component}
+ * <p>Example usage:</p>
+ * <pre><code>
+Ext.create('Ext.form.Panel', {
+    title: 'Time Card',
+    width: 300,
+    bodyPadding: 10,
+    renderTo: Ext.getBody(),        
+    items: [{
+        xtype: 'timefield',
+        name: 'in',
+        fieldLabel: 'Time In',
+        minValue: '6:00 AM',
+        maxValue: '8:00 PM',
+        increment: 30,
+        anchor: '100%'
+    }, {
+        xtype: 'timefield',
+        name: 'out',
+        fieldLabel: 'Time Out',
+        minValue: '6:00 AM',
+        maxValue: '8:00 PM',
+        increment: 30,
+        anchor: '100%'
+   }]
+});
+</code></pre>
+ * @constructor
+ * Create a new Time field
+ * @param {Object} config
+ * @xtype timefield
+ */
+Ext.define('Ext.form.field.Time', {
+    extend:'Ext.form.field.Picker',
+    alias: 'widget.timefield',
+    requires: ['Ext.form.field.Date', 'Ext.picker.Time', 'Ext.view.BoundListKeyNav', 'Ext.Date'],
+    alternateClassName: ['Ext.form.TimeField', 'Ext.form.Time'],
+
+    /**
+     * @cfg {String} triggerCls
+     * An additional CSS class used to style the trigger button.  The trigger will always get the
+     * {@link #triggerBaseCls} by default and <tt>triggerCls</tt> will be <b>appended</b> if specified.
+     * Defaults to <tt>'x-form-time-trigger'</tt> for the Time field trigger.
+     */
+    triggerCls: Ext.baseCSSPrefix + 'form-time-trigger',
+
+    /**
+     * @cfg {Date/String} minValue
+     * The minimum allowed time. Can be either a Javascript date object with a valid time value or a string
+     * time in a valid format -- see {@link #format} and {@link #altFormats} (defaults to undefined).
+     */
+
+    /**
+     * @cfg {Date/String} maxValue
+     * The maximum allowed time. Can be either a Javascript date object with a valid time value or a string
+     * time in a valid format -- see {@link #format} and {@link #altFormats} (defaults to undefined).
+     */
+
+    /**
+     * @cfg {String} minText
+     * The error text to display when the entered time is before {@link #minValue} (defaults to
+     * 'The time in this field must be equal to or after {0}').
+     */
+    minText : "The time in this field must be equal to or after {0}",
+
+    /**
+     * @cfg {String} maxText
+     * The error text to display when the entered time is after {@link #maxValue} (defaults to
+     * 'The time in this field must be equal to or before {0}').
+     */
+    maxText : "The time in this field must be equal to or before {0}",
+
+    /**
+     * @cfg {String} invalidText
+     * The error text to display when the time in the field is invalid (defaults to
+     * '{value} is not a valid time').
+     */
+    invalidText : "{0} is not a valid time",
+
+    /**
+     * @cfg {String} format
+     * The default time format string which can be overriden for localization support.  The format must be
+     * valid according to {@link Ext.Date#parse} (defaults to 'g:i A', e.g., '3:15 PM').  For 24-hour time
+     * format try 'H:i' instead.
+     */
+    format : "g:i A",
+
+    /**
+     * @cfg {String} submitFormat The date format string which will be submitted to the server.
+     * The format must be valid according to {@link Ext.Date#parse} (defaults to <tt>{@link #format}</tt>).
+     */
+
+    /**
+     * @cfg {String} altFormats
+     * Multiple date formats separated by "|" to try when parsing a user input value and it doesn't match the defined
+     * 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').
+     */
+    altFormats : "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",
+
+    /**
+     * @cfg {Number} increment
+     * The number of minutes between each time value in the list (defaults to 15).
+     */
+    increment: 15,
+
+    /**
+     * @cfg {Number} pickerMaxHeight
+     * The maximum height of the {@link Ext.picker.Time} dropdown. Defaults to 300.
+     */
+    pickerMaxHeight: 300,
+
+    /**
+     * @cfg {Boolean} selectOnTab
+     * Whether the Tab key should select the currently highlighted item. Defaults to <tt>true</tt>.
+     */
+    selectOnTab: true,
+
+    /**
+     * @private
+     * This is the date to use when generating time values in the absence of either minValue
+     * or maxValue.  Using the current date causes DST issues on DST boundary dates, so this is an
+     * arbitrary "safe" date that can be any date aside from DST boundary dates.
+     */
+    initDate: '1/1/2008',
+    initDateFormat: 'j/n/Y',
+
+
+    initComponent: function() {
+        var me = this,
+            min = me.minValue,
+            max = me.maxValue;
+        if (min) {
+            me.setMinValue(min);
+        }
+        if (max) {
+            me.setMaxValue(max);
+        }
+        this.callParent();
+    },
+
+    initValue: function() {
+        var me = this,
+            value = me.value;
+
+        // If a String value was supplied, try to convert it to a proper Date object
+        if (Ext.isString(value)) {
+            me.value = me.rawToValue(value);
+        }
+
+        me.callParent();
+    },
+
+    /**
+     * Replaces any existing {@link #minValue} with the new time and refreshes the picker's range.
+     * @param {Date/String} value The minimum time that can be selected
+     */
+    setMinValue: function(value) {
+        var me = this,
+            picker = me.picker;
+        me.setLimit(value, true);
+        if (picker) {
+            picker.setMinValue(me.minValue);
+        }
+    },
+
+    /**
+     * Replaces any existing {@link #maxValue} with the new time and refreshes the picker's range.
+     * @param {Date/String} value The maximum time that can be selected
+     */
+    setMaxValue: function(value) {
+        var me = this,
+            picker = me.picker;
+        me.setLimit(value, false);
+        if (picker) {
+            picker.setMaxValue(me.maxValue);
+        }
+    },
+
+    /**
+     * @private
+     * Updates either the min or max value. Converts the user's value into a Date object whose
+     * year/month/day is set to the {@link #initDate} so that only the time fields are significant.
+     */
+    setLimit: function(value, isMin) {
+        var me = this,
+            d, val;
+        if (Ext.isString(value)) {
+            d = me.parseDate(value);
+        }
+        else if (Ext.isDate(value)) {
+            d = value;
+        }
+        if (d) {
+            val = Ext.Date.clearTime(new Date(me.initDate));
+            val.setHours(d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
+            me[isMin ? 'minValue' : 'maxValue'] = val;
+        }
+    },
+
+    rawToValue: function(rawValue) {
+        return this.parseDate(rawValue) || rawValue || null;
+    },
+
+    valueToRaw: function(value) {
+        return this.formatDate(this.parseDate(value));
+    },
+
+    /**
+     * Runs all of Time's validations and returns an array of any errors. Note that this first
+     * runs Text's validations, so the returned array is an amalgamation of all field errors.
+     * The additional validation checks are testing that the time format is valid, that the chosen
+     * time is within the {@link #minValue} and {@link #maxValue} constraints set.
+     * @param {Mixed} value The value to get errors for (defaults to the current field value)
+     * @return {Array} All validation errors for this field
+     */
+    getErrors: function(value) {
+        var me = this,
+            format = Ext.String.format,
+            errors = me.callParent(arguments),
+            minValue = me.minValue,
+            maxValue = me.maxValue,
+            date;
+
+        value = me.formatDate(value || me.processRawValue(me.getRawValue()));
+
+        if (value === null || value.length < 1) { // if it's blank and textfield didn't flag it then it's valid
+             return errors;
+        }
+
+        date = me.parseDate(value);
+        if (!date) {
+            errors.push(format(me.invalidText, value, me.format));
+            return errors;
+        }
+
+        if (minValue && date < minValue) {
+            errors.push(format(me.minText, me.formatDate(minValue)));
+        }
+
+        if (maxValue && date > maxValue) {
+            errors.push(format(me.maxText, me.formatDate(maxValue)));
+        }
+
+        return errors;
+    },
+
+    formatDate: function() {
+        return Ext.form.field.Date.prototype.formatDate.apply(this, arguments);
+    },
+
+    /**
+     * @private
+     * Parses an input value into a valid Date object.
+     * @param {String/Date} value
+     */
+    parseDate: function(value) {
+        if (!value || Ext.isDate(value)) {
+            return value;
+        }
+
+        var me = this,
+            val = me.safeParse(value, me.format),
+            altFormats = me.altFormats,
+            altFormatsArray = me.altFormatsArray,
+            i = 0,
+            len;
+
+        if (!val && altFormats) {
+            altFormatsArray = altFormatsArray || altFormats.split('|');
+            len = altFormatsArray.length;
+            for (; i < len && !val; ++i) {
+                val = me.safeParse(value, altFormatsArray[i]);
+            }
+        }
+        return val;
+    },
+
+    safeParse: function(value, format){
+        var me = this,
+            utilDate = Ext.Date,
+            parsedDate,
+            result = null;
+
+        if (utilDate.formatContainsDateInfo(format)) {
+            // assume we've been given a full date
+            result = utilDate.parse(value, format);
+        } else {
+            // Use our initial safe date
+            parsedDate = utilDate.parse(me.initDate + ' ' + value, me.initDateFormat + ' ' + format);
+            if (parsedDate) {
+                result = parsedDate;
+            }
+        }
+        return result;
+    },
+
+    // @private
+    getSubmitValue: function() {
+        var me = this,
+            format = me.submitFormat || me.format,
+            value = me.getValue();
+
+        return value ? Ext.Date.format(value, format) : null;
+    },
+
+    /**
+     * @private
+     * Creates the {@link Ext.picker.Time}
+     */
+    createPicker: function() {
+        var me = this,
+            picker = Ext.create('Ext.picker.Time', {
+                selModel: {
+                    mode: 'SINGLE'
+                },
+                floating: true,
+                hidden: true,
+                minValue: me.minValue,
+                maxValue: me.maxValue,
+                increment: me.increment,
+                format: me.format,
+                ownerCt: this.ownerCt,
+                renderTo: document.body,
+                maxHeight: me.pickerMaxHeight,
+                focusOnToFront: false
+            });
+
+        me.mon(picker.getSelectionModel(), {
+            selectionchange: me.onListSelect,
+            scope: me
+        });
+
+        return picker;
+    },
+
+    /**
+     * @private
+     * Enables the key nav for the Time picker when it is expanded.
+     * TODO this is largely the same logic as ComboBox, should factor out.
+     */
+    onExpand: function() {
+        var me = this,
+            keyNav = me.pickerKeyNav,
+            selectOnTab = me.selectOnTab,
+            picker = me.getPicker(),
+            lastSelected = picker.getSelectionModel().lastSelected,
+            itemNode;
+
+        if (!keyNav) {
+            keyNav = me.pickerKeyNav = Ext.create('Ext.view.BoundListKeyNav', this.inputEl, {
+                boundList: picker,
+                forceKeyDown: true,
+                tab: function(e) {
+                    if (selectOnTab) {
+                        this.selectHighlighted(e);
+                        me.triggerBlur();
+                    }
+                    // Tab key event is allowed to propagate to field
+                    return true;
+                }
+            });
+            // stop tab monitoring from Ext.form.field.Trigger so it doesn't short-circuit selectOnTab
+            if (selectOnTab) {
+                me.ignoreMonitorTab = true;
+            }
+        }
+        Ext.defer(keyNav.enable, 1, keyNav); //wait a bit so it doesn't react to the down arrow opening the picker
+
+        // Highlight the last selected item and scroll it into view
+        if (lastSelected) {
+            itemNode = picker.getNode(lastSelected);
+            if (itemNode) {
+                picker.highlightItem(itemNode);
+                picker.el.scrollChildIntoView(itemNode, false);
+            }
+        }
+    },
+
+    /**
+     * @private
+     * Disables the key nav for the Time picker when it is collapsed.
+     */
+    onCollapse: function() {
+        var me = this,
+            keyNav = me.pickerKeyNav;
+        if (keyNav) {
+            keyNav.disable();
+            me.ignoreMonitorTab = false;
+        }
+    },
+
+    /**
+     * @private
+     * Handles a time being selected from the Time picker.
+     */
+    onListSelect: function(list, recordArray) {
+        var me = this,
+            record = recordArray[0],
+            val = record ? record.get('date') : null;
+        me.setValue(val);
+        me.fireEvent('select', me, val);
+        me.picker.clearHighlight();
+        me.collapse();
+        me.inputEl.focus();
+    }
+});
+
+
\ No newline at end of file