DateField

A Date field widget consisting of a date input field + a date picker.

Date field
//<code-header>
fiddle.title = 'Date field';
CSSHelper.insertRule('#datePickerRenderer .b-calendar-panel-cell .b-date-picker-cell-inner { padding:0.5em 1.2em 1.2em 1.2em;}', targetElement.getRootNode());
CSSHelper.insertRule('#datePickerRenderer .b-date-picker-cell-payload { bottom:0.75em;}', targetElement.getRootNode());
CSSHelper.insertRule('.price { font-size: 0.7em;}', targetElement.getRootNode());
CSSHelper.insertRule('.b-calendar-panel-cell:not(.b-active-date) .price { opacity:0.65; }', targetElement.getRootNode());
//</code-header>
const prices = [
    110, 80, 0, 70, 120, 80, 90,
    90, 110, 80, 0, 0, 120, 80, 90,
    90, 130, 60, 0, 70, 80, 90
];

// uneditable datefield (user only allowed to use picker)
new DateField({
    labelPosition : 'above',
    label         : 'Not editable',
    editable      : false,
    appendTo      : targetElement,
    style         : 'margin-right: .5em'
});

//editable datefield (user can type)
new DateField({
    labelPosition : 'above',
    label         : 'Editable',
    editable      : true,
    appendTo      : targetElement,
    style         : 'margin-right: .5em',
    picker        : {
        id            : 'datePickerRenderer',
        disabledDates : ['2025-01-10'],
        date          : '2025-01-03',
        // Show some extra info in each day cell
        cellRenderer({ cell, cellPayload, date }) {
            const
                sameMonth = date.getMonth() === this.date.getMonth(),
                price     = prices[date.getDate()];

            cellPayload.classList.add('price');
            cellPayload.innerHTML = `${sameMonth && price ? ('$' + price) : '&nbsp;'}`;

            delete cell.dataset.btip;
            if (sameMonth) {
                cell.dataset.btip = price ? `Flights available from: <strong>$${price}</strong>` : 'No flights available';
            }
        }
    }
});

//invalid datefield
new DateField({
    labelPosition : 'above',
    label         : 'Invalid',
    min           : new Date(2018, 4, 18),
    value         : new Date(2018, 4, 17),
    editable      : true,
    appendTo      : targetElement
});

It can be configured to allow user typing dates, or to only allow selection from the date picker (see editable). It can also validate that the date is within a specified range (see min -> max). It also optionally show step triggers to increment or decrement the date (see step & stepTriggers):

Basic date field
//<code-header>
fiddle.title = 'Basic date field';
//</code-header>
// Uneditable datefield (user only allowed to use picker)
new DateField({
    labelPosition : 'above',
    appendTo      : targetElement,
    label         : 'Not editable',
    editable      : false,
    style         : 'margin-right: .5em'
});

// Invalid datefield
new DateField({
    labelPosition : 'above',
    appendTo      : targetElement,
    label         : 'Invalid',
    min           : new Date(2018, 4, 18),
    value         : new Date(2018, 4, 17),
    editable      : true,
    style         : 'margin-right: .5em'
});

// DateField with step triggers
new DateField({
    labelPosition : 'above',
    appendTo      : targetElement,
    label         : 'Step triggers',
    step          : '1d',
    value         : new Date()
});

This field can be used as an editor for a grid column. It is used as the default editor for the DateColumn class.

// minimal DateField config with date format specified
const dateField = new DateField({
  format: 'YYMMDD'
});

Accessibility

This widget can be operated using the keyboard. When the field is focused, ArrowDown opens the date picker, which itself is keyboard navigable. Shift+ArrowDown activates the step back trigger. Shift+ArrowUp activates the step forwards trigger.

Configs

123

Common

editablePickerField
listenersEvents

Other

Format for date displayed in field. Defaults to using long date format, as defined by current locale (L)

keepTime: Boolean | Date | String= false

A flag which indicates what time should be used for selected date. false by default which means time is reset to midnight.

Possible options are:

  • false to reset time to midnight
  • true to keep original time value
  • '17:00' a string which is parsed automatically
  • new Date(2020, 0, 1, 17) a date object to copy time from
  • 'entered' to keep time value entered by user (in case format includes time info)
max: String | DateAlso a property

Max value

min: String | DateAlso a property

Min value

A reference to a partner TimeField which this DateField should sync its value with. When the TimeField's value is changed, this DateField's value is updated to match. When this DateField's value is changed, the TimeField's value is updated to match.

When a string is passed, this is taken to be the widget's reference property and the actual TimeField is looked up in the same owner container as this TimeField. If the reference cannot be found there, the string is used as a widget id.

A config object used to configure the datePicker.

dateField = new DateField({
    picker : {
        tbar : {
            items : {
                // Remove the prev year and next year buttons by setting them to null.
                // Move the prev month button to just before the next month button by increasing its weight
                prevYear  : null,
                nextYear  : null,
                prevMonth : {
                    weight : 390
                }
            }
        }
    }
pickerFormat: String

Format for date in the picker. Uses localized format per default

Time increment duration value. If specified, forward and back triggers are displayed. The value is taken to be a string consisting of the numeric magnitude and the units. The units may be a recognised unit abbreviation of this locale or the full local unit name. For example '1d' or '1w' or '1 week'. This may be specified as an object containing two properties: magnitude, a Number, and unit, a String

stepTriggers: Boolean= true

Set to false to hide the forward and backward date step triggers. These triggers are only shown when step is set.

strictParsing: Boolean= false

A flag which indicates whether the date parsing should be strict - meaning if the date is missing a year/month/day part - parsing fails.

Turned off by default, meaning default values are substituted for missing parts.

Widgets that trigger functionality upon click. Each trigger icon is a Widget instance which may be hidden, shown and observed and styled just like any other widget.

ParameterTypeDescription
triggers.expandFieldTriggerConfig

Expands the date picker to select a date

triggers.backFieldTriggerConfig

Subtracts the step from the current date

triggers.forwardFieldTriggerConfig

Adds the step to the current date

triggers.clearFieldTriggerConfig

Clears the field value, only available if this field is clearable

value: String | DateAlso a property

Value, which can be a Date or a string. If a string is specified, it will be converted using the specified format

weekStartDay: Number

The week start day in the picker, 0 meaning Sunday, 6 meaning Saturday. Uses localized value per default.

columnWidget
nameField
renditionTextField
rtlRTL
spanWidget

Accessibility

ariaLabelWidget
keyMapKeyMap

Container

inlineField

CSS

clsWidget
colorWidget
htmlClsWidget
styleWidget
uiWidget

DOM

adoptWidget
appendToWidget
contentWidget
datasetWidget
htmlWidget
idWidget
tagWidget
titleWidget

Field

maxLengthTextField
minLengthTextField

Float & align

alignWidget
anchorWidget
centeredWidget
draggableWidget
floatingWidget
xWidget
yWidget

Input element

Label

hintField
labelLabelable
labelClsLabelable
labelPositionLabelable
labelsField
labelWidthLabelable

Layout

alignSelfWidget
dockWidget
flexWidget
heightWidget
hiddenWidget
marginWidget
maxHeightWidget
maxWidthWidget
minHeightWidget
minWidthWidget
textAlignWidget
weightWidget
widthWidget

Misc

badgeBadge
dataFieldWidget
disabledWidget
localeClassLocalizable
localizableLocalizable
maskedWidget
ownerWidget
refWidget
rippleWidget
tabWidget
tooltipWidget

Picker

autoExpandPickerField

Scrolling

Properties

93

Class hierarchy

isDateField: Boolean= truereadonly
Identifies an object as an instance of DateField class, or subclass thereof.
isDateField: Boolean= truereadonlystatic
Identifies an object as an instance of DateField class, or subclass thereof.
isBadgeBadge
isDelayableDelayable
isEventsEvents
isFieldField
isFormulaFieldFormulaField
isKeyMapKeyMap
isLabelableLabelable
isLocalizableLocalizable
isPickerFieldPickerField
isTextFieldTextField
isValidatableValidatable
isWidgetWidget

Other

Get / set format for date displayed in field (see format for formatting options).

Get/set max value, which can be a Date or a string. If a string is specified, it will be converted using the specified format.

Get/set min value, which can be a Date or a string. If a string is specified, it will be converted using the specified format.

A reference to a partner TimeField which this DateField should sync its value with. When the TimeField's value is changed, this DateField's value is updated to match. When this DateField's value is changed, the TimeField's value is updated to match.

When a string is passed, this is taken to be the widget's reference property and the actual TimeField is looked up in the same owner container as this TimeField. If the reference cannot be found there, the string is used as a widget id.

The step property may be set in object form specifying two properties, magnitude, a Number, and unit, a String.

If a Number is passed, the step's current unit is used (or day if no current step set) and just the magnitude is changed.

If a String is passed, it is parsed by parseDuration, for example '1d', '1 d', '1 day', or '1 day'.

Upon read, the value is always returned in object form containing magnitude and unit.

triggers: Object<String, Widget>Also a config

Widgets that trigger functionality upon click. Each trigger icon is a Widget instance which may be hidden, shown and observed and styled just like any other widget.

ParameterTypeDescription
triggers.expandFieldTriggerConfig

Expands the date picker to select a date

triggers.backFieldTriggerConfig

Subtracts the step from the current date

triggers.forwardFieldTriggerConfig

Adds the step to the current date

triggers.clearFieldTriggerConfig

Clears the field value, only available if this field is clearable

Get/set value, which can be set as a Date or a string but always returns a Date. If a string is specified, it will be converted using the specified format

$namestaticWidget
columnWidget
formulaFormulaField
inputField
isEmptyField
isValidField
renditionTextField
rtlRTL
spanWidget
typestaticWidget

Accessibility

keyMapKeyMap

CSS

clsWidget

DOM

appendToWidget
contentWidget
datasetWidget
elementWidget
htmlWidget
idWidget
styleWidget

Float & align

xWidget
yWidget

Layout

alignSelfWidget
flexWidget
heightWidget
marginWidget
maxHeightWidget
maxWidthWidget
minHeightWidget
minWidthWidget
widthWidget

Lifecycle

configBase

Misc

badgeBadge
cellInfoWidget
disabledWidget
errorTipValidatable
labelLabelable
localeHelperLocalizable
localeManagerLocalizable
refWidget
tabWidget
tooltipWidget

Picker

pickerPickerField

Visibility

hiddenWidget
isVisibleWidget

Widget hierarchy

ownerWidget
parentWidget

Functions

67

Configuration

applyDefaultsstaticBase

Events

Float & align

alignToWidget
setXYWidget
showByWidget
toFrontWidget

Lifecycle

createstaticWidget
destroystaticBase
initClassstaticWidget

Misc

attachTooltipstaticWidget
fromElementstaticWidget
fromSelectorstaticWidget
getByIdstaticWidget
isOfTypeNamestaticBase
mixinstaticBase
optionalLstaticLocalizable

Other

clearField
clearErrorValidatable
composeWidget
createOnFrameDelayable
disableWidget
enableWidget
focusWidget
getErrorsValidatable
LstaticLocalizable
maskWidget
onEvents
recomposeWidget
relayAllEvents
selectField
setErrorValidatable
triggerEvents
unEvents
unmaskWidget

Picker

hidePickerPickerField
showPickerPickerField
togglePickerPickerField

Visibility

hideWidget
showWidget

Widget hierarchy

closestWidget
containsWidget
eachWidgetPickerField
ownsWidget
queryWidget
queryAllWidget
upWidget

Events

19

Fired when this field's value changes.

// Adding a listener using the "on" method
dateField.on('change', ({ source, value, oldValue, valid, event, userAction }) => {

});
ParameterTypeDescription
sourceDateField

This DateField

valueDate

This field's value

oldValueDate

This field's previous value

validBoolean

True if this field is in a valid state

eventEvent

The triggering DOM event if any

userActionBoolean

Triggered by user taking an action (true) or by setting a value (false)

actionField
catchAllEvents
clearField
destroyEvents
focusInWidget
focusOutWidget
hideWidget
inputField
paintWidget
readOnlyWidget
recomposeWidget
resizeWidget
showWidget
triggerField

Event handlers

19

Called when this field's value changes.

new DateField({
    onChange({ source, value, oldValue, valid, event, userAction }) {

    }
});
ParameterTypeDescription
sourceDateField

This DateField

valueDate

This field's value

oldValueDate

This field's previous value

validBoolean

True if this field is in a valid state

eventEvent

The triggering DOM event if any

userActionBoolean

Triggered by user taking an action (true) or by setting a value (false)

onClearField
onDestroyEvents
onFocusInWidget
onHideWidget
onInputField
onPaintWidget
onResizeWidget
onShowWidget

Typedefs

7

CSS variables

124