Date range

Notes for developers

The inputs must be of type text ensuring a consistent experience for all users. The pattern attribute must be set on both text inputs eg. for DD/MM/YYYY the attibute should have a value of \d{2}\/\d{2}\/\d{4}.

The m-date-range component must have the attributes data-min and data-max, in the format YYYY-MM-DD, set to limit the date pickers to a date range. These values should always be set server side, if they are not present the min date will default to 1901-01-01 and the max date will default to today's date.

When disabling form elements, do not solely rely on the is-disabled class, but ensure that the disabled attribute is also set on the relevant form element or input. If an entire set of form elements is to be disabled, the is-disabled class and disabled attribute should be added directly to the fieldset instead, and not to each individual element within it. However if only one element from the set is disabled, then the class and attribute should be applied to that element only.

Any validation (including server-side) on the input fields must validate against the entry format that has been specified eg. DD/MM/YYYY. If the native form validation needs to be disabled set the novalidate attribute on the form.

To enable the total number of days selected, simply include the class m-date-range--total on the date range component.

Aria usage for errors and help text

To aid screen reader users in completing forms without error and also with understanding and fixing any errors that have occured, some additional aria attributes are now recommended to be applied across all form fields/rows.

All form row help, explanatory text, form row instructions and form row errors must have a unique id assigned to them and be appropriately linked to either the individual form input or the form row using aria-describedby. This ensures that the help text is read out immediately on focus of the form input/fieldset. When there is more that one item that requires referencing within the aria-describedby attribute the id values must be supplied in the form of a space separated list. For example if there is an error with id of 'err1' and help text with id of 'help1' the value for the aria-describedby attribute would be 'err1 help1'.

All inline form error messages should start with the hidden text 'Error: ' so that when read by out by a screen reader it is immediately clear that the text being read is an error message.

All erroring form fields (or fieldset if a group or radios/checkboxes) must have aria-invalid="true" set on them, ensuring that when a user focus' on an errored form field, the field will be announced as invalid, so the user is then aware that there in an issue that requires fixing.

When linking help or errors, or even adding aria-invalid to the markup careful consideration must be taken as to where it is most appropriate to apply the value. The following rules should be used to decide where the attribute(s) should be applied.

• Single form field - All attributes should be applied directly to that form field
• Group of form fields but only one in error or help text applies to only one - Apply the attribute(s) to the only field in error or where the help text applies
• Group of form field where all in error or the help text applies to all - Apply the attribute(s) to the groups surrounding fieldset (form row)

There may situations where more than one of these rules applies to the overall form row for example a date range where the instruction text applies to both fields so should be linked to the fieldset for the date range but one of the two fields is in error so the error should be linked to just that field not to the fieldset.

Important messages

To help those using assistive technologies, make sure that success/error messages which need to be announced to users have their aria attributes updated to role="alert" and/or aria-live="assertive".

Configuration

When using the date range component, additional settings can be set/updated programatically after the initial load. To do this, the function setSettings should be called from the m-date-range element with a JavaScript object containing settings in the same format as below being passed into the function:

'autosetEndDate': true,
'autosetEndDateValue': [ 'day', 10 ]

'autosetEndDate': true,
'autosetMaxDateValue': [ 'day', 10 ]

For example:

document.addEventListener( 'frameworkready', function () {
	FRAMEWORK.require([ 'blocks/m-date-range' ], function ( mDateRangeModule ) {
		var dateRangeEl = document.querySelector( '#dateInput' ),
			dateRangeInstance = mDateRangeModule.initInstance( dateRangeEl );		dateRangeInstance.setSettings({
			autosetEndDate: true,
			autosetEndDateValue: [ 'month', 3 ],
			sameDay: false,
		});
	});
});

See Interacting with Framework components example for further details on how to safely interact with framework components.

Changing locale settings

The date format and labels within the datepicker can be updated for a particular locale.

en: {
	aDate : {
		locale : 'en-gb',
		format : 'DD/MM/YYYY',
		previousMonth : 'Previous month',
		nextMonth : 'Next month',
		months : [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December' ],
		weekdays : [ 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday' ],
		weekdaysShort : [ 'S', 'M', 'T', 'W', 'T', 'F', 'S' ],
		interactionInstruction : 'Use the arrow keys to pick a date',
		triggerLabelSingle : 'Select date',
		confirmLabelSingle : 'Confirm date',
		triggerLabelRange : 'Select dates',
		confirmLabelRange : 'Confirm dates',
		clearLabel : 'Clear',
		totalSelectedSingular : 'Total days selected: <strong>{days} day</strong>',
		totalSelectedPlural : 'Total days selected: <strong>{days} days</strong>',
		yearLabel : 'Year',
		monthLabel : 'Month',
		startDateTitle : 'Set start date',
		endDateTitle : 'Set end date',
	},
},

For more information on this, see our page on how to change locale settings within JavaScript.

Extension component

This component forms part of the 'forms-extended-a' extension and so requires an additional stylesheet to be loaded in order to be used; include the following code in the header of your page to attach the relevant additional stylesheet:

<link media="all" href="./assets/[ theme type ]/[ release version ]/[ organisation ]/[ theme name ]/css/forms-extended-a.css" rel="stylesheet" />

---

Notes for testers

• In IE11 the date icon will look fuzzy; this is a rendering issue with the browser when a background is on an element that has rounded corners.
• The form must have validation in place to catch any errors with the dates entered and present an error message back to the user. This message does not have to be shown real-time, but can appear once the user has attempted to submit the form.
• Ensure that the field has a correctly associated label; this not only provides context to the field for assistive technology users, but also a larger clickable area to select the field. Clicking / pressing on the label should cause the date field to gain focus.
• Users should be able to copy and paste if necessary.
• Highlight today's date and the selected date with clear variation between them
• Users should be able to easily identify and distinguish between selectable and non-selectable dates, today's date, the selected date and weekends.
• The calendar should have a clear hover state to help users identify the correct date.
• For some applications, past dates may need to be disabled.
• Clickable / tappable area of each day should be an appropriate size.

---

Classes overview

The following table gives you a quick overview of the CSS classes that can be applied.

---

Keyboard operations

TAB

Tabbing to an input field should make the input clearly visually different so that the focus point on the page is obvious to the user.