jQuery Plugin Creation: A Simple Boilerplate

25 February 2015

It's been a while and this is my first post of 2015! Now that's exciting news. right?

I have been experimenting with quite a bit of jQuery lately and making my own plugins is something that is not only a challenge but also a joy. It can lead to many possibilities, so in this short article I shall be showing you a simple boilerplate to get you kick-started on creating your own. Let's get started!

The code

JS
(function($) {
    $.pluginOptions = {
       // put your default options here, in form of an object
    }
    $.pluginName = function(element, options) {

       // private variables
       // reserve $this for easy reference in your methods
       var $this = this;

       // merge settings to your defaults
       var settings = $.extend({}, $.pluginOptions, options);
       
       // public variables
       $this.variable = undefined;

       // public methods
       $this.init = function() {
       }

       $this.function2= function() {
       }

       // private methods 
       function private() {

       }

       // you don't need to reference the init function
       // unless you want to do something upon construction
       $this.init();
    };

    $.fn.pluginName = function(options) {
       // accept options to be passed to the object
        var element = this;
        return this.each(function() {

          //ensure that the element hasn't already got the plugin
          if ($(this).data('pluginName') == undefined) {

             // For each element, create a new plugin object
             var plugin = new $.pluginName(element, options);
             $(this).data('pluginName', plugin);
          }
       });
    }

 } (jQuery));

 $(document).ready(function() {

    // add plugin to your element
    $("div").pluginName({
       //add options
    });

    // reference a public function
    $("div").data("pluginName").function2();
 });

Putting it togrther

For the purposes of this demonstration, the plugin below is going to perform a simple task of changing the background of a div. Not very exciting but a good way of showing you how it works.

HTML/JS
<!doctype html>
<html>
   <head>
      <script type="text/javascript" src="http://code.jquery.com/jquery-1.11.2.min.js"></script>
      <script type="text/javascript">
         (function($) {
            $.pluginOptions = {
               background: "blue"
            }
            $.pluginName = function(element, options) {
               var $this = this;
               var settings = $.extend({}, $.pluginOptions, options);
               
               $this.init = function() {
                  element.css("height","20px");
                  element.css("width","20px");
                  return $this;
               }
               $this.changeBackground= function() {
                  element.css("background", settings.background);
                  return $this;
               }
               $this.init();
            };

            $.fn.pluginName = function(options) {
                var element = this;
                return this.each(function() {
                  if ($(this).data('pluginName') == undefined) {
                     var plugin = new $.pluginName(element, options);
                     $(this).data('pluginName', plugin);
                  }
               });
            }
         } (jQuery));

         $(document).ready(function() {
            // box 1 to the background of blue
            $("#box1").pluginName();
            $("#box1").data("pluginName").changeBackground();

            // box 2 to have a background of red 
            $("#box2").pluginName({
               background: "red"
            });
            $("#box2").data("pluginName").changeBackground();

            // another way
            $("#box3").pluginName({
               background: "green"
            }).data("pluginName").changeBackground();
         });
      </script>
   </head>
   <body>
      <div id="box1"></div>
      <div id="box2"></div>
      <div id="box3"></div>
   </body>
</html>

Further Reading

Comments

comments