Adding user options to your jQuery plugin

Recently I created a tutorial named ‘How to write a simple jQuery plugin‘. It is necessary to go through that tutorial if you have no idea how to create a simple jQuery plugin.
This tutorial will teach you how to create user-friendly-options for the plugin user – Like you have probably seen and used many times before.

Why are options necessary?

These options turn a script into a jQuery plugin. It changes the script from being static to dynamic.
It can save you time in a few ways:

  • It makes the script dynamic.
  • It saves you the time of sifting through the code.
  • It saves you the time of re-scripting the jQuery.
  • You don’t have to worry about messing up the working plugin.

Let’s get started.

What are we planning on doing?

I think we should do something similar to the ‘How to create a simple jQuery plugin’ tutorial, since the most simple examples often gives us the “AHA!” moment.
This plugin is going to be called “redBorder” and it will be create a 3px, solid red border around the targeted element by default. The options we are going to have is to change the values of the property, and to change the property itself as well!

The jQuery Javscript

(function($){
	jQuery.fn.extend({

		// Plugin Name
		redBorder: function(options) {
			
			// Defaults options are set here
			// Every default goes within the { } brackets as seen below
			// A comma separates the different values
			var defaults = {  
				property: "border",
				value: "3px solid red"  
				
			};  
			var options = $.extend(defaults, options);  
			
			return this.each(function() {   
			
				// Add 'options.' before the value 
				// This is done to inform jQuery it is part of the default options
				jQuery(this).css(options.property, options.value);
			
			});

		}

	});
})(jQuery); 

If we target a paragraph element like this:

$("p").redBorder();

It will come out looking like it did in the other plugin example.

However, if we add the following options (The properties and values options have to be valid CSS properties and values)

$("p").redBorder({property: "background", value: "red"});

It will produce the following results:

Conclusion

And that is it! You now know all you need to know in order to create a jQuery plugin with user options. I had an “AHA!” moment when I figured out how to add options. It seems to open up a whole new world.
In case anyone was wondering, I like to use the ‘jQuery(“p”)’ syntax when I’m creating a plugin or function and I use ‘$(“p”)’ all the other times.

Any questions or comments?

  1. Pingback: How to create a simple jQuery plugin | CSS-Plus

  2. jatinder says:

    Would you also create tutorial for event base plugins?

    And also how to use plugin function from outside.

    Eg: on click of something i have to call function defined in the plugin, how i can achieve the same?

    1. jatinder says:

      Thanks for the above Tutorial!

    2. If you’d like to look at an example of that, you can check out the PlusSlider js on github and the documentation will explain how to make use of it.

      Basically it entails creating a new plugin object:

      slider = new $.plusSlider($('#slider'), {});

      From there you could make use of all the methods and properties, for example:
      slider.toSlide(‘next’); would change the slide.

      I will work on a tutorial explaining this in depth.

  3. Hemant soni says:

    Hello sir,
    This is very easy code to understand plugin, so first thanks. but i did not understand following ling

    var options = $.extend(defaults, options);
    please explain it.

    thanks.
    .

    1. Jamy Golden says:

      Hi Hemant, that extend method is a custom jQuery method which you can read a bit more about here: http://api.jquery.com/jQuery.extend/

      But basically the second object passed into that jQuery.extend method overwrites the properties and methods within the first object. So you have default options, and then you pass a set of custom options which override the default set. Let me know if I need to explain a bit more :)

  4. Hi Jamy,

    You should consider putting your default options outside the redBorder function so they are not re-created each time the function is called.

    Just my 2 cents.

    Cheers!

  5. Lucas says:

    I already set the default options but I get “unidefined” error. Why? Thanks

    1. Jamy Golden says:

      Can you send me a jsfiddle or a codepen example of the problem?