In a previous post I talked about how you can do a textbox watermark very easily using JQuery. I’m long overdue in showing how you can take that same JQuery code and make it into a simple plugin.

So why would we make it a plugin? A JQuery plugin gives you the chance to encapsulate JQuery functionality into a single, pluggable module which can then be activated by calling a single method (with optional settings passed to it). If you’ve used things like the JQuery Validation library, you’ve seen a bit of the power of plugins. They are not hard to write, and the official documentation on the JQuery site gives you enough information to get started.

We will start off with the same basic HTML text box that we had in the previous post:

<input type="text" id="textBox1" />

And some simple CSS to go with it:

.watermark { color: #CCC; font-style: italic; }

So, just to recap what we want to do: when our focus is off of the textbox, and the textbox is empty, we want to display the default text, which is “type here…” in a light gray color. When the focus is on the textbox and the default text is displayed, we want to clear the box and the styling. If they type something in the box and then click elsewhere, we want to keep the new text and not reactivate the watermark style.

Using the previous JQuery code I posted as a base, here is the plugin code with comments to explain how it works:

(function($) {
	// Create a plugin with the name 'watermark'
	$.fn.watermark = function() {
		// Loop through the elements in the selector that we call the plug-in on
		this.each(function() {
			// Apply defaults to the box
			$(this).addClass("watermark").val("type here...");

			// Apply our focus and blur events
			// When we click on the field, we expect it to clear the field and remove the watermark
			$(this).focus(function() {
				$(this).filter(function() {
					// Check to see if we have a blank field or the default text
					return $(this).val() === "" || $(this).val() === "type here...";
				}).val("").removeClass("watermark");
			});

			// When we click off of the field, we expect it to replace the watermark,
			// unless we have entered text
			$(this).blur(function() {
				$(this).filter(function() {
					// Check to see if the field is blank
					return $(this).val() === "";
				}).addClass("watermark").val("type here...");
			});
		});
	};
})(jQuery);

To apply the plugin to our text box above we can now simply do this:

$(function() {
	$("#textBox1").watermark();
});

Making it better

What we’ve done so far is fine if you’re only concerned with a specific case, but what if we wanted to use this same plugin for different default text scenarios, or with different CSS classes? As it turns out, this is not hard to do.

We’re going to add two simple options to our plugin, but leave our defaults as they currently are:

(function($) {
	// Create a plugin with the name 'watermark'
	$.fn.watermark = function(settings) {
		// Defaults
		var config = {
			watermarkClass: 'watermark',
			defaultText: 'type here...'
		};

		// merge the passed in settings with our default config
		if(settings) $.extend(config, settings);

		// Loop through the elements in the selector that we call the plug-in on
		this.each(function() {
			// Apply defaults to the box
			$(this).addClass(config.watermarkClass).val(config.defaultText);

			// Apply our focus and blur events
			// When we click on the field, we expect it to clear the field and remove the watermark
			$(this).focus(function() {
				$(this).filter(function() {
					// Check to see if we have a blank field or the default text
					return $(this).val() === "" || $(this).val() === config.defaultText;
				}).val("").removeClass(config.watermarkClass);
			});

			// When we click off of the field, we expect it to replace the watermark,
			// unless we have entered text
			$(this).blur(function() {
				$(this).filter(function() {
					// Check to see if the field is blank
					return $(this).val() === "";
				}).addClass(config.watermarkClass).val(config.defaultText);
			});
		});
	};
})(jQuery);

Now, we can customize how we use the plugin:

$(function() {
	$("#textBox1").watermark({
		watermarkClass: 'grayText',
		defaultText: 'search'
	});
});

Files

• Sample (watermarks.zip)

Useful links

• Plugins/Authoring (jquery.com)