How to Ruin a jQuery Plug-in: Markup

Tristan Dunn

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.
      $(this).append(options.html);

      // 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> \
    </div>'
  };
})(jQuery);

Plug-in Usage

$('#content').awesomeMagic({
  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?

About thoughtbot

We've been helping engineering teams deliver exceptional products for over 20 years. Our designers, developers, and product managers work closely with teams to solve your toughest software challenges through collaborative design and development. Learn more about us.