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.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

webchick’s picture

I support this change. It'll lend a great deal of consistency to what is currently sort of hap-hazard documentation regarding examples and make them easier to spot, it'll encourage people to document what values form fields are supposed to take, and it provides a lot of interesting theming possibilities for what to do with this information.

@keith.smith: Basically, your patch is going to need to do two things:

#1: Add an #example property to any '#type' => 'textfield's or '#type' => 'textarea's where it makes sense. Probably a good place to start is by looking at all of the existing "Example:" "e.g." information.

#2: Modify theme_form_element to print out an element's #example property, if it exists. I'm thinking in a span with a class "example" inside of the description div.

Let me know (either here or in #drupal) if you need further pointers.

keith.smith’s picture

Status: Active » Needs work
FileSize
7.77 KB
2.55 KB

Hmm. This was not as difficult as I thought it might be. And, when I said in my initial post that it had been suggested I look at theme_form_element, what I probably didn't understand at the time was that the suggestion was to patch theme_form_element to include the #example span.

I tried that, and it works great. The only question with doing this through #theme_form_element is exactly how the example should be presented, if it is to appear either at the beginning of or end of the #description. I tried it several ways, and it was always a bit confusing. It you append the #example to the end of the #description text, and bold it for instance, I still felt I needed an "Example:" at the front of the text to make it clear. It almost looked better at the front of the #description text, but then it needs a period at the end to distinguish between #example and #description content.

Now, just by random chance, my example case was a field provided by upload module. In this particular case, #field_suffix had previously been used to append a "WIDTHXHEIGHT" after the input box. What if, borrowing a trick from that playbook, we similarly add the #example at the end of the text field? The attached screenshot shows a very rudimentary example of this approach.

The attached patch is what I used to implement the screenshot, and I'm posting it for feedback (so I'm leaving at CNW). Unlike doing something in theme_form_element, I guess my current implementation will only work for textfields. I'm not certain how valuable example text will be for other types of input controls, though.

Please comment.

RobLoach’s picture

Subscribing, as this would be very, very, cool. There are many implementations of the example text field if no value is given.

webchick’s picture

So if we're only adding #example to textfields, then let's only override theme_textfield() rather than theme_form_element(), which applies to /all/ form elements. This plays in well to you adding it alongside #fieldsuffix, which I think is a good idea.

The screenshot I think is missing an "Example: " before it. The "640x480" is out of context for me.

So we'll probably want to add a new theme function to form.inc called theme_field_example() (or something) so people can change how this look in their site. You'll need to modify drupal_common_theme() to add this function in it, then clear your cache before it'll show up.

RobLoach’s picture

This is exactly what you're looking for: jQuery Example Plugin.

keith.smith’s picture

@Rob Loach: That plugin is extra-super-duper cool. And, you're right -- it is exactly what I was thinking of. It would be nice if we had example text that appeared to the right of the field with non-js-enabled browsers, but that was hidden (with the example text appearing in the field as in the plugin examples) on js-enabled browsers.

Rob, you should totally adapt a version of that code to Drupal.

@webchick: Thanks. It does probably need "Example:" in there, I guess. I say "I guess" because looking around at most other interfaces, they don't have "Example" in there and it remains clear. I've obviously not hit the right styling yet to make this apparent. On the theme overrides and stuff, I'll go do a bit of research into the theme registry and see what I can come up with.

RobLoach’s picture

Once you apply this patch, you can visit admin/settings/site-information and see the Slogan field with an example. When JavaScript is not enabled, the example is concatenated onto the end of the description. When JavaScript is enabled, it appears to be greyed out on the textfield itself, and disappears when the focus is set.

Problems:

  1. Uses jQuery Example Plugin, which is currently under the BSD license. We'd have to dual license it, or roll our own if we were going to stick this into Drupal core.
  2. Currently, when JavaScript is disabled and it puts the example onto the end of the description, it uses.... This is the description. Example: This is my example.... We could probably get a better system going for that.
  3. We'd should provide #example for textarea as well as the textfield
  4. We should provide an example for every possible textfield in Drupal core
RobLoach’s picture

For those visual learners, here's a couple of screenshots with JavaScript being enabled and disabled with the patch.

keith.smith’s picture

Thanks Rob!

The patch in #7 is very cool. It does pretty much exactly what I was envisioning, and is very similar to what I have seen in other web UIs, like the Yahoo signin screenshot posted above.

I've attached a new version of the patch which adds some additional #example properties.

Some thoughts:

  • This works well both with and without js.
  • I've tried a lot of different colors, as gray only goes so far. After experimenting though, the gray is still the best cross-theme color I've found.
  • This works well to provide additional visual cues to content. In the attached patch, for example, I added the permitted upload extensions as an #example to a textfield. If you erase the value of that field with the patch applied, you get a guide as to what you might want to put back. Previously, the field's default value was your guide and if you erased or significantly modified it, you were at the mercy of figuring out the instructions in the field description (which are easy in this case, but might not always be).
  • My previous example of 640x480 is somewhat problematic with this patch. That text field has two possible entry styles, a widthXheight, or a 0, and has a default value of 0. With the default value, and after removing the "e.g. 640x480" from the description, you only see the 640x480 if you delete the 0 and then move the focus off the field. In some cases, this field now gives you less information than we had before.
  • To be complete, we do need support for text areas, though I'm not sure how the jQuery magic here will work if someone is using a wysiwg.
  • Do we t items in #examples? I did in most of the examples in the attached patch. But, after thinking about it further, why would we? Taking the value of those file extensions as an example, we really wouldn't want someone to translate that. On things like slogans, it probably makes sense though.
  • We'll have to put some thought into the appropriate examples to use. What is a good example for "site name", for instance. In the attached patch, I used drupal.org, though using that is not without its own set of problems.

Obviously, as noted in #7, we'd have to get the plugin author's input on dual licensing and/or develop an equivalent piece of code.

webchick’s picture

I would err on the side of t()ing. Then I can make a translation with my own examples that are specific to my site with String Overrides module or what have you.

keith.smith’s picture

FileSize
29.6 KB
5.55 KB

(And in case we wind up going in a different direction (and so I won't lose it), the attached patch is where I had gotten to in response to webchick's comment #4, along with a screenshot of its current butt-ugly output.)

webchick’s picture

I would err on the side of t()ing. If example strings are t()ed I can change the default example to match the content for my own site.

I'm trying not to be nit-picky about this, but in that particular screenshot (http://drupal.org/files/issues/uploadexample2.PNG), I would suggest:

- Remove WIDTHxHEIGHT. That's ugly. And "Example: 640x800" does a /much/ better job of conveying what that field is asking for.
- "Default X size per X" should be changed to "Default X size per X (in MB)" and "MB" removed from beside the box.
- If that's the only places where that ugly #afterfield property is used (or whatever it's called), then let's get rid of it altogether.
- Hm. The "Default permitted file extensions" looks very bizarre, as does the "1". Maybe we should only show the example if there's not already text in the box? hmmm.
- Pink? :) Seriously? ;)

Other than that, I think this looks *great*!

RobLoach’s picture

I have sent a note to mudge (Paul Mucur), via the contact form, about getting a dual license going with the jQuery Example Plugin. I've also posted an issue about it. Hopefully we hear from him soon.

Expanding on webchick's thoughts on #12? I have to agree, with everything...

kourge’s picture

If we don't get through the licensing issue I can totally roll this JS.

mudgemeister’s picture

I am the author of the jQuery Form Input Example plugin and I am more than happy to dual-license it for use within Drupal.

I have amended the license as of version 1.2: http://plugins.jquery.com/node/1645 (you can read the new license at http://mucur.name/system/jquery_example/LICENSE.txt)

If I can be of further assistance, please do not hesitate to contact me.

Thanks,

-- Paul

RobLoach’s picture

Thanks for the help, Paul.

The attached patch includes the new Form Input Example Plugin 1.2 (licensed under the dual license), and shows the example only if there isn't any text in the textfield to begin with. You can see it in action in the Slogan textfield of the administer site information section when the textfield is empty. Thoughts?

The attached screenshot is what shows up when Javascript is disabled (removed the pink and fiddled with the font style from Keith's example).

catch’s picture

subscribing. This looks very lovely.

mfer’s picture

subscribing

webchick’s picture

Just a general note to keep an eye on http://webchick.net/node/23, where I've drawn attention to this patch. A few people have voiced usability concerns over the JS. I've encouraged them to post over here instead/as well, but just in case they don't end up doing that..

jbrauer’s picture

subscribe. This seems like a great improvement.

keith.smith’s picture

From the anonymous (?) comment on webchick's blog:

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.

This is very true. In our Yahoo example, "First Name" isn't really an example but a short description, as we'd discussed in #drupal previously. And, yes, as pointed out in the issue, typing something like the default value of the allowable upload extensions would be tough if they kept disappearing every time you focused on the field.

I think webchick was using it as an example of something that could be done, more than anything. No matter how we use them, we need consistency in specifying examples.

The most recent patch doesn't apply an #example if the form element has a specified #default_value. I'm not sure about that behavior yet -- I'm trying to think of a use case where a default value would be different from an example.

Just brainstorming here, but if there is no difference, why have #examples? We should just put a #default_value on everything, and possibly (in addition) display the #default_value out to the side of the field if the value in the textbox has been modified from the default.

catch’s picture

Personally, I really, really dislike having to manually clear out a form in order to type into it, which I think would be the case with default value. Stuff that's never going to be actually used should disappear when you click - having said that, if there's places where #default-value might be a better option it'd be good to use that more around core.

mfer’s picture

Would it be more appropriate for use to use #default-value and set a flag (like #example => TRUE) for javascript to clear it on focus?

keith.smith’s picture

An example where the default value is not equal to the example is the maximum dimensions field on the upload settings screen.

The default value is 0, for unlimited. But the example is 640x480.

RobLoach’s picture

After talking with Keith and webchick, I am convinced there are two different issues going on here...

1. Hints

What webchick introduced here (Yahoo's form) doesn't provide examples of what could be in the textfield, they are "hints". What appears greyed out in the textfield ("First Name", "Last Name", "Day", etc), are hints to what the user should type in that textfield. The user reads "Last Name" and they type their last name into the field. "Last Name" is not an example of what could be in the textfield.

Keith and I discussed this shortly and it seems like these hints (#hint?) are usually the same as what's set in the #title. In a "Last Name" field, the title is set to "Last Name", and this ends up being the same as the hint. In a "Description" field, the user could be presented with a hint of "Write your description...". This means that #hint would default to #title, but be overridden if desired.

The hints are what would be manipulated by the JavaScript. They are the little hint text that would show up initially in text field, to put in a correct value, the user would click on the text field, and then write in their own valid value.

This might have to be managed by a different issue, even though in relates very closely to this issue.

2. Examples

The examples are something completely different than the hint text. Examples would give the user some (an?) example of valid values for the field. They are what you'd see here from Keith's post. What we do with these examples, I'm not too sure. Display them to the right of the textfield, have the #default_value disappear when the use clicks on the field, etc? Really not sure, but I know the examples are different than the hint text. Goodreads uses the grey text as an example of an email.

Owen Barton’s picture

Actually, I think in the yahoo form the 'hints' are basically just field labels that have been put inside the field itself to allow for a more natural and compact layout of fields. Hints are not the same as field labels IMO, but are normally a guide to the format or context of the data that should be input (a little different from the label).

In other words, 'My Name' is really a field *group* (could possibly be a fieldset, or possibly not), and 'First Name' and 'Last Name' are actually the labels for these 2 fields (and must semantically be kept as the HTML label tag).

Hence, I think that we have 3 types of information that can be presented in this way:
1) Hints - e.g. '640x480'
2) Examples - e.g. 'John Smith'
3) Field names - e.g. 'First Name'

The first 2 can be an additional HTML tag (something like the 'units' tag we have now), but the third should pull in the field label tag. There may perhaps be a difference in presentation with the first two, I am not sure.

So in FAPI speak, the developer could perhaps add a '#hint' (?) field that could either have a value of some text (for the case of 1 or 2), or a value of '#title' if the field label itself should be pulled in instead.

RobLoach’s picture

A good example of what we can accomplish by implementing jQuery.Example.js:
https://mypromojobs.com/user/register

Sutharsan’s picture

Component: forms system » usability

Moving all usability issues to Drupal - component usability.

webchick’s picture

Version: 7.x-dev » 8.x-dev
Component: usability » base system

Features go into 8.x.

webchick’s picture

Component: base system » forms system
jhedstrom’s picture

Version: 8.0.x-dev » 8.1.x-dev

Feature -> 8.1.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.0-beta1 was released on March 2, 2016, which means new developments and disruptive changes should now be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.