DATE accessibility

Getting Drupal to emit screen-reader friendly dates is a pain in the butt. It can, however, be done. Here's a detailed account of my efforts on that score, complete with tests in two screen readers (including MP3s for your listening pleasure), some analysis, and a detailed walk through of customizing the code for a DATE element.

Let's look at an example. Here's the PHP for a fairly standard date input in Drupal's Forms API, from a project I've been working on:

Drupal 6.9 renders that with the following HTML (reformatted and abbreviated for legibility):

I've put together a bare bones test case. Here are some samples of how it's read by two screen readers:

• FireVox
• NVDA

As the demographics of screen reader use make clear, the most common screen reader out there is JAWS from Freedom Scientific. However, I do not have a purchased copy handy at this time, and the evaluation version of JAWS does not permit its use in testing code. Therefore I will not be testing with it.

There are some differences in how FireVox and NVDA read the sample. You'll note that FireVox silently omits the "Needed by" label. The reason for that is in the code:

  <label for="edit-rush-date">Needed by: </label>

The FOR attribute of this label associates it with the input in the document which has the ID "edit-rush-date". Unfortunately, there is no such input in the document. I asked Charles Chen, the developer of FireVox, about this a while back. In essence, he explained that he'd decided a LABEL element with no associated form element shouldn't be read at all, because it would erroneously lead the listener to believe that the form has more inputs than it actually does.

NVDA treats it differently -- it goes ahead and reads the orphaned label. Both NVDA and FireVox are affected by the other problem, which is that the three individual inputs comprising the date picker lack labels. In the FireVox sample, you'll hear that it reads the actual date pickers as:

Select box: One
Select box: Jan
Select box: Nineteen hundred

And NVDA reads it as:

Needed By
Combo box, collapsed submenu: One
Combo box, collapsed submenu: Jan
Combo box, collapsed submenu: Nineteen hundred

In both cases it's not clear from the audible description what the select boxes are actually for. FireVox's omission of the label makes it even less clear in that screen reader than in NVDA, but neither one is very obvious. It would help somewhat to have a more recent year as the default value, of course, which didn't occur to me till after I'd begun testing.

But even then, the screen reader user is left to infer the purpose of the form controls based on the types of information stored in them -- a one or two-digit integer for the day, an abbreviated month name for the month, and a four digit integer for the year. The order of the fields may get in the way of its understandability as well, depending on your cultural background. An American screen reader user would probably expect dates inputs to be ordered Month-Day-Year, while a British screen reader user would expect Day-Month-Year. In the absence of explicit labels for all three parts of the date, blind visitors are left to guess, and the cultural difference in date order just make it harder.

The root of the problem is one of hierarchy. A date picker like this one is supposed to yield just one form value -- the date -- but consists of three discrete form inputs for the day, month, and year. The discrete form inputs each require a label. That part is easy, like this:

The labels can be hidden easily enough with CSS -- .container-inline label { position: absolute; left: -999em; } would do it, though it would be preferable to add a more specific class to the HTML like class="form-item-date" to avoid applying the rule to other contexts. Adding explicit labels this way makes it a lot easier to interpret the purpose of the form controls, as you can hear:

• FireVox
• NVDA

But in order to be fully intelligible, the group as a whole needs a label too, and that label needs to be associated with all three form elements. It is possible to write code containing multiple labels for a single form input:

And, in fact, this is fully conformant with the HTML 4.01 standard, which says that "More than one LABEL may be associated with the same control by creating multiple references via the for attribute."[ref] The XHTML standard does not alter that.

However, screen reader support for multiple labels is variable. Given the above code, FireVox will speak both labels, but NVDA will only speak the first one.

Even if screen readers all supported multiple labels perfectly, though using multiple labels wouldn't solve the problem. The HTML specification requires that each label be associated with exactly one form control. The FOR attribute takes an ID, not a class. So in order to label each of the three select boxes, we would need three copies of the "Needed By" label, one for each of the three form elements:

That's obviously a bad solution, partly because it bloats the code, but also because it requires us to hide two of those duplicate labels from sighted visitors, which bloats the code even further. Great.

The natural HTML elements to use in this situation are FIELDSET and LEGEND elements. They were explicitly designed to group related sets of form controls together and to provide a label for the whole group in a screen-reader friendly way. Something like this works nicely:

This is fully intelligible in both screen readers:

• FireVox
• NVDA

The next thing to take care of is its appearance. The default styling for a FIELDSET/LEGEND combo is much too visually complex for just a date picker. Fortunately, it's not terribly difficult to make it look just like most other Drupal form items -- a bold label one line above the input. You can see a test case, using this CSS:

That renders acceptably in all four major browsers (screenshots). All that's left is to make Drupal emit the correct HTML and CSS to achieve this effect. Now, from here on in I'm going to assume that you're developing a module, because that's what I'm doing. Some of this can be replicated on the theme layer; other bits of it can't as far as I know. I'll indicate which is which.

First up, let's get some labels in place for the individual elements in the date. The Drupal function responsible for that is expand_date(), which takes the array of values provided in the #default_value index of the form array that defines the structure of the form. All it really does is automatically create SELECT elements in Drupal's Forms API notation. To make it spit out an appropriately formatted label, we'll need to override that function.

The first step is to make a copy of the stock expand_date() function into your module and rename it. My module is named ds_ticket, so the function will be ds_ticket_expand_date(). It actually only needs a single line added to make it produce the labels -- I've marked that with a comment below. Thus:

Once that's in place, we'll modify the original definition of the form field to call our version of expand_date() instead of the stock one. Here's that form field definition again:

Save the .module file, upload, and voila -- labels on all the individual dates. I don't know if you could accomplish the same thing from a theme's template.php; I've never tried. If it's possible, it would probably require using hook_form_alter().

Next up, we need to re-write the theming to make it generate the fieldset and legend code. The stock theming is handled by theme_date(). We'll need to override that with a custom function. The first step is to register a custom theming function using hook_theme(). Like this:

In this case, it's just a function, not a template file, and we don't need to pass any unusual arguments to the new function. The new function itself must have the same name as the index in hook_theme (here that's 'ds_ticket_date'), only with 'theme_' on the front, so the full name of the function is 'theme_ds_ticket_date'. If you're working from a template rather than a module, you can override the stock theme_date() simply by creating a function in your template.php file named either 'phptemplate_theme_date()' or 'YourThemeNameHere_theme_date()'. You may need to clear the Drupal cache in order to make it recognize your new function, which can be done by going to Administer --> Site Configuration --> Performance and clicking the "Clear Cached Data" button. If you're going to be doing that a lot, though, you'll probably want to install the Devel module, which adds a new block to your site with a very handy "Empty Cache" link.

In my module, I created the new function by copying and pasting the stock function in and changing the function name, like this:

As you can see, it's a really basic function. And, as yet, it's not actually doing anything. We've created the new theme function, and registered its existence with Drupal, but we haven't specified that the form element should use it yet. That's done by adding a #theme index, thus:

Now it should finally use our theme function. Let's make it produce a fieldset instead of the usual code.

This seems pretty straightforward, but it took a while to work out. In the stock theme_date() function, it just threw the element at theme() and passed it a value of $element['#children'] -- but when I examined that in my own version, it didn't exist. I believe theme_date() actually gets called twice (or more) in the process of building a date, but I'm not certain. Because Drupal relies so heavily on calling functions through call_user_func(), the execution flow can be rather opaque.

Anyway, I studied drupal_render() a bit. Since $element['#children'] didn't exist, I built it myself using element_children() to retrieve the children, and drupal_render() to render them as normal.

Another problem I ran into was that Drupal invariably wrapped the whole fieldset in another DIV containing a malformed LABEL. It was apparently calling theme_date() again after my own theme function ran, and adding an extraneous wrapped. I still don't know why it was doing this, or the proper way of making it stop. What eventually fixed it for me was manually marking the form element as "printed" in the initial form definition, thus:

And as you probably noticed, I also added a default value (today). With that whipped into shape, there's nothing left to do but add the CSS. I had to explicitly add some space at the bottom of the form element immediately above the date, because the LEGEND element in the date was too close to its predecessor for easy legibility, and adding margins or padding to the top of the fieldset did not help. (LEGEND element are notoriously difficult to style -- they just don't cooperate with a lot of ordinary style rules).

And all of this fuss because the W3C didn't see fit to give us a standard <input type="date" /> or <input type="time" /> back when they were last working on HTML, which would have been a better way to do it. That way the browser vendors could have worried about it once, and then we poor long-suffering web developers wouldn't have to. I wonder how many hours of time have been spent worrying about date/time inputs in forms? Probably a lot. And now we're getting fancy JavaScript datepicker widgets which are even more difficult to do in an accessible fashion.

I hope this helps someone, as I've just spent nearly 8 hours working out the code and documenting everything.