Looks great Joern. Nice work.
I'm sure we can mock up a static page for this plugin soon to work out the positioning across browsers.
It should also work with textareas, like I'm doing here: http://scottjehl.com

I'm curious about this part of the spec above though:
"-from an existing value attribute
- from title attribute
- from metadata
- from plugin arguments/options, both as actual value and callback."

I'm worried this will promote poor markup practices.
Shouldn't we simply require a label element with a properly linked "for" attribute?

That way we could just say...
$.fn.watermark(...
//get input's ID, find corresponding label, add behavior


Curious on your thoughts on this...
Again, nice work!!

I agree this looks great and I can't wait for this to be built in to the UI! I did some work on a watermark widget which is basically identical to the DAER watermark plugin before so wanted to share it here. http://daersystems.com/jquery/watermark_ui/

It lets you call watermark on the label and pass {target:"#id"} or else it looks for the 'for' attribute to find the proper input. If you call watermark on the input it looks for a label in the previous element and uses that or else creates one. The value for the watermark is pulled from value passed in the options, the input's title attribute, or the label's text.

Also put some options in there so you can control the effects on hide/show, add a class to the label, and force the label to inherit css from the input.

Thought it may give some ideas around allowing users to customize the watermark's css and effects.

Thanks Scott and Jason for your comments.

I've reworked parts of the document, leaning towards Scott's suggestion in regards to the watermark source. jQuery UI's philosophy makes this choice pretty clear - I think we can still add other source-options later when there is a good argument for that.

I think the two TODOs left affect animations, how to disable and customize them - this needs to be unified with the rest of jQuery UI, and themeing and positioning. The latter should be handled by the design team if this component gets on the roadmap.

Scott Jehl and I were just discussing this and through is really slick to use the label for the watermark text, there are a lot of cases where I would want to show the label and still provide a watermark for helper text or formatting hints. So we're thinking that it might make more sense to use the input or textarea's title attribute to store the watermark text instead of using the label. Should we offer an option to hide the label if watermark is called on an input or textarea? This should be defaulted to false if we go with it.

Todd, how about either applying the watermark method to the input element, using the title attribute as the source, or applying it to the label, then transforming the label itself into the watermark. Its mostly implemented that way already anyway.

Todd, I like the idea. What about defaulting to use the label, unless the title attribute is present. If title is present, use it, and don't hide the label. Then we don't need an option. That leaves a (obscure enough) case where someone wants a label hidden when the title is present (presumably with a different hint). In that case they would simply hide the label manually.

In case my comment wasn't clear, I just summed it up offline with Jörn:
- if the title is present, use the title, not the label
- if the title is not present, use the label
- if the label isn't used, don't hide it
- if the label is used, hide it

After further discussion with Richard: Using the title as a watermark is not a good idea. The title should be used as a tooltip, native or enhanced via the tooltip widget. Using it as a watermark just causes other issues: What when you want to use the label as the watermark, while keeping the title intact?

In that regard, we should stick with using the label as the watermark. If you need something else, use something else. Following that, the watermark would always be applied to the input (not the label, as I mentioned above); when there is no associated label, there is no watermark.

Yeah, I forgot title is already used for tooltip. So it would be limiting if we used it for the watermark source. As for only using the label, my reasoning is two-fold: 1) the watermark is only visible when the field doesn't have focus. So anything more than a label (a hint or a description) wouldn't be visible when it's needed. Such a hint would need to be visible while data is being entered into the field, so it should be external 2) If we've got three different elements, the label, the title attribute (and tooltip), the watermark, it's going to get quite complex if we allow one of those to be sourced from any of the others, or from some other value (what if you want a watermark that's different than a label that's different than a title that's different than a tooltip). It would mean an option, maybe two. This is supposed to be an extremely simple plugin. Put the label as a watermark over the input, to save space, and label more prominently.

I agree that this is getting pretty complex but the main thing I'd like to preserve is the ability to use the watermark to provide formatting help in an input with a visible (and semantically correct) label. For example, I want the word "Date" to be the label for the input and the d/mm/yyyy to be a watermark and the tooltip is a longer format help bubble. This seems like a pretty common scenario:

Date: [ dd/mm/yyyy ] tooltip = { You may select a reporting start date from January 1, 2005 through to today }

So if label needs to be left alone, and title on the input is being reserved for a tooltip or other, longer-format help about the input could we use a title on the label for this? We have 2 titles to work with: label and input/textarea.

If you want the simple no, label username/password style from the design above you do a watermark on the label but if a title attribute exists for the label, we leave the label alone and use the title for the watermark. Similar to what Richard posted above but with only the top 2 scenarios.

That works for me. But I don't see why it would only be the top 2 scenarios. If there is no title attribute on the label, the label is used as the source for the overlay, and the original label hidden, right? Otherwise you'd have

Date: [ Date ]

If there is a title, it is presumed to be different, so the label is left visible. So I still see all 4.

Good point Byron. Relevant Links:

A demo (doesn't work in FF for me, works fine in Safari 3.1: http://simon.html5.org/sandbox/js/placeholder-demo.htm It looks like it should work in FF, as there is some JS included for that.

The placeholder attribute in the html 5 spec: http://dev.w3.org/html5/spec/Overview.html#attr-input-placeholder

With that in mind, an approach for us could be to simply look for the attribute to display the watermark. We could exclude browsers that have native support for the placeholder attribute, though they probably won't support animations...

Good point about the animations. We should provide a mechanism/option to override the default handling the of the html5 feature if the dev prefers to use the jquery ui effects instead.

@Scott, I meant that this plugin can be called on an element, not that it would automatically find this attribute. Sorry for the confusion, sounds like we're all in agreement.

The main idea is that there are HTML5 tags and attributes that we could consider as *one possible way* to supply information to our plugins. Since HTML5 code will usually be ignored on older browsers, we just need to make sure the starting HTML markup will still be work and be meaningful enough to older browsers. In this specific case, using the placeholder attribute is a good option if you don't mind that people in old, non-JS browsers won't see this placeholder text at all since it's encoded in an attribute that will be ignored. For many situations, that is probably the case. As long as our plugin supports other ways to populate the watermark text (label, title attribute, JS option when called, etc.) then this is great. We just need to built in some flexibility so I can decide to use a title attribute instead of the placeholder attribute because the watermark text is so important that every device may need to see it.

How about...

Use the placeholder-option when specified, otherwise use the placeholder-attribute, if available, otherwise do nothing. The placeholder-option can be plain text, or a callback. The callback is called for each element when displaying the watermark and can return the title-attribute, or get the label, or whatever you want.

That would build upon the html5 feature by default, while maximal flexibility in choosing other sources.

I think Jorn's final suggestion seems like the way to go. If everyone in on board, we can produce some static mockups to get the CSS worked out (if needed).

A nice demo of the widget: http://www.commadot.com/jquery/experiments/shunra/

What about using the positionTo utility to position the watermark? Also should we add an option for watermark position? Some may prefer right-aligned.

There is a bug in ie8 standards mode if the input border is set to medium. On line 25 it tries to calculate a top/left position for the label. When the border comes back as NaN, watermark continues to try and set the top/left position to NaNpx.

One thing to be added is an onchange event. If the content is updated when not focused in the element (such as with datepicker) the watermark stays in place. Adding the following to the bind list worked for me

.bind("change." + this.widgetName, function() {
if(this.value)
label.hide();
});