wintoni.us

The Pug King

Sat, 18 Jul 2009 17:35:26 -0700

The Pug King

jQuery Plugin Patterns

Sat, 13 Jun 2009 12:50:00 -0700

// Simplest plugin ever

(function($) {
  $.myPlugin = function() {};
})(jQuery);


// Two ways to call it

jQuery.myPlugin();

jQuery(function($) {
  $.myPlugin();
});

With the realization that jQuery gives you no more than this basic structure to write fat, complex plugins, the youthful sense of exploration that brought you to jQuery quickly evaporates into an empty void of nothingness. You google “jQuery plugin tutorial” and ask yourself, “How is this better than ’s class helpers?” Your head feels strangely pressurized. “And how would I test…” Your brain explodes, Scanners-style, without even an understanding of the question you are about to ask. The very moment your brain begins to disentigrate, you realize that you never were alive to begin with; your existence was simply a predetermined, predictable set of events. The question of God is, and always was, irrelevant. The revelation itself is unimportant and unnoticed. You cease to exist.

OK, so that is the worst case scenario, albeit surprisingly frequent and plausable :). I am going to show you that using pure javascript to write your plugins is not only easier to read and comprehend, but extremely powerful. And then I’m going to show you how to test your plugins using qUnit.

Here is quick guide to the “class” structure I will discuss, for you programmer types:

(function($) {

  // Private class variable
  var a;

  // Private class method
  function doSomething() {}

  // Public class method
  $.myPlugin = function() {

    // Private instance variable
    var b;

    doSomething();
    doSomethingElse();

    // Private instance method
    function doSomethingElse() {}
  };
})(jQuery);

Before writing a real world plugin, let’s define a strategy for calling jQuery plugins.

jQuery plugins are usually accessed through a single public method. Often times, with more complex plugins, you will want to specify an action to take (play, pause, or stop, for example). You may also want to pass in any number of options to modify the plugin’s functionality or to specify event callbacks.

Given the requirements, this seems like a pretty versatile way to call a plugin:

$.myPlugin({ option: false })
// or
$.myPlugin('action', { option: false });

The implementation:

(function($) {
  var defaults = { option: true };
  var options;

  $.myPlugin = function(action, new_options) {
    if (typeof(action) == 'object') {
      new_options = action;
      action = 'initialize';
    }
    setOptions(new_options);
    // Do something
    // if (action == 'initialize')
    return options;
  };

  function setOptions(new_options) {
    options = $.extend({}, defaults, options, new_options);
  }
})(jQuery);

The options variable maintains state across multiple myPlugin calls. If myPlugin is called without options, the options variable will equal the defaults variable. If options are specified, they are merged with the default options. If myPlugin is called once again with options, those options will be merged with the previous options, and so on.

Now that you know how to handle basic options, let’s specify an event callback as well:

$.myPlugin({
  option: false,
  event: function() {}
})
// or
$.myPlugin('action', {
  option: false,
  event: function() {}
});

The implementation:

(function($) {
  var defaults = { option: true };
  var events = $({});
  var options;

  $.myPlugin = function(action, new_options) {
    if (typeof(action) == 'object') {
      new_options = action;
      action = 'initialize';
    }
    setOptions(new_options);
    // Do something
    // if (action == 'initialize')
    //   events.trigger('event');
    return options;
  };

  function setOptions(new_options) {
    $.each(new_options, function(event, fn) {
      if (typeof(fn) == 'function') {
        events.unbind(event);
        events.bind(event, fn);
      }
    });
    options = $.extend({}, defaults, options, new_options);
  }
})(jQuery);

The setOptions method detects when an option is a function. If so, it binds that event to an empty jQuery object.

Let’s harness the real power of jQuery by allowing access to the plugin via element collections:

// Simplest element-based plugin ever

(function($) {
  $.fn.myPlugin = function() {
    return this;
  };
})(jQuery);

// Two ways to call it

jQuery('#id').myPlugin();

jQuery(function($) {
  $('#id').myPlugin();
});

The jQuery object has a special fn object that you can assign functions to. Any function attached to fn will also be available to jQuery element collections.

The new plugin call:

$('#id').myPlugin({ option: false });
// or
$('#id').myPlugin('action', { option: false });

Handling plugin options is a bit different when you involve element collections. Your plugin acts on each individual element, and therefore must maintain state for each element separately.

The implementation:

(function($) {
  var defaults = { option: true };

  $.fn.myPlugin = function(action, options) {
    if (typeof(action) == 'object') {
      options = action;
      action = 'initialize';
    }
    
    this.each(function(el) {
      el = $(this);
      setOptions(el);
      // Do something
      // if (action == 'initialize')
    });

    function setOptions(el) {
      options = $.extend({}, defaults, el.data('my_plugin:options'), options);
      el.data('my_plugin:options', options);
    };

    return this;
  };
})(jQuery);

Here we use jQuery’s data store to associate options with each individual element.

A plugin call with an event callback:

$('#id').myPlugin({
  option: false,
  event: function() {}
});
// or
$('#id').myPlugin('action', {
  option: false,
  event: function() {}
});

The implementation:

(function($) {
  var defaults = { option: true };

  $.fn.myPlugin = function(action, options) {
    if (typeof(action) == 'object') {
      new_options = action;
      action = 'initialize';
    }
    
    this.each(function(el) {
      el = $(this);
      el.trigger('event');
      setOptions(el);
      // Do something
      // if (action == 'initialize')
    });

    function setOptions(el) {
      $.each(options, function(event, fn) {
        if (typeof(fn) == 'function') {
          el.unbind(event);
          el.bind(event, fn);
        }
      });
      options = $.extend({}, defaults, el.data('my_plugin:options'), options);
      el.data('my_plugin:options', options);
    };

    return this;
  };
})(jQuery);

As with options, events are attached to the element instead of maintaining state through a class variable.

Finally, let’s take a look at testing this plugin structure using qUnit. The implementation:

(function($) {
  var defaults = { option: false };

  $.fn.myPlugin = function(action, options) {
    if (typeof(action) == 'object') {
      options = action;
      action = 'initialize';
    }
    
    this.each(function(el) {
      el = $(this);
      setOptions(el);
      // Do something
      // if (action == 'initialize')
      el.trigger('test_each', {
        functions: { setOptions: setOptions },
        variables: { defaults: defaults, options: options }
      });
    });

    function setOptions(el) {
      options = $.extend({}, defaults, el.data('my_plugin:options'), options);
      el.data('my_plugin:options', options);
    };

    return this;
  };
})(jQuery);

Here we use a “test_each” event to provide context for the tests. Events allow you to test private variables and functions, eliminating the need for thinking about accessibility all the time. It also eliminates the need for having “this” everywhere and generally making the javascript ugly.

Here is how we might test the last example:

jQuery(function($) {
  var functions, variables;

  function setup() {
    var accessor = $('#id').myPlugin({
      option: true,
      test_each: function(event, accessor) {
        functions = accessor.functions;
        variables = accessor.variables;
      }
    });
  }

  module('setOptions', { setup: setup });
  test('should extend the default options if options specified', function() {
    equals(variables.options.option, true);
  });
  test('should assign default options if no options specified', function() {
    $('#id').data('my_plugin:options', null).myPlugin();
    equals($('#id').data('my_plugin:options'), variables.defaults);
  });
  test('should store options in the data store', function() {
    equals($('#id').data('my_plugin:options'), variables.options);
  });
});

And finally, the HTML to execute the test:



  
  
  
  
  
  jquery.my_plugin



  jquery.my_plugin

Learn more about qUnit here.

Personally, this way of doing things has reinvigorated my curiosity towards jQuery. Most of all, it has dispelled my worries about jQuery only being a tool for designers. Let me know if you guys find an even cleaner way to execute and test complex objects.

Git Externals

Mon, 27 Apr 2009 22:38:00 -0700

We were having trouble figuring out the best way to handle our application’s external git dependencies at Bleacher Report. We wanted to be able to “freeze” externals to simplify project setup and deployment. We also wanted our developers to be able to quickly unfreeze externals, work on them, and freeze them back.

Submodules and cached_externals did not fit those requirements. I really like giternal, which works well (and has a way cool name), but I don’t like how it shares a single gzipped .git snapshot across all users on a repository. I also think it could be made simpler in some areas. Many thanks to Pat Maddox for getting the ball rolling.

Introducing externals. Let’s install the gem.

Terminal:

gem sources -a http://gems.github.com
sudo gem install winton-externals

Create a configuration file.

my_repo/config/externals.yml or
my_repo/.externals.yml:

rails:
  repo: git://github.com/rails/rails.git
  path: vendor

Freeze Rails into your repository.

cd my_repo
externals freeze

You should see a frozen copy of Rails in your vendor directory. Now you can commit to your parent repository like normal.

git add .
git commit -m "Freezing Rails"
git push origin master

When you unfreeze an external, it becomes its own repository again. Let’s pull the latest changes from the Rails repository.

externals unfreeze
cd vendor/rails
git pull origin master
cd ../../
externals freeze

You can also freeze and unfreeze specific externals using a regular expression match.

This would also freeze rails:

externals freeze ra

In case you can’t remember the freeze state of your externals:

externals status

And last but not least, some nifty shortcuts:

externals st # status
externals fr # freeze
externals un # unfreeze

An additional thanks to Tung Nguyen for helping me get this to 1.0.0 and ovoice for updating the wiki.

More details on the externals GitHub page.

Kicking myself for not bringing up some terminals to further...

Fri, 17 Apr 2009 17:58:00 -0700

Kicking myself for not bringing up some terminals to further exemplify my 1337ness.

Its usually pretty easy to tell what Henry is thinking about.

Sat, 11 Apr 2009 17:53:00 -0700

Its usually pretty easy to tell what Henry is thinking about.

Today in Golden Gate Park I encountered a wild Henry. I was...

Sat, 21 Mar 2009 14:50:00 -0700

Today in Golden Gate Park I encountered a wild Henry. I was attacked and mauled.

RubyMachine

Sat, 21 Mar 2009 01:13:00 -0700

This is the first in my “rambling about ideas I don’t have the time to create, but want to take credit for if someone makes it” series. My first entry is about an idea I am calling RubyMachine, a Ruby platform for novices to create and deploy web applications.

Rails is not easy. Yes, to people who do this stuff for a living, Rails is easy in the sense that everything before it sucked. But its not PHP easy, not “takes your nephew an hour to learn” easy. I want a Ruby web framework with a directory structure a child can understand:

index.haml
index.rb
about/
  me.erb
  me.rb
  _interests.markdown

Every file pairing consists of a markup file and an optional Ruby companion script. The companion script contains non-classed Ruby code with access to a query string hash and a database via DataMapper. Routes resemble the file paths (without extensions). Partials are underscored and cannot be accessed externally.

Locally, install the gem, run rubymachine in your project’s home directory, and your development server starts. When you’re ready to publish, visit rubymachine.com and deploy your project straight from a GitHub repository to your own dedicated server for a low monthly price (kaching).

I realize that I’m skipping a few details like layouts, plugins, and rendering partials. However, with these basic guidelines, I think this could be a cool way to get Ruby and web development out to a broader audience.

Somebody watching me pretend to be someone I once saw getting...

Thu, 19 Mar 2009 23:02:00 -0700

Somebody watching me pretend to be someone I once saw getting their picture taken with hipster glasses on. If the shoe.

Ubistrano on Rails Envy

Mon, 16 Mar 2009 00:56:00 -0700

I am thankful to have received a brief plug last Friday from Jason Seifer on Rails Envy Podcast #70. Hosting along side Obie Fernandez, he briefly mentioned my server provisioning tool, Ubistrano, and got me a few more watchers on GitHub.

Ubistrano came about primarily because I did not want to learn Puppet’s (ugly) proprietary scripting language. Sprinkle has great promise, but at the time was short on examples and had no stable versioning in place. It made the most sense to throw together some helper methods and write the provisioning process myself. I think it is still the quickest way to get rolling without having to cobble together recipes from random places. However, you are restricted to my very specific server stack.

I am writing this to outline my view of Ubistrano 2.0, which will probably be released under a different name. Firstly, I want to eliminate Capistrano altogether. I want everything to be run from a binary on the target machine (i.e. ubistrano apache:install). Using this binary you can run automated tasks written in a nice Ruby DSL. The DSL handles things like:

Building and installing binaries
Piping STDIN/STDOUT to and from other processes
Adding and removing strings from files
Creating a cohesive install process (return where you left off)

…and anything else you need to provision a system. The solution I am describing becomes more of a generic automation tool, one that you could also use to install the latest version of Git, manage a project’s externals, upload SSH keys, and other local tasks. Ideally these tasks could be packaged as gems for quick installation to a target system.

So far I’m looking into Ropen and HighLine to do the heavy lifting for me. Other than the DSL and task execution process, I want to keep this thing light. Suggestions welcomed.