Jquery Style guide (https://github.com/cowboy/talks/blob/master/jquery-plugin-authoring.js)

jquery.plugin.js

// ===========================================================================
// About Me.
// ===========================================================================

var cowboy = {
  name:      "Ben Alman",
  url:       "http://benalman.com/",
  twitter:   "@cowboy",
  github:    "cowboy",

  work: {
    name:    ["     __                                           ",
              "    |  |--..-----..-----..-----..--.--..-----.    ",
              "    |  _  ||  _  ||  ___||  _  ||  |  ||  _  |    ",
              "    |_____||_____||_____||_____||_____||   __|    ",
              "                                       |__|       "].join("\n"),
    title:   "Director of Pluginization",
    url:     "http://bocoup.com/",
    twitter: "@bocoup"
  },

  plugins:   ["BBQ", "doTimeout", "equalizeBottoms", "getObject", "Star Wipe",
              "hashchange event", "Tiny Pub/Sub", "throttle / debounce", "iff",
              "longUrl", "cond", "Message Queuing", "Random", "outside events",
              "postMessage", "replaceText", "resize event", "Untils", "unwrap",
              "URL Utils", "urlInternal", "loadAdScript", "Floating Scrollbar",
              "deparam", "infiniteScroller", "scrollinout event", "Sphere 3D",
              "Farthest Decendant", "Data+", "Detach+", "oneOnly", "queueFn",
              "Widget Bootstrap", ":scrollable selector", "liveOne", "each2",
              "bindAndTrigger", "isjQuery", ":attached, :detached selectors",
              "queueFn", "htmlDoc", "nodetype filter", "seq", "getUniqueClass",
              "getClassData", "sortObject", "selectColorize", "viewportOffset",
              "serializeObject", ":nth-last-child selector"],

  articles:  ["The \"catch\" with try-catch",
              "Immediately-Invoked Function Expression (IIFE)",
              "Schrecklichwissen: Terrible Knowledge",
              "Partial Application in JavaScript",
              "Cooking BBQ: the original recipe",
              "jQuery special events",
              "There's no such thing as a \"JSON Object\"",
              "On licensing my code",
              "John Resig: JavaScript's Chuck Norris",
              "The Mysterious Firefox setTimeout \"Lateness\" argument™"]
};

// FWIW
cowboy.plugins.length // 50

// Feel free to "tag along": http://bit.ly/jq-plugin-authoring-talk






// ===========================================================================
// What's a jQuery Plugin?
// ===========================================================================

// Note to self: talk about this for 30 seconds. Try not to ramble.

// This is not a jQuery plugin. Sure, it uses jQuery.. but it doesn't feel
// jQuery-like.
function setHref(elems, href) {
  elems.prop("href", href);
};

setHref($("a"), "/super-lame"); // AWKWARD


// Now this, on the other hand...
jQuery.fn.href = function(href) {
  return this.prop("href", href);
};

$("a").href("/super-awesome"); // AWESOME


// Which is doubly awesome, because it saves us, like, eight characters:
$("a").prop("href", "/super-awesome"); // SLIGHTLY LESS AWESOME






// ===========================================================================
// IIFE = Immediately Invoked Function Expression
// ===========================================================================

// Function Declaration.
function foo(a) { console.log("foo " + a); }
foo(1); // logs "foo 1"

// Function Expression.
var bar = function(a) { console.log("bar " + a); };
bar(2); // logs "bar 2"


// Without the parens, the IIFE is broken.
function(a) { console.log("broken " + a); }(3); // SyntaxError

// But with the parens, the IIFE works.
(function(a) { console.log("awesome " + a); }(4)); // logs "awesome 4"


// The "jQuery plugin" IIFE
(function($) {
  // Vars and functions are local to the IIFE.
  var myLocalVar = "plugin";
  function myLocalFunction() {
    return "my " + myLocalVar;
  }

  // A "static" jQuery method.
  $.myPlugin = function(isWhat) {
    return myLocalFunction() + " is " + isWhat;
  };

  // A "jQuery object" method.
  $.fn.myPlugin = function(isWhat) {
    return this.html($.myPlugin(isWhat));
  };
}(jQuery));

// These variables are private, and don't clutter up the global scope:
myLocalVar      // ReferenceError
myLocalFunction // ReferenceError

// But the jQuery plugin methods works just fine:
$.myPlugin("awesome") // "my plugin is awesome"



// What are the alternatives to using an IIFE?

// You could just use `jQuery` everywhere, instead of `$`.
jQuery.fn.myplugin = function(val) {
  if (jQuery.isFunction(val)) {
    // Do something.
  } else if (jQuery.isArray(val)) {
    // Do something else.
  }
};

// Why not just use `$`? Because if the plugin user had to use $.noConflict()
// to get jQuery to work with MooTools, congratulations. You've just created
// a MooTools plugin.
$.fn.myplugin = function() {
  // MooTools probably doesn't have $.fn anyways.
};

// Also, if you're not inside an IIFE, all your vars are global.
var myLocalVar = "This is really a global var";

// I've written a whole article about IIFEs. Read it.
// http://bit.ly/js-iife






// ===========================================================================
// What's `this` Inside a "jQuery Object" Method?
// ===========================================================================

(function($) {

  // Inside a "jQuery object" method:
  $.fn.test = function() {
    // this === the jQuery object.
  };

  $("div").test(); // Inside the "test" function, this === $("div")

  // Not to be confused with:

  // Inside an each callback (or map, or filter, or event handler, etc):
  $("div").each(function() {
    // this === the DOM element, as jQuery iterates over selected elements.
  });

}(jQuery));






// ===========================================================================
// Chainable Methods
// ===========================================================================

(function($) {

  $.fn.href = function(href) {
    this.prop("href", href);
  };

  $("a").href("/test"); // This works.
  $("a").href("/test").addClass("not-gonna-work"); // TypeError, whoops!

  // Why? Because, in JavaScript, functions return `undefined` unless you
  // explicitly return a value.


  // Also, while we're talking about using jQuery methods in your plugin,
  // NEVER EVER EVER use undocumented (private) jQuery methods or properties
  // in your plugin. Why? Because that stuff has a long history of always
  // getting changed when you're least able to update your code, which makes
  // your plugin users all kinds of :'-( THIS EMOTICON IS CRYING

}(jQuery));


// So, how do we chain?

(function($) {

  $.fn.href = function(href) {
    this.prop("href", href);
    return this; // returning `this` makes any method chainable!
  };

  $("a").href("/test"); // This still works.
  $("a").href("/test").addClass("gonna-work"); // Much better!

  // Here's the crazy part. Because the jQuery#prop method is chainable when
  // used as a setter, you can do this.
  $.fn.href = function(href) {
    return this.prop("href", href); // MIND = BLOWN
  };

}(jQuery));






// ===========================================================================
// Implicit (and Explicit) Iteration
// ===========================================================================

(function($) {

  // We all know this, right?
  $("li").html("hello world"); // Set the HTML of every selected element.
  $("li").html() // "hello world" (get the HTML of first selected element).

  // But what's the problem with this? (besides the fact that I haven't saved
  // a reference to the jQuery object in a variable, which we all know is bad)
  $("li").html($("li").html() + "!!!");


  // We can solve this problem in a few ways:

  // This is the preferred way (since jQuery 1.4).
  $("li").html(function(index, currentHtml) {
    return currentHtml + "!!!";
  });

  // This is the explicit way, using jQuery#each.
  $("li").each(function() {
    var elem = $(this);
    elem.html(elem.html() + "!!!");
  });


  // jQuery plugins need to explicitly iterate, so users don't have to!

  // This plugin works with 0 or 1 elements, but...
  $.fn.yell = function() {
    return this.html(this.html() + "!!!");
  };

  $("li").yell(); // ...2 or more P elements? Whoops.


  // This is much better. It works with 0, 1, or any number of elements.
  // Of course, I should probably have just used the "preferred" way, but I
  // wanted to make my point. Iterate with jQuery#each in your plugin.
  $.fn.yell = function() {
    return this.each(function() {
      var elem = $(this);
      elem.html(elem.html() + "!!!");
    });
  };

  $("li").yell(); // Works just like you (and your plugin's users) expect.

}(jQuery));


// Here's a general-purpose template. Modify as-necessary.

(function($) {

  $.fn.myPlugin = function() {
    return this.each(function() {
      // Your per-element code goes here!
    });
  };

}(jQuery));






// ===========================================================================
// Getters & Setters
// ===========================================================================

(function($) {

  // This works as both getter and setter, because a built-in jQuery method
  // is used internally.
  $.fn.href = function(href) {
    return this.prop("href", href);
  };

  $("a").href("/test"); // Set property of every selected element (and chain).
  $("a").href()         // "/test" (get property of first selected element).


  // What if our core logic couldn't just use a built-in jQuery method?
  $.fn.href = function(href) {
    if (href == null) {
      // No arguments was passed (getter). Return the current href property
      // of the first selected element.
      return this.get(0).href;
    } else {
      // An argument was passed (setter). Set the current href property of all
      // selected elements and return the jQuery object, allowing chaining.
      return this.each(function() {
        this.href = href;
      });
    }
  };

  // FWIW, testing `val == null` is equivalent to testing `val === null ||
  // val === undefined`. In general, I *strongly recommend* against using the
  // == operator, because it does type coercion. But it's super-convenient
  // for testing to see if a value is either null or undefined. So, in this
  // case, it's ok. There are articles about this. JSHint has an "eqnull"
  // setting just for this. But use === otherwise.

}(jQuery));






// ===========================================================================
// Creating .end()-able Traversal & Filtering Methods
// ===========================================================================

(function($) {

  // Have you ever used the jQuery#end method?
  $("ul").children().addClass("li").end().addClass("ul");


  // So, how do you create your own .end()-able method?

  // If you're using a jQuery method internally, it's easy.
  $.fn.spans = function() {
    return this.find("span");
  };

  // Awesome!
  $("div").spans().addClass("span").end().addClass("div");


  // But what if things get a little more.. complicated? Note: Andrew Wirick
  // (aka @amwirick) came up with this plugin scenario. Thanks, Andrew!
  $.fn.cousins = function() {
    return this.parent().siblings().children();
  };

  // Whoops! jQuery#end only reverts to the previous set.
  $("li:eq(0)").cousins().addClass("cousin").end().addClass("aunt-or-uncle");


  // Let's do this the right way, using jQuery.pushStack.
  $.fn.cousins = function() {
    return this.pushStack(this.parent().siblings().children());
  };

  // Much better.
  $("li:eq(0)").cousins().addClass("cousin").end().addClass("li");


  // jQuery#pushStack supports a few more options. Check out the API docs
  // and jQuery source for more info.
  // http://api.jquery.com/pushStack/
  // http://bit.ly/jqsource

}(jQuery));






// ===========================================================================
// A Few Other .end()-able Method Patterns.
// ===========================================================================

(function($) {

  // Filter the current set of nodes down to just text nodes.
  $.fn.textNodes = function() {
    return this.filter(function() {
      return this.nodeType === Node.TEXT_NODE;
    });
  };

  $("li").contents().textNodes(); // Works!


  // Traverse from the current set of elements.
  $.fn.firstChildren = function() {
    return this.map(function() {
      // Add some DOM element or array of DOM elements to the result set.
      return this.firstChild;
    });
  };

  $("ul").firstChildren(); // Note: Might return textNodes.


  // For this method, jQuery#pushStack would have been a better choice.
  $.fn.cousins = function() {
    return this.map(function() {
      return $(this).parent().siblings().children().get();
    });
  };

})(jQuery);






// ===========================================================================
// Namespacing Your Plugin
// ===========================================================================

(function($) {

  // For "static" jQuery methods, this works wonderfully:

  $.myPlugin = function() {
    // Your code goes here.
  };

  $.myPlugin.submethod = function() {
    // Your code goes here.
  };

  $.myPlugin(); // This will work.
  $.myPlugin.submethod(); // So will this.


  // For "jQuery object" methods, this DOES NOT WORK WONDERFULLY:

  $.fn.myPlugin = function() {
    // Your code goes here.
  };

  $.fn.myPlugin.submethod = function() {
    // Your code goes here.
  };

  $("li").myPlugin(); // Works great.
  $("li").myPlugin.submethod(); // Not so great.

  // Why does it fail? Think about it. What's `this` inside submethod?


  // You can write a lot of code (believe me, I've tried) to make this kind of
  // thing work, but while it's technically possible, it's confusing. Just try
  // to keep track of chaining and .end(). Good times.
  $("li").myPlugin().submethod();


  // For basic "jQuery object" methods, this is usually sufficient.
  $.fn.myPlugin = function() {
    // Your code goes here.
  };

  $.fn.myPluginSubmethod = function() {
    // Your code goes here.
  };

  $("li").myPlugin(); // Works great.
  $("li").myPluginSubmethod(); // Also works great.


  // You can, of course, just use the jQuery UI Widget Factory to make a
  // stateful plugin with submethods, events and more. Read more here:
  // http://ajpiano.com/widgetfactory/
  // http://blog.nemikor.com/2010/05/15/building-stateful-jquery-plugins/
  $("li").myPlugin("submethod", options);

}(jQuery));






// ===========================================================================
// Custom Selectors
// ===========================================================================

(function($) {

  // Test if an element is in the DOM.
  $.expr.filters.attached = function(elem) {
    return $.contains(document.documentElement, elem);
  };

  $("div").is(":attached")          // true
  $("div").detach().is(":attached") // false
  $("<div/>").is(":attached")       // false


  // How about a detached selector?
  $.expr.filters.detached = function(elem) {
    return !$.contains(document.documentElement, elem);
  };

  $("div").is(":detached")          // false
  $("div").detach().is(":detached") // true
  $("<div/>").is(":detached")       // true


  // Now let's organize this code and DRY it up a bit.
  $.extend($.expr.filters, {
    attached: function(elem) {
      return $.contains(document.documentElement, elem);
    },
    detached: function(elem) {
      return !$.expr.filters.attached(elem);
    }
  });


  // You can also pass arguments to selectors, match[3] is that value.
  $.expr.filters.hasdata = function(elem, i, match) {
    // Has data been stored on the element?
    var hasData = $.hasData(elem);
    if (match[3] == null) {
      // If no argument was passed to :hasdata, just return true or false
      // based on whether or not data has been stored on the element.
      return hasData;
    } else {
      // If an argument was passed to :hasdata(), return true if argument is
      // a property of the data object.
      return hasData && match[3] in $(elem).data();
    }
  };

  $("p:hasdata").length           // 0
  $("p:first").data("foo", 123);
  $("p:hasdata").length           // 1
  $("p:hasdata(foo)").length      // 1
  $("p:hasdata(bar)").length      // 0


  // Note: you might also see $.expr[":"] used in custom selectors. It's
  // just another reference to the $.expr.filters object. See the jQuery
  // source if you don't believe me! http://bit.ly/jqsource

}(jQuery));






// ===========================================================================
// Extending Default Options
// ===========================================================================

(function($) {

  // If your plugin only has one option, handling defaults is easy.
  $.fn.colorize = function(color) {
    return this.css("color", color || "black");
  };

  $("p").colorize();        // black!
  $("p").colorize("green"); // green!


  // When you start to have more optional arguments, things can get messy:

  $.fn.colorizeAndOrSetWidth = function(color, width) {
    // If `width` was passed, but `color` was not, shuffle argument values.
    if (typeof color === "number") {
      width = color;
      color = null;
    }
    // Set arguments to default values if necessary.
    if (color == null) { color = "red"; }
    if (width == null) { width = 100; }
    // Now we can finally, actually, do stuff.
    return this.css("color", color).width(width);
  };


  // And what about accepting a string width value like "1em"? How do you
  // know if a string or a width was passed? You don't.


  // Let's use default options:

  var defaults = {color: "red", width: 100};

  $.fn.colorizeAndOrSetWidth = function(options) {
    // Copy defaults and then the passed options into an empty object, then
    // set the result into options, thus updating it.
    options = $.extend({}, defaults, options);
    // Now do stuff.
    return this.css("color", options.color).width(options.width);
  };


  // You can also expose the defaults so they can be changed by the user:

  $.fn.colorizeAndOrSetWidth = function(options) {
    // Copy defaults and then the passed options into an empty object, then
    // set the result into options, thus updating it.
    options = $.extend({}, $.fn.colorizeAndOrSetWidth.options, options);
    // Now do stuff.
    return this.css("color", options.color).width(options.width);
  };

  // Expose default options.
  $.fn.colorizeAndOrSetWidth.options = {color: "red", width: 100};

}(jQuery));






// ===========================================================================
// What Shouldn't be a jQuery Plugin
// ===========================================================================

// Why shouldn't this be a jQuery plugin? Because this code has nothing to do
// with jQuery. It's just JavaScript. Don't attach arbitrary methods to jQuery
// unless they're REALLY jQuery plugins.
(function($) {
  var startDate;

  $.timer = {
    start: function() {
      startDate = new Date();
    },
    elapsed: function() {
      return new Date() - startDate;
    }
  };
}(jQuery));

$.timer.start();
// wait one second
$.timer.elapsed(); // 1000


// Use this structure when creating timer.js, and you'll get a global timer
// object with two functions.
(function(exports) {
  var startDate;

  exports.timer = {
    start: function() {
      startDate = new Date();
    },
    elapsed: function() {
      return new Date() - startDate;
    }
  };
}(typeof exports === "object" && exports || this));

timer.start();
// wait one second
timer.elapsed(); // 1000


// Don't like globals? Me neither. Just do something like this before
// including the timer.js module:

this.exports = Bocoup.utils;
// << Include timer.js here! >>
Bocoup.utils.timer.start();
Bocoup.utils.timer.elapsed(); // 1000 (etc)

// And no new globals have been introduced.
window.timer // undefined


// Or just use a script loader! This non-jQuery-specific timer.js will work
// in Node.js, RequireJS and curl.js (there's a config option for it).

// Per John Hann (aka @unscriptable), "As long as the AMD loader can auto-wrap
// CommonJS modules in a define(), it's all good."





// ===========================================================================
// Using grunt
// ===========================================================================

// The website (coming soon)
// http://gruntjs.com/

// A jQuery Plugin with Grunt & QUnit
// http://javascriptplayground.com/blog/2012/04/a-jquery-plugin-with-grunt-qunit

// Grunt: Let's create a jQuery plugin!
// http://codestre.am/c87f9daa6ec5df92dbc6edfc8





// ===========================================================================
// jQuery Plugins Index package.json
// ===========================================================================

// Still under development, actually. Check this out for the latest info:
// https://github.com/jquery/plugins.jquery.com/blob/master/docs/package.md