very helpful lioness

Drupal 7.x itch of the week: examples for text fields

Tue, 02/19/2008 - 21:25 -- webchick

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:

Yahoo! registration form

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. :)


Submitted by Anonymous (not verified) on

You seem to be missing a rather important point: none of the grayed out labels in the Yahoo registration form are actually examples. They are simply a compact way of presenting labels for (sub-)fields.

Using this UI behaviour for examples seems just about the worst possible use imaginable, since there is a high risk of confusing the example with an actual filled-in value. Plus, for more complicated/confusing fields, you can't actually type out your result with the example as a reference, because it disappears as soon as you focus the field.

Submitted by Michaella (not verified) on

If you take a look at the screenshots posted along with the patches, when JS isn't there, the example is merely displayed.

I'm pretty sure you can do this without javascript with something along the lines of input { background-color: transparent; }
input:focus { background-color: white; }
and some tricky positioning/layering of the #example's html wrapping element. I'm not sure if IE6 or 7 support input:hover, or how easily the tricky positioning and layering would work scale to infinite unknown form text field sizes. But it would be great if this feature weren't JS dependent, at least for most users.

Submitted by webchick on

....of the kind of wacky stuff you can do with CSS/JS with these example descriptions. Those could just as easily be "Jane" and "Smith" and so on.

That's a good point that the examples go away when you tab into the text field, but I've found that when I've used this UI, my eye goes naturally to the example first, and then as I tab into the box I merely type in what it asked for. My memory's not /that/ bad ;) so I find this easy and self-documenting without making the form ridiculously long.

Of course for phone numbers, postal codes, and that kind of thing, the example would probably be more useful just displayed next to the field... "I can't remember; did they want (xxx) xxx-xxxx or xxxxxxxxxxx or....?" Wonder if we need to build in an option for this... hmmm...

The example does degrade, however. If you take a look at the screenshots posted along with the patches, when JS isn't there, the example is merely displayed beside the field as "Example: foo"

However, if you have usability concerns about this patch please by all means add a comment to the issue. The last thing I want to do is end up having this feature become /more/ confusing for people, rather than less. :)

Submitted by Matt J. Sorenso... (not verified) on

with js, if the user clicks into or tabs into and out of a field without typing anything... you can just check for zero-length onblur and put the sample text back in.

Submitted by davedelong (not verified) on

If you're willing to look into browser-specific implementations of this, you can add the placeholder="" attribute to the text inputs in Safari. In browsers that don't support placeholder text, it just won't appear. It's really simple to include it:

<input type="text" placeholder="My awesome placeholder">