WDateField

WDateField is a component for creating a date input field or reporting a date.

• Why use WDateField
• Creating a WDateField
  • Setting a date
  • Input constraints
    • Mandating input
    • Earliest date
    • Latest date
• Accessibility
  • Custom control
    • Keyboard use
  • Labeling a WDateField
    • Exposing constraints
  • Setting a toolTip
  • Additional labelling text
  • Access Keys
  • Default focus
• Appearance
  • Native control
  • Custom control
  • Setting input size
  • Customising based on HTML class
• HTML output
• Supported date formats
• Read-only
• Change action
• Disabling
• Hiding
• Default submit button
• Related components
• Further information

Why use WDateField

WDateField allows for capture and display of dates in an unambiguous format. WDateField provides the only way to unambiguously obtain a date from a user and is the best way to obtain a date form a user on a mobile device.

WDateField will always use a browser-native date input where one is available. If the browser does not support date inputs (such as Internet Explorer) then an alternate input and display mechanism is used which will ensure an unambiguous date.

Creating a WDateField

There are two constructors for WDateField. A date is not set in either constructor.

WDateField dateField = new WDateField();

// create a WDateField with lenient date parsing
dateField = new WDateField(true);

Setting a date

DateField's value is retained from user input (if any) within the current session. A default or initial value may be set from a data source or manually.

// given WDateField df...
// set its date to today
df.setDate(new Date());

Input constraints

WDateField's input may be constrained in various ways.

Mandating input

A WDateField may be marked as being a mandatory field in the UI. The WLabel for the component is also decorated with a visual indicator that the component is mandatory. This property does not apply if in a read-only state.

// make WDateField `field` mandatory
field.setMandatory(true);

Earliest date

The min property is used to set the earliest date which is acceptable if any date is entered by the user. If this property is set then this minimum date should be indicated in the WLabel for the component (for example in the WLabel's hint). This property does not apply if in a read-only state.

// with WDateField df and Date date:
df.setMinDate(date);

Min does not imply mandatory

Setting a min will not automatically make the component mandatory. The min is validated only if the user has entered a date. To make a component mandatory use the mandatory setter. These properties may be used in conjunction to enforce a required minimum date entry by the user.

Latest date

A WDateField can be constrained to accept a latest acceptable date which can be entered as a valid date. If set then the maximum date should be indicated to the user within the WLabel for the WDateField. This property does not apply if in a read-only state.

// with WDateField df and Date date:
df.setMaxDate(date);

Accessibility

When in an interactive mode WDateField will use the browser's native date input where possible. When not in a read-only state the WDateField must be labelled (see below).

When read-only the date is output in a HTML time element which provides for a machine-readable form of the date. Note WAbbrText must not be used to provide machine-readable dates.

Custom control

If the browser does not provide a native input a custom control set is provided which is completely keyboard driveable and implemented in accordance with WAI-ARIA guidelines. The control provides a calendar based date picker and autocomplete suggestions if the user types directly into the input field.

The displayed value of the custom control is theme dependent. The default is an internationalised unambiguous format.

Keyboard use

The date picker calendar may be launched using only the keyboard using ALT + DOWN as per the WAI-ARIA combo widget and common native implementations. The calendar is completely keyboard drivable including using the ARROW keys to move in two dimensions through the calendar grid. The calendar is closed by selecting a date or by pressing the ESCAPE key. If date suggestions are provided they may be accessed from the text box using the DOWN and UP ARROW keys and a suggestion is selected using the ENTER/RETURN key or SPACEBAR.

A list of suggestions is provided once enough text content is entered into the text input to generate potential dates (see WPartialDateField for more information about this). shortcuts are also available:

• t will enter today's date;
• y will enter yesterday's date;
• m will enter tomorrow's date;
• +N will enter a date N days after today (future); and
• -N will enter a date N days before today (past).

Labeling a WDateField

All WDateFields in a UI must be associated with a label or otherwise have their usage and intent exposed to all users. This may be done using (in order of preference):

• WLabel or by using the WDateField in a WField (preferred) this is required if the label must be visible in the UI; or
• using the toolTip property if the label does not have to be visible in the UI; or
• using the accessibleText property of WDateField.

When designing a UI containing a WDateField the WLabel must be placed immediately before or above the control.

A WDateField which is not appropriately labelled may display an unlabelled control warning.

Exposing constraints

If the WDateField has input constraints then there must be an indication of these constraints somewhere in the UI and available to all users. The appropriate place for this information is in the WLabel hint. If the control is mandatory this indication is automatically generated within the label.

Setting a toolTip

See toolTip. A WDateField may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.

// with WDateField field
field.setToolTip("Some further context to this date.");

Additional labelling text

WDateField may have accessible text applied as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.

// with WDateField field
field.setAccessibleText("Some further context to this date.");

Access Keys

A WLabel for a WDateField may be given an access key to provide rapid keyboard access.

Default focus

A WDateField in an enabled, interactive state may be set as the default focus point for a page. If this is specified it must comply with accessibility principles regarding focus and not put users into a position where they may skip content required for full understanding of the current view. See Setting focus for more information.

Appearance

The images in this document show how WDateField is rendered in Google Chrome on OS X unless specified otherwise.

Native control

• Editable with no content:

  

• Editable with content:

  

• Read only with content:

  

• Editable, no content, focussed:

  

• Editable, no content, calendar date picker open:

  

Custom control

The screen captures in this section are from Firefox 52 on OS X.

• Editable with no content:

  

• Editable with content:

  

• Editable, no content, calendar date picker open:

  

• Editable with input suggestions:

  

Setting input size

The width of the input element of a WDateField is determined for the most part by the user agent. If the user agent supports native HTML date inputs then the whole component size is determined by the user agent. For user agents which do not support HTML date inputs the width may be modified using WField setInputWidth(int) and in most browsers a WDateField will be no wider than its containing element. Note, however, that unlike text inputs (such as WTextField) there is no supported size or columns attribute on a WDateField. It is, of course, possible to restrain custom date input width using CSS in either a theme implementation or as custom CSS.

Customising based on HTML class

WDateField may have one or more values to be added to the component's wrapper element. This can be used for fine-grain styling of specific components but should be used with care. For more information see WComponents HTML class property.

HTML output

If the user agent supports HTML inputs of type date then the native date control will be used but it will have a HTML div element wrapper.

Otherwise a WDateField will output a HTML div element which includes a HTML input element in the text state and a button element. If the calendar based picker is opened it will also contain a HTML div element and several other form controls. Under some use scenarios it may contain transient list artefact comprising a HTML span element with one or more child span elements. If the UI may be used with browsers which do not support native date inputs then WDateField must not be placed in any container WComponent which may only contain phrasing content.

In a read-only state the output will be a HTML time element containing the text value of the component.

Supported date formats

If the user agent supports input elements in the date state then the date format is determined by the user agent and is normally locale aware.

If the user agent does not support the date state then the formats for date entry and display are dependent on the language being used and dates are displayed in the unambiguous format dd MON yyyy. In English entry formats for full dates are:

• d M yy,
• M d yy,
• d M yyyy,
• M d yyyy,
• d MON yy,
• d MON yyyy,
• dd MON yy,
• dd MON yyyy,
• dMyy,
• ddMMyyyy,
• ddMMyy,
• ddMMyyyy,
• dMONyy,
• dMONyyyy,
• yyyy-MM-dd,
• yyyyMMdd,
• d/M/yy,
• d/M/yyyy,
• M/d/yy,
• M/d/yyyy,
• MMddyy,
• MMddyyyy,
• Mdyy,
• Mdyyyy

The input field provides suggestions on user input. These suggestions are made using all of the supported date formats which apply to the entered content. Upon leaving the input field the user entered date is converted to an unambiguous format if it matches a date using any of those supported formats.

Read-only

When in a read-only state the output rendering of the WDateField changes so that it appears as text output of the value of the control (converted to a predetermined human readable, preferably unambiguous date format). The control is not able to be interacted with by the user and does not return any value back to the application.

A WDateField in a rad-only state may be the target of a WSubordinateControl or WAjaxControl. If it is the target of a WAjaxControl its state may be changed to an interactive state.

Change action

A WDateField may be used to trigger an Action which runs if the field's value changes. This will trigger any time the value changes and the server application is informed, not only if the WDateField triggers the call back to the server by being a trigger for a WAjaxControl.

// with WDateField `field`
field.setActionOnChange(new Action() {
  @Override
  public void execute(final ActionEvent event) {
    // do something
  }
});

Disabling

A WDateField may be disabled on page load. When disabled the WDateField will not respond to user input or interaction. This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call. This property does not apply if in a read-only state.

// to disable WDateField `field`
field.setDisabled(true);

Hiding

A WDateField may be hidden on page load. When hidden the WDateField is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WDateField is hidden a WLabel associated with it is also hidden.

Default submit button

A WDateField may be associated with a WButton in a way that if the user hits the ENTER key whilst the WDateField has focus then the nominated WButton will be deemed to be the control which submits the form to the server. This is discussed in more detail in Implicit form submission.

This property does not apply if the WDateField is in a read-only state or is a trigger for a WAjaxControl.

Related components

• WPartialDateField
• WComponent form controls

Further information

• JavaDoc;
• HTML Specification;
• List of WComponents.