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.
Comment | File | Size | Author |
---|---|---|---|
#16 | example_223941-16.patch | 8.16 KB | RobLoach |
#16 | examplejavascriptdisabled2.png | 32.65 KB | RobLoach |
#11 | 223941-2.patch | 5.55 KB | keith.smith |
#11 | uploadexample2.PNG | 29.6 KB | keith.smith |
#9 | drupal_textfield_example-2.patch | 6.42 KB | keith.smith |
Comments
Comment #1
webchickI 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.
Comment #2
keith.smith CreditAttribution: keith.smith commentedHmm. 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.
Comment #3
RobLoachSubscribing, as this would be very, very, cool. There are many implementations of the example text field if no value is given.
Comment #4
webchickSo 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.
Comment #5
RobLoachThis is exactly what you're looking for: jQuery Example Plugin.
Comment #6
keith.smith CreditAttribution: keith.smith commented@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.
Comment #7
RobLoachOnce 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:
Comment #8
RobLoachFor those visual learners, here's a couple of screenshots with JavaScript being enabled and disabled with the patch.
Comment #9
keith.smith CreditAttribution: keith.smith commentedThanks 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:
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.
Comment #10
webchickI 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.
Comment #11
keith.smith CreditAttribution: keith.smith commented(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.)
Comment #12
webchickI 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*!
Comment #13
RobLoachI 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...
Comment #14
kourge CreditAttribution: kourge commentedIf we don't get through the licensing issue I can totally roll this JS.
Comment #15
mudgemeister CreditAttribution: mudgemeister commentedI 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
Comment #16
RobLoachThanks 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).
Comment #17
catchsubscribing. This looks very lovely.
Comment #18
mfer CreditAttribution: mfer commentedsubscribing
Comment #19
webchickJust 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..
Comment #20
jbrauer CreditAttribution: jbrauer commentedsubscribe. This seems like a great improvement.
Comment #21
keith.smith CreditAttribution: keith.smith commentedFrom the anonymous (?) comment on webchick's blog:
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.
Comment #22
catchPersonally, 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.
Comment #23
mfer CreditAttribution: mfer commentedWould it be more appropriate for use to use #default-value and set a flag (like #example => TRUE) for javascript to clear it on focus?
Comment #24
keith.smith CreditAttribution: keith.smith commentedAn 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.
Comment #25
RobLoachAfter 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.
Comment #26
Owen Barton CreditAttribution: Owen Barton commentedActually, 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.
Comment #27
RobLoachA good example of what we can accomplish by implementing jQuery.Example.js:
https://mypromojobs.com/user/register
Comment #28
Sutharsan CreditAttribution: Sutharsan commentedMoving all usability issues to Drupal - component usability.
Comment #33
webchickFeatures go into 8.x.
Comment #34
webchickComment #35
jhedstromFeature -> 8.1.