apex4x
Version:
The Comprehensive ARIA Development Suite
614 lines (523 loc) • 19.9 kB
HTML
<!doctype html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>ARIA Date Pickers - Apex 4X Technical Style Guide</title>
<meta name="description" content="Scalable ARIA Components" />
<meta name="Author" content="Bryan Garaventa" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link
rel="stylesheet"
type="text/css"
href="../_common/_doc_files/css/global.css"
/>
<link
rel="stylesheet"
type="text/css"
href="../_common/_doc_files/prism.css"
/>
<link
rel="stylesheet"
type="text/css"
href="../_common/_doc_files/css/components-style.css"
/>
<script src="../_common/_doc_files/prism.js"></script>
</head>
<body>
<div class="outer-wrapper">
<header class="header">
<div class="logo">
<a href="https://whatsock.com">
<img
alt="WhatSock : Changing the world one step at a time"
src="/Templates/_common/_doc_files/img/whatsock.svg"
/>
</a>
</div>
</header>
<div class="wrapper">
<main id="main" class="main">
<h1><strong>ARIA Datepickers</strong></h1>
<nav class="navigation--parent">
<p>
<a href="/Tutorials/Beginner-Introduction.htm"
>Beginner Tutorial</a
>
</p>
<h2 class="parent--page">Template Examples</h2>
<ul>
<li class="mobile--componentName">
<a href="../index.htm">Back to Components</a>
</li>
<li class="mobile--componentName">
<a href="Basic/index.htm">Basic</a>
</li>
<li class="mobile--componentName">
<a href="Basic - Straylight/index.htm">Basic - Straylight</a>
</li>
<li class="mobile--componentName">
<a href="Basic Short/index.htm">Basic Short</a>
</li>
<li class="mobile--componentName">
<a href="Basic, Auto Open/index.htm">Basic, Auto Open</a>
</li>
<li class="mobile--componentName">
<a
href="Basic, ReadOnly Auto Open plus Disabled Ranges/index.htm"
>Basic, ReadOnly Auto Open plus Disabled Ranges</a
>
</li>
<li class="mobile--componentName">
<a href="With Absolute Disabled Date Ranges/index.htm"
>With Absolute Disabled Date Ranges</a
>
</li>
<li class="mobile--componentName">
<a href="With Complex Custom Disabled Date Ranges/index.htm"
>With Complex Custom Disabled Date Ranges</a
>
</li>
<li class="mobile--componentName">
<a href="With Custom Date Formats/index.htm"
>With Custom Date Formats</a
>
</li>
<li class="mobile--componentName">
<a href="With Disabled Weekends/index.htm"
>With Disabled Weekends</a
>
</li>
<li class="mobile--componentName">
<a href="With Editable Tooltip Comments/index.htm"
>With Editable Tooltip Comments</a
>
</li>
<li class="mobile--componentName extlong">
<a
href="With Full Calendar Display, Condense Year and Natural PageUpDown/index.htm"
>With Full Calendar Display, Condense Year and Natural
PageUpDown</a
>
</li>
<li class="mobile--componentName">
<a href="With Relative Disabled Date Ranges/index.htm"
>With Relative Disabled Date Ranges</a
>
</li>
<li class="mobile--componentName">
<a href="With Tooltip Comments/index.htm"
>With Tooltip Comments</a
>
</li>
</ul>
</nav>
<section class="section--instructions">
<h2>Expected behaviors</h2>
<p>
An external triggering element should activate the datepicker for
touch support, focus should move into the datepicker when
selecting a date using the keyboard, the arrow keys should move
between calendar cells and the calendar should scroll
automatically between months, PageUp/PageDown should switch
between months, Alt+PageUp/PageDown should switch between years,
Enter should activate the selected date, and pressing Escape or
Tab should close the calendar and return focus to the triggering
element.
</p>
<p>
The 4X ARIA Datepicker module automatically configures all
required ARIA attributes and focus handling, in strict accordance
with the ARIA specification.
</p>
<p>
Note: A datepicker is a composite widget, meaning that it is
comprised of different ARIA roles and supporting attributes.
</p>
<p>
The following attributes are handled automatically by the
Datepicker module:
</p>
<ul>
<li>role=dialog</li>
<li>role=application</li>
<li>role=button</li>
<li>role=presentation</li>
<li>aria-hidden</li>
<li>aria-label</li>
<li>aria-disabled</li>
<li>aria-current</li>
<li>tabindex</li>
</ul>
<h2>HTML syntax</h2>
<div>
<pre><code class="language-markup">
<label for="dateInputId"> Departure date: </label>
<input placeholder="MM/DD/YYYY" id="dateInputId" type="text">
<button title="Datepicker" id="dateCalendarIconId"><!-- Calendar Icon Here --></button>
</code></pre>
</div>
<h2>JavaScript syntax</h2>
<div>
<pre><code class="language-javascript">var myCalendarDC = $A.setDatepicker({
// Configuration key / value map
});</code></pre>
</div>
<ul>
<li>Module file: Datepicker.js</li>
<li>Has no dependencies.</li>
<li>Recommended: Velocity.js, VelocityUI.js.</li>
</ul>
<h2>Parameters</h2>
<ol>
<li>A configuration map to customize behaviors and options</li>
</ol>
<h3 tabindex="-1" id="configure">Configuration</h3>
<div>
<pre><code class="language-javascript">{
// Unique ID for the datepicker instance
// After instantiation, can be referenced using: var DC = $A("UniqueCalendarId");
id: "UniqueCalendarId",
// Clickable icon triggering element
toggle: "#dateCalendarIconId",
// Native input element where the saved date value will be set.
input: "#dateInputId",
// Optionally specify a DOM node to return focus to after the datepicker calendar is removed.
// By default, this will set focus back to the associated input field where the date is saved, but it can be overridden if needed using the following property.
returnFocusTo: $A.get('elementId'),
// Optionally convert the static year field into a year selector dropdown.
yearSelect: true,
yearSelectMin: 1900,
yearSelectMax: new Date().getFullYear() + 5,
// Optionally convert the static month field into a month selector dropdown.
monthSelect: true,
// Force the month/year select dropdown to render instead of a button.
forceSelect: false,
// Set initial inline styling properties for the dynamically rendered calendar.
style: {
position: 'absolute',
zIndex: 1,
display: "none" // Set the initial state to hidden in prep for animation if applicable.
},
// Optionally specify a render and remove animation effect for the calendar.
// Requires the "Animate" module import to function, which is powered by Velocity.js.
// To ignore animation effects, delete the animate object declaration entirely from the setup script.
// View implementations within "Templates/Datepickers" for practical animation usage examples.
animate: {
onRender: function(dc, wrapper, next) {
// Specify the render animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for rendering.
}
});
},
onRemove: function(dc, wrapper, next) {
// Specify the removal animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for removal.
}
});
}
},
onActivate: function(event, dc) {
// Optionally override the default functionality when a date is activated.
// format selected calendar value and set into input field
dc.target.value = dc.formatDate(dc);
dc.remove();
if (!dc.triggerClicked) dc.target.focus();
else dc.trigger.focus();
dc.triggerClicked = false;
},
// If not included, all of the below values are set by default
role: 'Calendar',
// Set the initial state of the datepicker when activated.
// If true, the datepicker will not open and the associated input will be disabled.
disabled: false,
// Short help text message that is automatically announced to screen reader users when the calendar first opens.
helpTextShort: 'Press F1 for help.',
// Set help text to be displayed when F1 is pressed.
helpText: 'Press the arrow keys to navigate by day, PageUp and PageDown to navigate by month, Alt+PageUp and Alt+PageDown to navigate by year, or Escape to cancel.',
// Set description text to be announced when the datepicker is set to open onFocus().
openOnFocusHelpText: "Press Down arrow to browse the calendar, or Escape to close.",
// Set tooltip text
tooltipTxt: 'Press Escape to cancel',
disabledTxt: 'Disabled',
markedTxt: 'Selected',
commentedTxt: 'Has Comment',
prevTxt: 'Previous',
nextTxt: 'Next',
monthTxt: 'Month',
yearTxt: 'Year',
// Set month names
months: [
'January',
'February',
'March',
'April',
'May',
'June',
'July',
'August',
'September',
'October',
'November',
'December'
],
// Set short and long weekday names
days: [
{
s: 'S',
l: 'Sunday'
},
{
s: 'M',
l: 'Monday'
},
{
s: 'T',
l: 'Tuesday'
},
{
s: 'W',
l: 'Wednesday'
},
{
s: 'T',
l: 'Thursday'
},
{
s: 'F',
l: 'Friday'
},
{
s: 'S',
l: 'Saturday'
}
],
// Switch the behaviour when the PageUp or PageDown keys are pressed to a "natural" behaviour
// (PageUp goes to previous month, PageDown goes to next month)
pageUpDownNatural: true,
// Append a "dayToday" CSS class to the current day cell element - this allows styling to be targeted to this specific element
highlightToday: true,
// Fill in the day cells outside of the current month so that the calendar grid is always filled with day cells
drawFullCalendar: true,
// Run custom functions at the end of the code within the following component functions.
// Receives a single parameter "dc", which provides access to the Datepicker object.
beforeRender: function (dc) {
console.log('beforeRender');
console.log(dc);
},
afterRender: function (dc) {
console.log('afterRender');
console.log(dc);
},
afterRemove: function (dc) {
console.log('afterRemove');
console.log(dc);
},
// Override the character used on the month / year change buttons
leftButtonYearText: '<',
rightButtonYearText: '>',
leftButtonMonthText: '<',
rightButtonMonthText: '>',
// Specify if the calendar should open when the input field receives focus.
// If true, the Down arrow or Tab key must be pressed to move focus from the input field into the calendar for manual traversal, and Escape will collapse the calendar.
openOnFocus: false,
openOnFocusHelpText: 'Press Down arrow to browse the calendar, or Escape to close.',
// Specify that only the year and month selector will be rendered, and no individual dates.
// Set inputDateFormat to return the correct string value when the datepicker closes. For example:
// inputDateFormat: 'MM/YYYY',
monthOnly: false,
// Display a Close button
showEscBtn: true,
escBtnName: 'Close',
escBtnIcon: '×',
// Set specific start / end boundaries of a date range. Can be Date objects (absolute boundaries), or positive/negative integers (relative boundaries).
// If undefined, no date range will be enforced.
minDate: undefined,
maxDate: undefined,
// Using a token system, set a specific date string format to be used when setting the selected value into the calendar input box
// 'YYYY': 4 digit year, 2019
// 'YY': 2 digit year, 19
// 'MMMM': Full name of month, January, etc.
// 'dddd': Full name of weekday, Monday, etc.
// 'MM': 2 digit month, 01, etc.
// 'DD': 2 digit day, 01, etc.
// 'Do': getDateOrdinalSuffix, 1st, 2nd, 3rd.
// 'M': 1 or 2 digit month, 1 through 12
// 'D': 1 or 2 digit day, 1 through 31.
inputDateFormat: 'MM/DD/YYYY',
// Using a token system, set a specific date string format to be read out to screen reader users
// The default format covers all necessary information to ensure accessibility, so do not change unless absolutely necessary.
audibleDateFormat: 'D, dddd MMMM YYYY',
// Allow a date that isn't today to be set as the initial date. If unset, this value is initialised to today's date
initialDate: new Date(),
// Disable weekdays from selection
disableWeekdays: false,
// Disable weekends from selection
disableWeekends: false,
// Set positive or negative offset for differing column arrangements, or 0 for none
wdOffset: 0,
// Set class for the calendar wrapper
className: 'calendar',
// Choose a different insertion point in the DOM; must be a DOM node; defaults to the triggering element if not specified.
targetNode: null,
// Reset date to the current calendar date every time the datepicker opens
resetCurrent: false,
// Configure the Comments tooltip pane
comments: {
role: 'Comment',
className: 'commentTooltip'
},
// Configure the editor form pane
editor: {
// Choose to show the form, defaults to false
show: false,
// Set the section name, and the Edit button text
role: 'Edit',
className: 'commentAdd',
// Set the Save button text
action1: 'Save'
},
// Condense the year display by removing the year nav buttons.
condenseYear: false,
// Manually configure the calendar using the configure method or a customization script
configure: function(dc){
// And optionally prevent this script from running again
// dc.stopConfigure = true;
}
}</code></pre>
</div>
<h2>Programmatic control</h2>
<div>
<pre><code class="language-javascript">// Get a reference to the calendar DC instance using its id.
var dc = $A('UniqueCalendarId');
// Manually open the calendar.
dc.render();
// Or close it
dc.remove();
// There are some additional methods which allow altering the Date Picker state after invocation:
dc.setDayMarked(dc, dateObj, isMarked);
dc.clearAllMarked(dc);
dc.setDayDisabled(dc, dateObj, isDisabled);
dc.setMonthDisabled(dc, dateObj, isDisabled);
dc.setDayOfWeekDisabled(dc, dateObj, daysOfWeekArray, isDisabled);
dc.setWeekdaysDisabled(dc, dateObj, isDisabled);
dc.setWeekendsDisabled(dc, dateObj, isDisabled);
dc.clearAllDisabled(dc);
dc.setMonthMessage(dc, dateObj, message);
dc.clearAllMessage(dc);
dc.setDate(dc, dateObj);
dc.presetDate(dc, initialDateObj, minDateObj, maxDateObj);</code></pre>
</div>
<h2>Implementation notes</h2>
<p>
For more granular access to date string values that exist within
each calendar object instance, you can access the internal
variables like so:
</p>
<div>
<pre><code class="language-javascript">var weekday = dc.range.wDays[dc.range.current.wDay].lng; // = 'Friday'
var monthName = dc.range[dc.range.current.month].name; // = 'November'
var monthDay = (dc.range.current.month+1); // = numerical month string
var day = dc.range.current.mDay; // = '30'
var year = dc.range.current.year; // = '2012'</code></pre>
</div>
</section>
</main>
</div>
<footer class="footer">
<div class="flex-container-row">
<div class="flex-item">
<h2>License</h2>
<p>
Apex 4X including all template design patterns is distributed
under the terms of the Open Source Initiative OSI - MIT License,
and may be freely used for any purpose within any web technology.
</p>
</div>
<div class="flex-item">
<h2>Resources</h2>
<ul>
<li>
<a target="ext" href="https://github.com/WhatSock/apex"
>Apex 4X on GitHub</a
>
</li>
<li>
<a
target="ext"
href="https://whatsock.github.io/visual-aria/github-bookmarklet/visual-aria.htm"
>Visual ARIA Bookmarklet</a
>
</li>
<li>
<a
target="ext"
href="https://chrome.google.com/webstore/detail/visual-aria/lhbmajchkkmakajkjenkchhnhbadmhmk"
>Visual ARIA Chrome Extension</a
>
</li>
<li>
<a
target="ext"
href="https://addons.mozilla.org/en-US/firefox/addon/visual-aria/"
>Visual ARIA Firefox Extension</a
>
</li>
<li>
<a target="ext" href="https://github.com/AccDC/visual-aria"
>Visual ARIA on GitHub</a
>
</li>
<li>
<a target="ext" href="https://whatsock.com/training/matrices/"
>ARIA Role Conformance Matrices</a
>
</li>
<li>
<a target="ext" href="https://whatsock.com/training/"
>Accessibility Tree Training Guide</a
>
</li>
</ul>
</div>
<div class="flex-item">
<h2>Acknowledgements</h2>
<ul class="list--horizontal">
<li>
Author and developer:
<a target="ext" href="https://www.linkedin.com/in/bgaraventa"
>Bryan Garaventa</a
>
</li>
<li>
Website designer:
<a target="ext" href="https://gericci.me/">Angela Ricci</a>
</li>
<li>
Style and markup editor:
<a
target="ext"
href="https://www.linkedin.com/in/laurence-lewis-77520365/"
>Laurence Lewis</a
>
</li>
<li>
Code contributor:
<a target="ext" href="https://dannya.com">Danny Allen</a>
</li>
</ul>
</div>
</div>
</footer>
</div>
</body>
<script
async
src="https://api.whatsock.com/accdc-updates.js?4x=template"
></script>
</html>