This week's itch is another usability itch: adding example text to all textfields in core. There's work there in process to do stuff like emulate the Yahoo! registration form, where a faded-out example value is placed in initially, and disappears when the box gets focus:

On browsers that lack JS support, the example text will just be displayed next to the box.

How does this work?

Any text fields (and probably text areas) get a new form property: #example. This property contains an example of how to use the field. For example (heh. ;)), in the upload module settings, there's a field where you're supposed to specify height x width of the maximum resolution to allow. It would look basically like this:


$form['upload_max_resolution'] = array(
'#type' => 'textfield',
'#title' => t('Maximum resolution for uploaded images'),
'#default_value' => variable_get('upload_max_resolution', 0),
'#description' => t('The maximum allowed image size.'),
'#example' => t('640x480'),
);


Why is this important?

1. It encourages us to document how those text fields are intended to be used.
2. It standardizes on a way to display this text. Right now, examples are sometimes wedged into the #description properties, sometimes lopped into a ghetto #field_suffix property, etc.
3. It allows us to do neat things, including Dark jQuery Magick enhancement, since the #example property run through a theme function so we can change the way they look.

Big thanks to Keith Smith and Rob Loach for taking this on. I'm going to try and help w/ reviewing when I can. :)