Stateful jQuery plugins with jQuery UI’s widget factory

There are many different formats for jQuery plugins, many of the formats are not designed for stateful plugins.  What is a stateful plugin? A plugin that keep track of what the state of the plugin is and lets you call methods and change properties even after the plugin as been initialized.  All of jQuery UI‘s plugins are stateful (as of version 1.7.2), part of the jQuery UI core is a “Widget Factory” which makes it very easy to quickly make a stateful plugin.

Below is an example of a plugin created with the jQuery UI widget factory.

$.widget('namespace.pluginName', {
	_init: function() {
		// stuff that is called on initialization of the plugin

		//this.options a combination of the defualt options and the ones passed in during the plugin initialization
		if (this.options.foo) {
			//this.element is the element that the plugin was called on
			this.element.fadeOut();
		}
	},
	_privatemethod: function() {
		//private internal function
		//private functions should be named with a leading underscore
		//will only be able to be called from inside the plugin
	},
	publicmethod: function() {
		//this is a public fuction that can be called outside of the plugin

		//calling the private method from inside the public method
		this._privatemethod();
	},
	value: function() {
		//this is a public function that is defined as a getter
		//meaning it returns a value not a jquery object
		return this.options.foo;
	},
	destroy: function() {
		$.widget.prototype.apply(this, arguments); // default destroy
		// this is where you would want to undo anything you do on init to reset the page to before the plugin was initialized.
	}

}));

$.extend($.namespace.pluginName, {
	getter: 'value',
	defaults: {
		option1: 'bar',
		foo: true
	}
});

With this you can call the following to initialize the plugin

$('#myelement').pluginName();

To call the publicmethod function you can now do this after initializing the plugin:

$('#myelement').pluginName();
$('#myelement').pluginName('publicmethod');

This makes it very easy to create a stateful jQuery plugins very quickly. All you need is the core of jQuery UI, but most people already have the whole jQuery UI package on their page.



  • motoplux

    Hi!
    Helpful post for me:)
    I think should be better to write

    20. this._privatemethod();

  • Pingback: jQuery UI 1.8 Widget Factory « Petersen Did It

  • allen

    I’m sure you don’t get this enough. thank you. this helps people like me a lot.

  • Jørgen

    Good and very on-the-spot about stuff that could be really confusing. Thanks!

  • Katman

    What should I do if I want to call the public method with arguments?

    • http://blog.petersendidit.com/ David Petersen

      You just have to do $(‘#myelement’).pluginName(‘publicmethod’, ‘arg1′, ‘arg2′);

  • Phil

    I notice you have ‘destory’ as a function name; I assume that should be ‘destroy’.

    • http://blog.petersendidit.com/ David Petersen

      Yup, it should be destroy. I have fixed the post. Thanks

  • Pingback: How to make your own great jQuery UI widgets (Basics of making a control) « Nathan's Thoughts