Better handling for the date format descriptions

I've been thinking about other alternatives for these descriptions. I think we should put the description into a theme so it can be overridden. That would make it possible to hide it or show it site-wide and to alter the exact text used. I also was looking at the Hint module, so offering an option to show the description as a hint would be a nice option (in that case it would just display a formatted date inside the date box that disappears if you click on it rather than displaying the description below the date). If we pass enough information to the theme someone could decide to hide the description in some places and show it in others (when it is in a Views exposed filter vs when it is on a node form, for instance). We could also make these kinds of options available as settings.

As you say, we also have to think about accessibility. The calendar widget is the jQuery UI default calendar picker so I'm a bit surprised it is a problem. I wonder if there are settings we can add to the popup that would make it work better when using a keyboard?

From the datepicker demo page:

You can use keyboard shortcuts to drive the datepicker:

    page up/down - previous/next month
    ctrl+page up/down - previous/next year
    ctrl+home - current month or open when closed
    ctrl+left/right - previous/next day
    ctrl+up/down - previous/next week
    enter - accept the selected date
    ctrl+end - close and erase the date
    escape - close the datepicker without selection

It works once you know what it is using. It would be nice to have a way to show how that works. I wonder about changing the description to a 'help' link just to the right of the textfield that pops up a window that shows the expected format for the date and also describes the keyboard shortcuts?

The more I think about it the more I like the idea of a help link (it could be a help icon) just to the right of any textfields -- the date and time fields used by date_popup and the textfield used by date_text. It takes up less screen real estate (which is part of the problem with the current descriptions), but allows us to provide as much information as necessary to use the element. So the date popup would describe the expected format and show the keyboard shortcuts, the time textfield could do the same (adjusting the explanation based on which timepicker option is being used), and the plain text field would pop up just the expected format (since there are no keyboard shortcuts). I assume a description popup is still accessible and could be made to work either with or without javascript.

What do you think about that idea? Would you be willing to implement it?

A better title.

Marking #1065438: More control over format examples in description as a duplicate. It has some other ideas and points out another reason to fix this -- we are man-handling the description field and making it hard for anyone to override it. Switching to a help icon would allow us to leave #description alone.

I am happy to take a look at a demo using a few different screen-reader / browser combinations if you provide me a demo URL and a task to complete.

As a general rule date pickers are poorly accessible, particularly to screen-reader users. I am not surprised that jQuery date picker is hard to use from the keyboard, it is a complex UI component with complicated (too complicated) keyboard interaction.

If we don't do the help icon we still have the problem that we've made the description un-alterable. Putting it into a theme would at least make it possible to change the text (or remove it).

Yes, if you click on the datepicker it pops up the calendar and you 'know what to do' if you use a mouse. If you need a keyboard you are clueless about how to make it work. Although I suppose you can still type directly into the textfield in that case.

[Edit] I tried to see what exactly happens if you try to manipulate it entirely with a keyboard, no mouse. In that case when you get to the date you can type it into the box and no calendar pops up (so you don't need instructions on how it works). The same for the timepicker, you type directly into the box and nothing pops up that needs to be explained. It will be nice to confirm what happens with a screen reader, but it does look like it's accessible with a keyboard. If it's also OK in a screen reader, then maybe the only change we need to make is to theme the description so it can be overridden.

David, I'll take a look tomorrow. Thanks.

I took a quick look at the widget using JAWS 12 / FF 5. When I tab into the date field nothing happens. This means that the date picker isn't accessible to me, but it also means that it doesn't appear to interfere w/ me entering a date.

In order to find the format of the date I needed to pass the field and read the description. Which, IMO, makes the description pretty important. Unfortunately, at this time, the description of a form field is not programmatically associated with the field, so there is no way for this information to be automatically voiced by a screen-reader. This is important as some screen-reader users tab through a form (from one field to the next), while others navigate the form / page line by line. Those navigating line by line will find the description, those tabbing through the form fields will not.

See related: #405360: Use aria-describedby to link form elements with form element descriptions

There's an even larger usability issue here. The date "Format" description underneath the date widget actually show the 'converted' date not the actual format. i.e if my date format is d/m/y it actually says "Format: 04/02/2012" which is practically useless depending on the day... since it does not allow me to determine if the day or month comes first.

See attached image for clarity.

The date Format description should show the unconverted format. i.e dd/mm/yyyy etc.

Chiming in here to see if there's been any progress on this issue.

@Tsubo makes a good point that showing the converted date can be pretty unclear depending on the format. I would make much more sense to show the unconverted format.

It's easy to say things like 'show the unconverted format', but I don't know how we can do that. We have format strings that look like 'm/d/Y g:i a'. You want to create a way to convert that into something like 'MM/DD/YYYY HH:MM AM' for every possible format string? Keep in mind that the format strings have lots of options and also can have lots of escaped non-date content in them, like punctuation and other text prepending or postpending some of the elements. I don't think this is reasonably possible to do. The best we can do is display a known date using the format string. And that comes down to figuring out what known date will work best.

Any hard coded date where the day is greater than the 12th so it can't possibly confused with the month will do.

27/01/2012

or

01/27/2012

etc

Any movement on this? Some good ideas from KarenS..... but looks as if I'll have to go with David's patch and then specify the correct format in the help text instead, unless a suitable solution is agreed.

I ran into this issue - the description does indeed look odd and there's not a nice way to remove it since it's added in process.

Attaching a patch that adds the example date as a placeholder attribute instead.

#19 is an elegant solution, but the time element description is not changed.
patch updated.

here is a new patch that add a display settings both for date instance fields or views date filters for date popup type.

fixed small typo

re-roll...

I applied patch manually and it works as expected. Thanks!

Re-roll

I wanted a custom description for my date field, so I've updated the most recent patch to include a check for an already set #description field. This prevents duplicate help text when custom help text has been set. Merge Request coming.

Re-roll of the #27 as merge request !7 has only fraction of the changes from the #27.