Watermark plugin for jQuery Version 3.0.4

This simple-to-use jQuery plugin adds watermark capability to HTML input and textarea elements.

A watermark typically appears as light gray text within an input or textarea element whenever the element is empty and does not have focus. This provides a hint to the user as to what the input or textarea element is used for, or the type of input that is required.

For example, a search input space sometimes appears at the top of the page, giving the user quick access to the search functionality. Oftentimes you will see the word "Search" in light gray text in that space, and when the user clicks into the entry space, the word disappears. That is an example of a watermark.

This plugin lets you specify the text that will be used for the watermark, and optionally you can supply your own CSS class name that will be applied to the input or textarea element every time the watermark is shown.

If you do not supply your own class name, the class name "watermark" is used.

In addition, this plugin allows you to change the watermark text and/or class name any time after the watermark is initialized. One of the examples included with the plugin demonstrates this capability by showing a watermark that doubles as a countdown timer.

The plugin is also capable of displaying a watermark in password input elements, showing the watermark in plain text, but then switching to password-protected (obscured) mode when focused. (Because of the complexity of making password watermarks operate, it is recommended that programmatic changes to password input elements be avoided.)

New for version 3.0, the plugin can also handle input elements of type="search" (WebKit browsers), and it supports drag-and-drop to watermarked elements, plus native browser support (when available).

Drag-and-drop support is significant, because it is currently supported by few (if any) jQuery plugins. Combined with the Watermark plugin's ability to support native browser watermark features, this may be the most feature-complete watermark plugin available.

See latest change log

Using the plugin

To set a watermark of "Required information" on an input element, you would use a line of code such as:

   $('#inputId').watermark('Required information');

If you want to use a different class name to define the appearance of the watermark, simply add the class name to the options specified in the second argument:

   $('#inputId').watermark('Required information', {className: 'myClassName'});

If you want to avoid using native browser support (for example, for Search elements that have buggy drag-and-drop support in WebKit), add the useNative option to the options specified in the second argument, as follows:

   $('#inputId').watermark('Search', {useNative: false});

Important usage notes

• Multiple input elements - You can set multiple input elements to the same watermark at once by including them all in the jQuery matched set. For example, you can let the user know which input is optional by setting a watermark based on class name:

   $('input.optional').watermark('Optional');

• Non-relevant elements ignored - The plugin ignores any elements in the matched set that are not input elements of type="text/password/search" and not textarea elements, so you do not have to filter your matched set to remove extra elements.

• Return value - When watermark(...) is called on a matched set, it returns the same matched set, allowing you to chain the plugin.

• Programmatic changes - JavaScript events do not generally respond to programmatic changes in an input element's value, so you will need to manually refresh the watermark after you change the value through code. When calling the plugin for the purpose of a refresh, do not include any arguments. An example of changing the value, followed by a watermark refresh, would be:

   $('#myInput').val('newValue').watermark();

• Avoid programmatic changes to passwords - Because of the complexity of making password watermarks operate, it is recommended that programmatic changes to password input elements (changes made after the page finishes loading) be avoided.

• Mutli-line textarea watermarks - In textarea elements, you can create multi-line watermarks by specifying a line-break character ( \n ) where each new line should start.

• Form submission - The plugin automatically cleans up all watermarks prior to form submission, so you should never need to manually remove watermarks before submit.

• Dynamic changes to watermark text and/or class - After a watermark is initialized, you can continue to make changes to it, changing the text, the class name (style), or both. The plugin demo page included in the download package demonstrates a watermark that doubles as a countdown timer. As the timer nears zero, the style changes to red text.

Static properties and methods

The plugin includes static properties and methods that are called in a "stand-alone" manner (not on a matched set). Many developers will never need to use any of these properties or methods, but they exist in case you need them.

Any time < selector > is indicated, you can pass any valid jQuery selector, such as a DOM element, selector string, jQuery matched set, an array of elements, etc.

$.watermark.options

Examples

   $.watermark.options.className = 'myClass';
   
   $.watermark.options.useNative = false;
   
   $.watermark.options.useNative = myFunction;
   
   $.watermark.options = {
      className: 'myClass',
      useNative: false
   };

Description

You can control the default class name to use for watermarks, as well as if native browser support for watermarks should be used. Both values can be overidden for individual watermarks.

$.watermark.show( < selector > )

Example

   $.watermark.show('input.optional');

Description

The equivalent of calling .watermark() (with no arguments) on a matched set, this method "refreshes" all matched elements.

$.watermark.hide( < selector > )

Example

   $.watermark.hide('#myInput');

Description

Removes the watermark from all matched elements. This does not completely destroy the watermark definition, so if after calling this method the user enters and leaves the element, the watermark will re-activate.

$.watermark.showAll()

Example

   $.watermark.showAll();

Description

This method "refreshes" all watermarks on the page. Maybe use useful after several programmatic changes were made to input values.

$.watermark.hideAll()

Example

   $.watermark.hideAll();

Description

Removes all watermarks from the page. This method is called automatically just before form submission to "clean up" all watermarks, and ensure that watermark text is not submitted to the Web server. After calling this method, a watermark will re-appear if the user enters and then leaves an input element that previously contained a watermark.

Troubleshooting

Watermark does not ever appear

Check the following:

• Verify you are using the right syntax:

   $( < selector > ).watermark( < text > [ , < options > ] )

• Be sure the first argument includes a valid string, and that the string is not empty.

• Are you certain that your jQuery selector matched one or more input elements? You can quickly test if your selector is matching elements by temporarily inserting an alert() call into your code. If a zero (0) is displayed in the alert box, you know that it did not match any elements.

   alert( $( < selector > ).length );

• The plugin only places watermarks on input elements with type="text/password/search" and on textarea elements. Are you sure that you are matching the correct input element(s) and/or textarea(s)? For example, you cannot use a watermark on an input element with type="checkbox".

Watermark appears in regular-styled text (not light gray text)

Don't forget that you need to define the CSS style for the watermark, either in an external style sheet, or within the page itself (in style tags).

If you are using the default class name (not specifying a className property in the second argument), you will need to define the watermark style using the class name watermark. For example:

<style type="text/css">
.watermark {
   color: #999;
}
</style>

If you specified the className property in the second argument, be sure that you have defined the watermark styles using that class name.

Another common cause is a CSS cascade problem, where your style definition is overridden by another definition with a higher level of specificity.

In the following example, the watermark style would appear as black text, even though the gray color is defined after the black definition:

<style type="text/css">
input[type=text] {
   color: #000;
}
.watermark {
   color: #999;
}
</style>

Even though the definition containing the gray color (#999) appears after the definition with the black color (#000), the watermark text will still be black. That's because the first definition has a higher level of specificity, according to CSS rules, than the second definition.

A sure-fire way to be sure this doesn't happen is to use !important on your watermark definitions, like so:

<style type="text/css">
.watermark {
   color: #999 !important;
}
</style>

Can't enter the same text as the watermark

What if you want the user to be able to enter the exact same text as a watermark? For example, your search box has the watermark "Search", and the user wants to search for the term "Search".

Normally, once the user enters "Search", the plugin recognizes the text as a watermark, and applies the watermark style.

One easy way around this is to use a watermark that contains spaces after the text. So in the case of the search box, you could use
"Search      " instead of "Search".

The user can't see the spaces, but internally they distinguish the watermark in a way that the user is unlikely to stumble across.

About the author

Todd Northrop is the owner and developer of Lottery Post (www.lotterypost.com), the world's largest community of lottery players and home to the #1 lottery results service worldwide.

He founded his technology company, Speednet Group (www.speednet.biz), in 2000.

Todd was featured in Microsoft's (ASP.NET AJAX Showcase).