Usability: Enhance form elements by providing examples

Created on 19 February 2008, over 17 years ago

Updated 28 May 2025, 2 days ago

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 #example.

Ideas:

All current "examples" that are now part of #description will be broken off into new values for #example. New text for core text fields without explicit examples can be added.
#example text, the way I am thinking of it, would be styled differently from #description text. 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 #example different from #description, we can choose to display one while hiding the other.
Text in #example keys 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.

✨ Feature request

Status

Postponed: needs info

Version

11.0 🔥

Component

forms system

Created by

🇺🇸United States keith.smith

Live updates comments and jobs are added and updated live.

stale-issue-cleanup
To track issues in the developing policy for closing stale issues, [Policy, no patch] closing older issues

Incomplete comments

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Comment 2 days ago →
🇺🇸United States smustgrave
Thank you for sharing your idea for improving Drupal.

We are working to decide if this proposal meets the Criteria for evaluating proposed changes. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or there is no community support. Your thoughts on this will allow a decision to be made.

Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.

Thanks!

contrib.social Blog FAQ Discussions

Production build 0.71.5 2024