This chapter covers

• Why extend jQuery with custom code
• Using third-party plugins
• Guidelines for effectively extending jQuery
• Writing custom utility functions
• Writing custom methods for jQuery objects

12.1 Why extend jQuery?

12.2 Where to find plugins

12.2.1 How to use a (well-written) plugin

12.2.2 Great plugins for your projects

12.3 The jQuery plugin authoring guidelines

12.3.1 File and function naming conventions

• Choose a name for the plugin that's short but also reasonably descriptive.
• Prefix the filename with jquery.
• Optionally add the name of the company or the suite.
• Follow that with the name of the plugin.
• Optionally include the version number of the plugin.
• Conclude with .js.

12.3.2 Beware the $

(function($){
//
// Plugin definition goes here
//
})(jQuery);

12.3.3 Taming complex parameter lists

complex(p1, options)

function complex(p1, options) {
 var settings = $.extend({
 p2: defaultValue1,
 p3: defaultValue2,
 p4: defaultValue3,
 p5: defaultValue4,
 p6: defaultValue5,
 p7: defaultValue6
 },
 options || {}
 );
 // Remainder of the function...
}

(function($) {
 var defaults = {
 idMenu: null,
 bindLeftClick: false
 };
})(jQuery);

12.3.4 Keep one namespace

var init = function(options) {
 // Code here...
};
var destroy = function() {
 // Code here...
};

(function($) {
 var defaults = {
 idMenu: null,
 bindLeftClick: false
 };
 $.fn.init = function() {
 // Code here...
 };
 $.fn.destroy = function() {
 // Code here...
 };
})(jQuery);

(function($) {
 var defaults = {
 idMenu: null,
 bindLeftClick: false
 };
var methods = {
 init: function(options) {
 // Code here...
 },
 destroy: function() {
 // Code here...
 }
 };
 $.fn.jqiaContextMenu = function(method) {
 if (methods[method]) {
 return methods[method].apply(
 this,
 Array.prototype.slice.call(arguments, 1)
 );
 } else if ($.type(method) === 'object') {
 return methods.init.apply(this, arguments);
 } else {
 $.error('Method ' + method +
 ' does not exist on jQuery.jqiaContextMenu');
 }
 };
})(jQuery);

12.3.5 Namespacing events and data

The init() method has the following responsibilities:

1. Check that the options are passed to the plugin, especially that mandatory ones are provided.
2. Merge the passed options with the default values.
3. Test if the plugin has already been initialized on the selected elements.
4. Store the options on the elements in the jQuery collection.
5. Listen for the mouse right button's click event, named contextmenu, on the elements in the jQuery collection to show the custom menu. Optionally, listen for the mouse left button's click event(click).
6. Hide the custom menu when a click event is fired outside the elements in the jQuery collection.

12.3.6 Maintaining chainability

12.3.7 Provide public access to default settings

12.4 Demo: creating a slideshow as a jQuery plugin

This page sports the following components:

• A set of thumbnail images
• A full-size photo of one of the images available in the thumbnail list
• A set of buttons for moving through the slideshow manually and for starting and stopping the automatic slideshow

The behaviors of the page are as follows:

• Clicking any thumbnail displays the corresponding full-size image.
• Clicking the full-size image displays the next image.
• Clicking any button performs the following operations:
  First-Displays the first image
  Previous-Displays the previous image
  Next-Displays the next image
  Last-Displays the last image
  Play-Commences moving through the photos automatically until clicked again
• Any operation that moves past the end of the list of images wraps back to the beginning and any operation that moves past the beginning of the first image, and clicking Previous while on the first image displays the last.

jqiaPhotomatic(options)
Parameters
options (Object)
Returns
The jQuery collection

The options for the Jqia Photomatic custom plugin method

12.4.1 Setting up the markup

$('#thumbnails-pane img').jqiaPhotomatic({
  photoElement: '#photo-display',
  previousControl: '#previous-button',
  nextControl: '#next-button',
  firstControl: '#first-button',
  lastControl: '#last-button',
  playControl: '#play-button',
  delay: 1000
});

12.4.2 Developing Jqia Photomatic

(function($){
 var methods = {
 init: function() {
 }
 };
 $.fn.jqiaPhotomatic = function(method) {
 if (methods[method]) {
 return methods[method].apply(
 this,
 Array.prototype.slice.call(arguments, 1)
 );
 } else if ($.type(method) === 'object') {
 return methods.init.apply(this, arguments);
 } else {
 $.error('Method ' + method +
 ' does not exist on jQuery.jqiaPhotomatic'
 );
 }
 };
})(jQuery);

$.fn.jqiaPhotomatic.defaults = {
 photoElement: 'img.photomatic-photo',
 transformer: function(name) {
 return name.replace('thumbnail', 'photo');
 },
 nextControl: null,
 previousControl: null,
 firstControl: null,
 lastControl: null,
 playControl: null,
 delay: 3000
};

options = $.extend(true, {}, $.fn.jqiaPhotomatic.defaults, options);

options = $.extend(
 true,
 {},
 $.fn.jqiaPhotomatic.defaults,
 options,
 {
 current: 0,
 $thumbnails: this.filter('img')
 }
);

function showPhoto(options, index) {
  $(options.photoElement).attr(
    'src', options.transformer(options.$thumbnails[index].src)
  );
  options.current = index;
}

options.$thumbnails.click(function() {
  showPhoto(options, options.$thumbnails.index(this));
});

$(options.photoElement + ', ' + options.nextControl).click(function() {
 showPhoto(options, (options.current + 1) % options.$thumbnails.length);
});

$(options.previousControl).click(function() {
 showPhoto(
 options,
 options.current === 0 ?
 options.$thumbnails.length - 1 :
 options.current - 1
 );
});
$(options.firstControl).click(function() {
 showPhoto(options, 0);
}).triggerHandler('click');
$(options.lastControl).click(function() {
 showPhoto(options, options.$thumbnails.length - 1);
});

var tick;
$(options.playControl).click(function() {
 var $this = $(this);
 if ($this.attr('src').indexOf('play') !== -1) {
 tick = window.setInterval(
 function() {
 $(options.nextControl).triggerHandler('click');
 },
 options.delay
 );
 $this.attr(
 'src',
 $this.attr('src').replace('play', 'pause')
 );
 } else {
 window.clearInterval(tick);
 $this.attr(
 'src',
 $this.attr('src').replace('pause', 'play')
 );
 }
});

12.5 Writing custom utility functions

$.say = function(what) {
  alert('I say ' + what);
};

12.5.1 Writing a date formatter

$.formatDate(date, pattern)
Parameters
date (Date)
pattern (String)
Returns
The formatted date.

12.6 Summary