Currently, examples are provided in Drupal by including them in the
#description text of a form element. Those descriptions currently range in construction from "Example: so and so", to "e.g., so and so", to "so and so". I think it would be a significant usability enhancement to provide an additional FAPI property (similar to
#description) named something like
- All current "examples" that are now part of
#descriptionwill be broken off into new values for
#example. New text for core text fields without explicit examples can be added.
#exampletext, the way I am thinking of it, would be styled differently from
#descriptiontext. The styling for
#example, which would be consistent across core, then becomes the visual cue of the presence of an example. Having an easily recognizable and consistent visual cue allows us to eliminate the need to point out that we're talking about an example, which we currently do when they're part of a description (by adding something like "Example:" to the front of the text).
- In line with the webchick's permission description issue, and a similar one that I have for hiding help text, as we think of new uses for system_admin_compact_mode, perhaps "Hide descriptions" could also hide form field descriptions, but leave examples visible. While implementing this would be feature creep for this issue, I mention it here to point out that by making
#description, we can choose to display one while hiding the other.
- Text in
#examplekeys could be displayed in text fields (in gray), and then disappear when one begins typing. People have pointed out to me several current web-based UI's that do this, including the Yahoo signin screenshot I have attached. (In the attached screenshot, "First Name", "Last Name", "Day", "Year", while not examples proper, illustrate the style of theming we could perhaps use if these values were automatically displayed in text fields. The gray values disappear as your cursor enters the field.)
I can redo the existing descriptions and provide
#example text where it does not exist. I'm not yet sure of the best way to tackle the implementation of the
#example property itself. I've queried several folks in #drupal, though, and suggested methods for tackling this range from adding
#example to form.inc, to using theme_form_element. Suggestions -- and patches -- are very welcome, because I may well be in over my head on portions of this.
Also note that while I have used
#example here for ease of description, suggestions for other more appropriate names are also appreciated.