{"id":1110,"date":"2014-10-11T20:00:57","date_gmt":"2014-10-11T17:00:57","guid":{"rendered":"http:\/\/www.webcodegeeks.com\/?p=1110"},"modified":"2014-10-11T17:53:29","modified_gmt":"2014-10-11T14:53:29","slug":"things-i-learnt-creating-a-jquery-plugin-part-i","status":"publish","type":"post","link":"https:\/\/www.webcodegeeks.com\/javascript\/jquery\/things-i-learnt-creating-a-jquery-plugin-part-i\/","title":{"rendered":"Things I learnt creating a jQuery Plugin (Part I)"},"content":{"rendered":"

jQuery<\/a> is one of the most used JavaScript libraries, if not the most used one, which allows to make great things with the big set of little tools it offers to the web developers: HTML\/DOM manipulation, CSS manipulation, HTML event methods, effects and animations, AJAX, utilities, \u2026<\/p>\n

One of the key aspects of jQuery is the possibility to extend it with new\u00a0functionalities, so called plugins<\/em>. For those who has a basic knowledge of jQuery and want or need to create a new jQuery plugin this post tries to be a helping summary of good things to take into account.<\/p>\n

 <\/p>\n

Before to start<\/h2>\n

Because of the flexibility and powerful of the language, the Perl community is proud of his Tim Today<\/em> motto, \u00a0that is:<\/p>\n

There\u2019s more than one way to do it<\/span><\/strong><\/p><\/blockquote>\n

You can consider the same for JavaScript, that\u2019s true. The fact JavaScript is not an object oriented language but a prototype based language<\/a> allows to follow the OOP paradigm in many different ways. Looking for a template code to create a jQuery plugin I found tons and not all following the same conventions and ideas.<\/p>\n

Here I present a mix of the most accepted templates and its key aspects.<\/p>\n

The code<\/h2>\n

Accompanying the article you can find\u00a0the self documented version of the boilerplate code at my GitHub repository<\/a>.<\/p>\n

Where to start<\/h2>\n

If you are planning to create a jQuery plugin, the first places I suggest you to start reading is the Plugins\/Authoring<\/a> section of the project documentation. It is a great starting resource but in the real live you will find soon you need to know a bit more of that.<\/p>\n

Using a jQuery plugin<\/h2>\n

Suppose we have a jQuery plugin called beautyLink<\/code>, that transform a normal link (the <a><\/code> element) into a really nice one changing the font family, text and background color. So we need to include it in our page before start using it:<\/p>\n

\r\n<script type="text\/javascript" src="jquery.js"><\/script>\r\n<script type="text\/javascript" src="jquery-beautylink.js"><\/script> <\/pre>\n
The conventional way to create and apply it on an element would be:<\/p>\n
\r\n$('#linkID').beautyLink();<\/pre>\n
or, if you want to apply on each link of the current page:<\/p>\n
\r\n$('a').beautyLink();<\/pre>\n
Later, to change the text color to red we could invoke a plugin\u2019s public method like:<\/p>\n
\r\n$('#linkID').beautyLink('color', 'red');<\/pre>\n
or to retrieve the current text color:<\/p>\n
\r\n$('#linkID').beautyLink('color');<\/pre>\n
that is, the color<\/code> method can act as a setter or getter depending if we pass a value or not.<\/p>\n
Creating a new plugin<\/h2>\n
All right, we know how to use a plugin but we want to create a new one. The first step we need to do is to create a new JavaScript file where to place our code. As a good practice this file must contain a documentation header section with the plugin\u2019s name, version, author contact information, license, etc<\/p>\n
When we include the JavaScript file in a web page we need the code to be auto-executed so the plugin can be registered within the jQuery. To do so all the JavaScript code in the file must be inside the code:<\/p>\n
\r\n(function($, window, document, undefined) {\r\n  \/\/ The code here\r\n})(jQuery, window, document);<\/pre>\n
This way, the code of our plugin will receive a reference to the jQuery library, the window and the document and, also, an undefined reference on the undefined<\/code>parameter that we can use to compare undefined values (wow, that was too much undefineds in a sentence).<\/p>\n
The wrapper function<\/h2>\n
To create a jQuery plugin we need to register a new function in the jQuery.fn<\/code> object. This is an array where jQuery stores references to all available or included plugins in the current page. To add a new one simply write something like:<\/p>\n
\r\njQuery.fn.myPlugin = function(options) {\r\n  \/\/ Do your awesome plugin stuff here\r\n};<\/pre>\n
or<\/p>\n
\r\njQuery.fn['myPlugin'] = function(options) {\r\n  \/\/ Do your awesome plugin stuff here\r\n};<\/pre>\n
The function you define here is the entry point to your plugin. It is a wrapper function that must handle the plugins initialization or\u00a0invocation\u00a0to any plugin\u2019s method.<\/strong><\/p>\n
How to distinguish the action?<\/h3>\n
The question is, how do we implement the plugin\u2019s wrapper function to distinguish if it must initialize the plugin or call a method? The answer is in the options<\/code> parameter.<\/p>\n
When we instantiate a plugin without passing any argument the options<\/code> parameter isundefined<\/code>:<\/p>\n
\r\n$('#linkID').beautyLink();<\/pre>\n
If we instantiate passing any argument the options<\/code> parameter is an Object<\/code>:<\/p>\n
\r\n$('#linkID').beautyLink({\r\n  someOption: 'a',\r\n  someOther: 123\r\n});<\/pre>\n
Finally, if we are calling a plugin\u2019s method like:<\/p>\n
\r\n$('#linkID').beautyLink('color', 'red');<\/pre>\n
then the options<\/code> parameter is an array with two elements ['color', 'red']<\/code><\/p>\n
The starter code for the wrapper function<\/h2>\n
With the above in mind, we can write the base code for the wrapper function:<\/p>\n
\r\n$.fn[pluginName] = function(options) {\r\n    var args = arguments;\r\n\r\n    if (options === undefined || typeof options === 'object') {\r\n        \/\/ Creates a new plugin instance\r\n\r\n    } else if (typeof options === 'string' &amp;&amp; options[0] !== '_' &amp;&amp; options !== 'init') {\r\n        \/\/ Call a public pluguin method (not starting with an underscore) and different\r\n        \/\/ from the 'init' one\r\n\r\n    }\r\n};<\/pre>\n
Chainable or not chainable<\/h2>\n
jQuery is famous (and powerful) by its chainable way to work, that is, a call to a method returns a reference to the same element so we can make another call. For example:<\/p>\n
\r\n$('#someID')\r\n  .parents(".pane")\r\n  .animate({ opacity: "hide" }, "slow");<\/pre>\n
or applied to our plugin:<\/p>\n
\r\n$('#linkID')\r\n  .beautyLink('color', 'red')\r\n  .beautyLink('backgroundColor', 'black');<\/pre>\n
We must think which of our methods must be chainable and which ones not. For example, the getter methods must break the chainability<\/strong>. In our case we want a call to:<\/p>\n
\r\n$('#linkID').beautyLink('color');<\/pre>\n
returns the red<\/code> value and not a reference to the element to make another call.<\/p>\n
Implementing chainability<\/h3>\n
When the wrapper function $.fn[pluginName]<\/code> is called the this reference points to:<\/p>\n