How to Ruin a jQuery Plug-in: Markup

jQuery is one of my favorite libraries, in any language. And one of the greatest advantages of using jQuery is the abundance of third-party plug-ins available. Just about anything you need to do has probably already been done and extracted into a plug-in. That being said there are ways I feel you can completely ruin a jQuery plug-in.

Generating or expecting specific markup

Recently I needed a content slider for an existing homepage design. The first promising plug-in I found generated the navigation for you, so it was out the door. Several others expected very specific markup and made it difficult to customize. Eventually I found one that at least allowed me to customize the selectors and even though it still expected <li> elements I managed to easily modify it to work.

Proposed Solution

If you are going to generate markup from your plug-in, make it customizable. It is trivial to add another string to your default options and makes it a lot easier to find. If you need to act on the markup, which you will, then base it on an ID, or class names, and not elements.

Example Plug-in

Here’s a very basic plug-in to give you an idea what I am talking about.

(function($) {
  $.fn.awesomeMagic = function(options) {
    // Overwrite the defaults with any provided options.
    options = $.extend(true, {}, $.fn.awesomeMagic.defaults, options || {});

    return $(this).each(function() {
      // Append the markup.

      // Grab the elements needed.
      var hat    = $(this).find('.awesome-magic-hat');
      var rabbit = $(this).find('.awesome-magic-rabbit');

      // Perform awesome magic here.

  $.fn.awesomeMagic.defaults = {
    wand : true,
    html : '\
    <div class="awesome-magic-hat"> \
      <div class="awesome-magic-rabbit"> \
        Rabbit goes here. \
      </div> \

Plug-in Usage

  html : '\
    <span class="awesome-magic-rabbit">Rabbit goes here.</span> \
    <span class="awesome-magic-hat" />'

How do you handle custom or expected mark up in your plug-ins? What are other ways you feel a plug-in can be ruined?