Skip to content

WPartialDateField

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 19 revisions

WPartialDateField is a component for creating a text input which is able to accept text input which may be read as parts of a date. WPartialDateField is not a date input control. For that use WDateField.

Not a date input

NOTE WPartialDateField does not provide date input. It provides text (String) input which may, under some circumstances, be able to be parsed into a date or may be read as ambiguously representing parts of a date. If you require date input then you should use WDateField.

Why use WPartialDateField

It is very difficult to justify WPartialDateField. It produces a text input which accepts any content then uses opaque algorithms to try to parse the input into parts of an unambiguous date. For almost all purposes date input should be done using WDateField and a date range (e.g. any date in June 2016) should be done using a set of WDateField components.

When not to use

WPartialDateField must not be used where a date input is expected. For this use WDateField.

Creating a WPartialDateField

There are four constructors for WPartialDateField. The default constructor creates a field with no default date and a default padding character. Other constructors exist to allow a customised padding character, a default (partial) date or both. Note that the parts of a date are 1 based (January is month 1 not month 0)

// default WPartialDateField
WPartialDateField partField = new WPartialDateField();

// create a WPartialDateField with a default month (March) and year (2017)
partField = new WPartialDateField(null, 3, 2017);

Input constraints

Mandatory input

WPartialDateField 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.

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

Padding character

The parts of a (recognised) date which are absent from a partial date (for the purposes of WPartialDateField) are padded with a padding character. This is not the same as adding leading zeros to day and month parts to make a single digit into a two digit date/month. The default padding character is a SPACE and there is almost no reason to change this but it may be changed if desired. Changing the padding charater to a digit (0-9) may result in some VERY strange results.

Accessibility

WPartialDateField is a complex widget which contains aspects of a combo-box (to supply completion suggestions) but which also may contain an owned calendar-based date picker. Note, however, that this date picker may be dropped as it causes significant ambiguity in the use of WPartialDateField. The calendar based date picker works in the same way as the custom control version of WDateField. The combo-box nature of WPartialDateField works as per the WAI-ARIA authoring practices.

Labeling a WPartialDateField

All WPartialDateFields 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 WPartialDateField 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 WPartialDateField.

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

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

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.

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).

Setting a toolTip

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

// with WPartialDateField field
field.setToolTip("Some further context to this input.");

Additional labelling text

WPartialDateField 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 WPartialDateField field
field.setAccessibleText("Some further context to this input.");

Access Keys

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

Default focus

A WPartialDateField 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.

HTML output

A WPartialDateField will output a HTML div element which includes a HTML input element in the text state and a button element. It may contain transient list artefact comprising a HTML span element with an appropriate role and (when the calendar is launched) a HTML div element with table, select, input and button element descendants. WPartialDateField must not be placed into any component which has a content model of phrase content.

If the component is in a read-only state then the output will be a HTML span element containing the text value of the component.

Date formats

WPartialDateField accepts all date formats supported by the non-HTML5 version of WDateField. In English additional entry formats for partial dates are:

  • M y,
  • MON y,
  • M yyyy,
  • MON yyyy,
  • MONy,
  • MONyy,
  • MONyyyy,
  • MMyy,
  • MMyyyy,
  • yyyyMM,
  • yyyyM,
  • y,
  • yyyy,
  • M,
  • MM,
  • MON,
  • d M,
  • M d,
  • dM,
  • Md,
  • dMM,
  • MMd,
  • ddMM,
  • MMdd,
  • ddM,
  • Mdd,
  • d MON,
  • MON d,
  • dd MON,
  • MON dd,
  • dMON,
  • MONd,
  • ddMON,
  • MONdd,
  • d,
  • dd yyyy,
  • ddyyyy,
  • ddyy,
  • dd yy

In English all dates are displayed in the unambiguous format dd MON yyyy for full date equivalents and the equivalent for any given part of a partial date.

Suggestions

A list of suggestions is provided once enough text content is entered into the text input to generate potential dates based on the current input and supported date formats. For example:

  • 1 provides suggestions of Jan and 01;
  • 11 provides 2011 (year), Nov (month 11), 01 Jan (day 1 of January in an unknown year) and 11 (day 11);
  • 111 provides Jan 2011, 11 Jan, 01 Nov and 01 2011 (day 01 of an unknown month in year 2011);
  • 1111 provides 01 Jan 2011, Nov 2011, 1111 (year in the 12th century), 11 Nov and 11 2011;
  • 11111 provides 11 Jan 2011, 01 Nov 2011, Jan 1111 and 01 1111;
  • 111111 provides 11 Nov 2011, 01 Jan 1111, Nov 1111 and 11 1111;
  • 1111111 provides 11 Jan 1111 and 01 Nov 1111; and
  • 11111111 provides 11 Nov 1111.

Change action

A WPartialDateField 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 WPartialDateField triggers the call back to the server by being a trigger for a WAjaxControl.

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

Disabling

A WPartialDateField may be disabled on page load. When disabled the WPartialDateField 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.

Hiding

A WPartialDateField may be hidden on page load. When hidden the WPartialDateField 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 WPartialDateField is hidden a WLabel associated with it is also hidden.

Read only

The readOnly property changes the output rendering of the WPartialDateField so that it appears as text output of the value of the control (converted to a predetermined human readable format). The control is not able to be interacted with by the user and does not return any value back to the application.

// With WPartialDateField `roInput`
// to set read-only
roInput.setReadOnly(true);

A WPartialDateField in a read-only state may be the target of a WSubordinateControl or WAjaxControl If it is the target of an AJAX action its state may be changed to remove the read-only setting.

Default submit button

This property is used to create a relationship between the WPartialDateField and a WButton for controlling form submission when the user presses the ENTER key. This is discussed in more detail in Implicit form submission.

This setting is not used if the WPartialDateField is in a read-only state or is a trigger for a WAjaxControl.

Related components

  • WTextField is the component most akin to WPartialDateField. NOTE: WDateField is for dates, WPartialDateField is for text which may or may not represent some part of what a human may consider to be a date.
  • WComponent form controls

Further information

Some start pages

Clone this wiki locally