Sub createlist()
    Dim source As Range
    Set source = Range("B2:D4")
    Dim dest As Range
    Set dest = Range("F1")
    dest.Range("A1:C1").Value = Array("When", "What", "Who")
    Dim target As Range
    Dim c As Range
    For Each c In source.Cells
        If Not IsEmpty(c.Value) Then
            If IsEmpty(dest.Range("A2").Value) Then
                Set target = dest.Range("A2")
            Else
                Set target = dest.End(xlDown).Range("A2")
            End If
            target.Range("C1").Formula = "=" & c.Address
            target.Range("B1").Formula = "=" & c.EntireRow.Range("A1").Address ' row header
            target.Range("A1").Formula = "=" & c.EntireColumn.Range("A1").Address ' column header
        End If
    Next c
End Sub

The key tricks was getting column/row headers with .EntireColumn/Row.Range("A1"), and appending to the end of a list with .End(xlDown).Range("A2"). Unfortunately, End(xlDown) is too clever; if the region contains only one item (like the column header only), it goes all the way to the end of the spreadsheet and the .Range("A2"), which should get the next line, throws an error. Hence the If IsEmpty(dest.Range("A2").Value) Then.

The If Not IsEmpty(c.Value) Then line allows for blank spots in the original table to be ignored. VBA doesn't have a Continue statement, just an equivalent for break, called Exit For.]]> http://youngisrael-stl.org/wordpress/2008/10/23/turning-a-table-into-a-list-in-excel/feed/ http://youngisrael-stl.org/wordpress/2008/10/23/changes/ http://youngisrael-stl.org/wordpress/2008/10/23/changes/#comments Fri, 24 Oct 2008 04:25:02 +0000 Danny http://youngisrael-stl.org/wordpress/?p=155 Barthelme; very simple and elegant. Removed the Chili code highlighting line-numbering, which only worked intermittently, tended to get lost in the margins of the <pre> elements, and didn't add much.]]> http://youngisrael-stl.org/wordpress/2008/10/23/changes/feed/ http://youngisrael-stl.org/wordpress/2008/08/29/making-metadata-extensible/ http://youngisrael-stl.org/wordpress/2008/08/29/making-metadata-extensible/#comments Fri, 29 Aug 2008 07:20:59 +0000 Danny http://youngisrael-stl.org/wordpress/?p=108

Metadata

I put the idea that the metadata plugin should be extensible out on the jquery discussion group, but it got no attention, so I'm documenting it here.

Metadata is information about a DOM element that isn't part of the actual text; e.g. you mention New York City and somehow associate the coordinates [40.783, -73.967] with that. Scripts can use that information to add to the user experience; in this case, you could point the city out on a map.

There are two reasons to use metadata, for good or for evil:

1. For good: the metadata is semantic, related to the actual information present on the page and the metadata helps build the semantic web.
2. For evil: as a way of mixing behavior and presentation in the semantic markup. In this sense, in-line style statements and class="draggable" sorts of things are metadata.

I'm obviously being tongue-in-cheek here; mixing presentation and markup isn't really evil. Having everything on one page is both faster to write, and, for small projects, easier to understand.

The metadata plugin

The jquery metadata plugin provides a way of getting metadata out of an element and into a javascript object that you can use. obj = $('#foo').metadata() analyzes the foo element for metadata and returns it. For efficiency's sake, it stores that metadata in the jQuery cache under the key 'metadata', so $('#foo').data('metadata') will get it back again, and in fact metadata first checks for that cache and only analyzes the element if it isn't found. This means the analysis only happens once per element. The key can be changed with the single option (calling it single is a historical accident, from previous versions of metadata that used mulitple expandos on the element or combined them into one expando).

Creating metadata

The problem is that there is no standard for incorporating metadata into your markup. Lots of things have been proposed or used, like custom attributes, pre-determined classes (the microformats approach) and HTML5's data- attributes. The metadata plugin allows for three methods: custom attributes, JSON in the className, and the content of a specified child element (generally a <script> element with an unrecongnized type that will be ignored by the HTML parser). In the words of the plugin documentation, "This means that there is at least one option here that can appease you."

But that clearly isn't true. There are lots more ways to encode metadata, and there's no reason that the plugin should be limited to just three. Therefore, in the spirit of jQuery, I made it freely extensible:

The extensible metadata

$.extend({
	metadata : {
		defaults : {
			type: 'class',
			name: 'metadata',
			cre: /({.*})/,
			single: 'metadata'
		},
		setType: function( type, name ){
			this.defaults.type = type;
			this.defaults.name = name;
		},
		get: function( elem, opts ){
			var opts = $.extend({},this.defaults,opts);
			return $.data(elem, opts.single) || $.data(elem, opts.single, this[opts.type].call(elem,opts));
		},
		asJSON: function(s){
			if (!s) return {};
			if (/^[[{]/.test($.trim(s))) return eval("(" + s + ")");
			return s;
		}
	}
});

$.fn.metadata = function( opts ){
	return $.metadata.get( this[0], opts );
};

and all metadata "analyzing functions"--defined by the options.type string--take an options object and return the metadata object, with this bound to the element.

The original three

For example, the original metadata methods are:

$.metadata["class"] = function (opts){
	var m = opts.cre.exec( this.className );
	if ( m ) return $.metadata.asJSON(m[1]);
	return {};
};

$.metadata.elem = function (opts){
	var e = this.getElementsByTagName(opts.name);
	if ( e.length ) return $.metadata.asJSON(e[0].innerHTML);
	return {};
};

$.metadata.attr = function (opts){
	var attr = this.getAttribute( opts.name );
	// allow for not including the braces, as in the original metadata plugin
	if ( attr ){
		if ( attr.indexOf( '{' ) < 0 ) attr = "{" + attr + "}";
		return $.metadata.asJSON(attr);
	}
	return {};
};

Example: type 'class'

<div class="{ draggable : {axis: 'x', opacity: 0.5}} example">I have data!</div>

Example: type 'attr'

<div coords="{lat: 40, long: -90}" class="example">I have data!</div>

Example: type 'elem'

<div class="example">
<script type="text/json">{first: 1, second: 2}</script>
I have data!
</div>

Example: metaobjects

$.metadata.object = function (opts){
	var ret = {};
	$('> object.metaobject > param', this).each(function(){
		ret[this.name] = $.metadata.asJSON(this.value);
	});
	return ret;
};

<div class="example">I have data!
<object class="metaobject" style="display:none">
	<param name="Full Name" value="Danny W"/>
	<param name="Age" value="too large to count" />
</object>
</div>

Example: Microformats

$.metadata.hcard = function(opts){
	var hcards = HCard.discover(this);
	return hcards.length ? hcards[0] : {};
};

<div class="example">
  I have data from 
	<span class="vcard">
	  <span class="fn">Danny Wachsstock</span>
		at <span class="tel">555-1212</span>
	</span>!
</div>

HTML 5

$.metadata.data = function(opts){
	var ret = {};
	$.each (this.attributes, function(){
		var m = /data-(.*)/.exec(this.nodeName);
		if (m) ret[m[1]] = $.metadata.asJSON(this.nodeValue);
	});
	return ret;
};

<div data-lat="40" data-long="-90" class="example">I have data!</div>

Without further ado, here's the code (download):

// create the master widget
$.widget("ui.widget",{
	// Aspect Oriented Programming tools from Justin Palmer's article
  yield: null,
  returnValues: { },
  before: function(method, f) {
    var original = this[method];
    this[method] = function() {
      f.apply(this, arguments);
      return original.apply(this, arguments);
    };
  },
  after: function(method, f) {
    var original = this[method];
    this[method] = function() {
      this.returnValues[method] = original.apply(this, arguments);
      return f.apply(this, arguments);
    }
  },
  around: function(method, f) {
    var original = this[method];
    this[method] = function() {
      this.yield = original;
      return f.apply(this, arguments);
    }
  }
});

function object(o){
	function F(){};
	F.prototype = o;
	return new F;
}

// create a widget subclass (always in the $.ui namespace)
$.ui.widget.subclass = function subclass(name) {
	$.widget('ui.'+name); // Slightly inefficient to create a widget only to discard its prototype, but it's not too bad
	var widget = $.ui[name]; // $.widget should return the object itself!
	widget.subclass = subclass;
	var superclass = this;
	
	widget.prototype = object(this.prototype);
	arguments[0] = widget.prototype; // add the the new methods to the prototype
	$.extend.apply(null, arguments); 
	widget.defaults = object(this.defaults);
	widget.getter = this.getter;
	
	// Subtle point: we want to call superclass init and destroy if they exist
	// (otherwise the user of this function would have to keep track of all that)
	if (widget.prototype.hasOwnProperty('init')){;
	  var init = widget.prototype.init;
		widget.prototype.init = function(){
			superclass.prototype.init.apply(this);
			init.apply(this);
		}
	};
	if (widget.prototype.hasOwnProperty('destroy')){
		var destroy = widget.prototype.destroy;
		widget.prototype.destroy = function(){
			destroy.apply(this);
			superclass.prototype.destroy.apply(this);
		}
	}
	return widget; // address my complaint above
};

And here are the samples from the Extending Widgets tutorial:

//  Experiment 1
var Superbox = {
	init: function(){
		var self = this;
		this.element.click(function(){
			self.move();
		});
	},
	move: function(){
		this.element.css (this.newPoint());
	},
	newPoint: function(){
		return {top: this.distance(), left: this.distance()};
	},	
	distance: function(){
		return Math.round (Math.random()*this.getData('distance'));
	}
};
$.ui.widget.subclass ('superbox', Superbox);
$.ui.superbox.defaults = { distance: 200 };

$('#experiment1').superbox();

// Experiment 2
$.ui.superbox.subclass ('supererbox', {
	// overriding and new methods
	move: function(){
		this.element.animate(this.newPoint(), this.getData('speed'));
	},
	home: function(){
		this.element.animate({top:0, left:0}, this.getData('speed'));
	}
});
$.ui.supererbox.defaults.speed = 'normal';

$('#experiment2').supererbox();

// Experiment 3
$.ui.supererbox.subclass('superboxwithtext',  {
	move: function(){
		var count = this.getData('count') || 0;
		++count;
		this.setData('count', count);
		this.element.text('Move number '+count);
		$.ui.supererbox.prototype.move.call(this); // note that we could just as well use $.ui.superbox.move for the original, "jumpy" move
	}
});

$('#experiment3').superboxwithtext();

// Experiment 4
$.fn.pulse = function (opts){
	opts = $.extend ({}, $.fn.pulse.defaults, opts);
	for (i = 0; i < opts.times; ++i){
		this.animate({opacity: 0.1}, opts.speed).animate({opacity: 1}, opts.speed);
	}
	return this;
};
$.fn.pulse.defaults = {
	speed: 'fast',
	times: 2
};
$('#experiment4').supererbox().supererbox('before','move', function() {
	this.element.pulse();
});

// Experiment 5
$('#experiment5').supererbox().supererbox('around','move', function() {
	this.element.pulse();
	this.yield();
	this.element.pulse();
});

	$('div.test input:button').click(function(){
		$('.output').sendkeys($('div.test input:text').val());
	});
	$('.phonepad input').click(function(){
		$('.output').sendkeys(this.name || this.value);
	});

<div>
<textarea class="output"></textarea>
<br/>
<input type="text" class="output" />
<div class="phonepad"><input type="button" name="{leftarrow}" value="&larr;"/><input type="button" name="{rightarrow}" value="&rarr;"/><input type="button" name="{backspace}" value="BS"/><input type="button" value="7" /><input type="button" value="8" /><input type="button" value="9" /><input type="button" value="4" /><input type="button" value="5" /><input type="button" value="6" /><input type="button" value="1" /><input type="button" value="2" /><input type="button" value="3" /><input type="button" value="*" /><input type="button" value="0" /><input type="button" value="#" /></div>
<div class="test"><input type="text" /><input type="button" value="test"/></div>
</div>

The $.fn.sendkeys Plugin

I wanted to make a general-purpose onscreen keypad, and wasted a huge amount of time trying to find a way to simulate a keypress. $(element).trigger("keypress",...) won't work. Neither will keyup or keydown. For security reasons, I guess, you can't tell an element to pretend a key was pressed. The browser is too worried that you will access menus or something.

So I wrote my own plugin and named it after Microsoft's sendkeys which does similar things. For any element elem that is a <textarea> or <input type="text">, $(elem).sendkeys(string) inserts string at the insertion point or selection. It's the insertion point sensitivity that makes it more sophisticated than elem.value += string.

You can use it on more than one element at a time, like any plugin, but it looks funny, since the insertion point only blinks on the last element (see the example above).

Internet Explorer (of course!) causes a bit of trouble, since input elements do not retain the location of the insertion point when focus returns to them. I have to store the insertion point in $.data(elem, 'sendkeys.selection'), which works, but on first use it always appends to the string rather than inserting.

In the example above, the "test" button will insert whatever is in the text field into the output on top.

It might work on other elements, but there are no guarantees.

Special keys

Some special keys are defined, namely {backspace} to delete backwards, {del} to delete forwards, and {rightarrow} and {leftarrow} to move the insertion point. {selectall} selects the entire field. {{} inserts a { by itself. So $(elem).sendkeys('1234') inserts 1234, $(elem).sendkeys('123{backspace}4') inserts 124, and $(elem).sendkeys('1234{leftarrow}{leftarrow}{leftarrow}{del}') inserts 134.

I used Microsoft's key-escaping notation rather than backslashes because putting backslashes in strings means escaping them, and I always get lost in the forest of slashes. Unlike the Microsoft function, this does not use metacharacters (+^%~).

Options

There are no options to the plugin call itself, but the $.fn.sendkeys.defaults object contains the functions to deal with special keys. It defaults to:

$.fn.sendkeys.defaults = {
	'{backspace}': backspace,
	'{rightarrow}': rightarrow,
	'{leftarrow}': leftarrow,
	'{del}': del,
	'{{}': function() {simplechar.call(this, '{')},
	'simplechar': simplechar // the default function
};

where the backspace, rightarrow, leftarrow and del functions are browser-specific. You can create synonyms easily, like $.fn.sendkeys.defaults['{BS}'] = $.fn.sendkeys.defaults['{backspace}']. $.fn.sendkeys.defaults.simplechar is the workhorse insertion function. You can define your own special key functions as function(<string>), where the argument is the name of the special key and this is bound to the element.

Thus, $.fn.sendkeys.defaults['{alert}'] = function(s) {alert(this.value}}.

The plugin also pulls custom special keys from the jQuery cache with the key 'sendkeys', so

$.data(elem, 'sendkeys', {
	'{alert}' : function(s) {alert(this.value}}
});

will use that function on that element only.

Downloads

Download $.fn.sendkeys.

  <div style="background: purple; margin: 2px">This is a test</div>

And more testing:

  <div style="background: #080; margin: 2px">This is a test</div>

Avoiding Bloat in Widgets

A while back, Justin Palmer wrote an excellent article on "Avoiding Bloat in Widgets." The basic premise (no suprise to anyone whose ever dealt with object-oriented programming) is that your widgets should not do everything possible; they should do one thing well but be flexible enough to allow others to modify them.

He describes two ways of extending objects: subclassing and aspect-oriented programming (AOP). Subclassing creates new classes, while AOP modfies the methods of a single object. Both can be useful.

So let's make Palmer's Superbox widget (it just moves randomly about the screen with mouse clicks):

$.yi = {}; // create our namespace
var Superbox = {
	init: function(){
		var self = this;
		this.element.click(function(){
			self.move();
		});
	},
	move: function(){
		this.element.css (this.newPoint());
	},
	newPoint: function(){
		return {top: this.distance(), left: this.distance()};
	},	
	distance: function(){
		return Math.round (Math.random()*this.getData('distance'));
	}
};
$.widget ('yi.superbox', Superbox);
$.yi.superbox.defaults = { distance: 200 };

I've factored apart a lot of the code, so we have plenty of "hooks" to use to extend the method without copying code. Note that none of the code refers to "superbox" directly, so we can create subclasses that don't know the superclass's name.

Subclassing Widgets

Now let's make a new class, supererbox, that moves rather than jumps to its new location. I'll use Douglas Crockford's prototypal inheritance pattern to simplify subclassing (you could use a fancier one like Dean Edward's Base, or manipulate prototypes yourself).

function object(o){
	function F(){};
	F.prototype = o;
	return new F;
}

$.widget.subclass = function (name, superclass){
	$.widget(name); // Slightly inefficient to create a widget only to discard its prototype, but it's not too bad
	name = name.split('.');
	var widget = $[name[0]][name[1]]; // $.widget should return the object itself!
	
	widget.prototype = object(superclass.prototype);
	var args = Array.prototype.slice.call(arguments,1); // get all the add-in methods
	args[0] = widget.prototype;
	$.extend.apply(null, args); // and add them to the prototype
	widget.defaults = object(superclass.defaults);
	
	// Subtle point: we want to call superclass init and destroy if they exist
	// (otherwise the user of this function would have to keep track of all that)
	if (widget.prototype.hasOwnProperty('init')){;
	  var init = widget.prototype.init;
		widget.prototype.init = function(){
			superclass.prototype.init.apply(this);
			init.apply(this);
		}
	};
	if (widget.prototype.hasOwnProperty('destroy')){
		var destroy = widget.prototype.destroy;
		widget.prototype.destroy = function(){
			destroy.apply(this);
			superclass.prototype.destroy.apply(this);
		}
	}
	return widget; // address my complaint above
};

// allow for subclasses to call superclass methods
$.widget.prototype.callSuper = function(superclass, method){
	superclass = superclass.split('.'); // separate namespace and name
	return $[superclass[0]][superclass[1]].prototype[method].apply(this, Array.prototype.slice.call(arguments, 2)); // corrected from (arguments, 3)
};
// For the purposes of this demo, the above function was defined after we created superbox,
// so superbox does not include it. We'll include it manually
$.yi.superbox.prototype.callSuper = $.widget.prototype.callSuper;

And use it like this:

$.widget.subclass ('yi.supererbox', $.yi.superbox, {
	// overriding and new methods
	move: function(){
		this.element.animate(this.newPoint(), this.getData('speed'));
	},
	home: function(){
		this.element.animate({top:0, left:0}, this.getData('speed'));
	}
});
$.yi.supererbox.defaults.speed = 'normal';

The function signature is $.widget.subclass(name <String>, superclass <Object>, [newMethods <Object>]*), where you can use as many newMethod objects as you want. This lets you use mixin objects, like $.ui.mouse, that add a specific set of methods.

We now have a new widget called supererbox that is just like superbox but moves smoothly.

Calling Superclass Methods

If we want to use the superclass methods in our method, we use callSuper:

$.widget.subclass('yi.superboxwithtext', $.yi.supererbox, {
	move: function(){
		var count = this.getData('count') || 0;
		++count;
		this.setData('count', count);
		this.element.text('Move number '+count);
		this.callSuper('yi.supererbox', 'move'); // note that we could just as well use 'yi.superbox' for the original, "jumpy" move
	}
});

Aspect Oriented Programming

Aspect oriented programming addresses some of these problems, by keeping a reference to the superclass method. New methods don't so much override the old ones as supplement them, adding code before or after (or both) the original code, without hacking at the original class definition.

We'll create a mixin object for widgets that's stolen straight from Justin Palmer's article:

$.widget.aspect =  {
  yield: null,
  returnValues: { },
  before: function(method, f) {
    var original = this[method];
    this[method] = function() {
      f.apply(this, arguments);
      return original.apply(this, arguments);
    };
  },
  after: function(method, f) {
    var original = this[method];
    this[method] = function() {
      this.returnValues[method] = original.apply(this, arguments);
      return f.apply(this, arguments);
    }
  },
  around: function(method, f) {
    var original = this[method];
    this[method] = function() {
      this.yield = original;
      return f.apply(this, arguments);
    }
  }
};

And we use it just like we might use $.ui.mouse: $.widget('ns.foo', $.extend({}, {...methods for foo...}, $.widget.aspect) or, with our subclassing, $.widget.subclass('ns.foo-with-aspects', $.ns.foo, $.widget.aspect).

For example, let's say we have a cool plugin to make an element pulsate (I know, UI has a pulsate method that does this):

$.fn.pulse = function (opts){
	opts = $.extend ({}, $.fn.pulse.defaults, opts);
	for (i = 0; i < opts.times; ++i){
		this.animate({opacity: 0.1}, opts.speed).animate({opacity: 1}, opts.speed);
	}
	return this;
};
$.fn.pulse.defaults = {
	speed: 'fast',
	times: 2
};

And we'll create a version of supererbox that allows for AOP:

$.widget.subclass ('yi.supererbox2', $.yi.supererbox, $.widget.aspect);

And we'll create a supererbox object, then make it pulse before moving:

$('#experiment4').supererbox2().supererbox2('before','move', function() {
	this.element.pulse();
});

Or even make it pulse before and after moving:

$('#experiment5').supererbox2().supererbox2('around','move', function() {
	this.element.pulse();
	this.yield();
	this.element.pulse();
});

Note that once we added the aspect methods to create supererbox2, we didn't create any new classes to get this new behavior; we added the behavior to each object after the object was created.

alert('Hello, world');

and another: <div>Hello, <em>world</em></div>

I'm trying to be as HTML5-compliant as possible, at least in the sense of using their standards rather than making up my own, so the Chili setup I'm using is:

    $.extend(ChiliBook, {
        automatic: false,
        codeLanguage: function(el){
            // use the HTML5 language class
            var recipeName = /language-(\S+)/.exec(el.className);
            return recipeName ? recipeName[1] : '';
        }
    });
    $(function(){
        $('code[class*=language-]').not($('pre code')).chili({lineNumbers: false})
                                  .otherwise().chili({lineNumbers: true});
    });

 

Sweet! The idea of the above code is to look for a class that starts with "language-" and use that as the recipe for Chili (rather than Chili's built-in way of taking the entire className). It also assumes that any code in a pre element should have line numbers, and anything else should not. It uses the cute and brilliant otherwise plugin from http://groups.google.com/group/jquery-en/browse_thread/thread/6be2a127822a108d.

Update: It looks like line numbering works only intermittently. Oh well; I won't fix it.

This idea fails for plugins, however, since plugins expect this to refer to the jQuery object that started the chain. If I define $.fn.bar = function(){}, then when $(...).bar() is called, this refers to $(...), just as we want. But if I define $.fn.foo.bar = function(){}, then when $(...).foo.bar() is called, this refers to $(...).foo, which is an object that knows nothing about jQuery. There's no way to make an object reference return something else.

But all is not lost. We can define a function that returns an object, and that function can use this to set the returned object to be just like a jQuery object, but with the desired namespaced methods in it. The inefficient way to do that is to copy the new methods into the jQuery object, but if we can manipulate the prototype chain directly (as we can in Firefox) we can add our new methods to the chain without copying.

So a namespacing plugin would be:

(function($){
if ({}.__proto__){
	// mozilla  & webkit expose the prototype chain directly
	$.namespace = function(name){
		$.fn[name] = function namespace() { // insert this function in the prototype chain
			this.__proto__ = arguments.callee;
			return this;
		};
		$.fn[name].__proto__ = $.fn;
	};
	$.fn.$ = function(){
		this.__proto__ = $.fn;
		return this;
	};	
}else{
	// every other browser; need to copy methods
	$.namespace = function(name){
		$.fn[name] = function namespace() { return this.extend(arguments.callee); };
	};
	$.fn.$ = function() { // slow but restores the default namespace
		var len = this.length;
		this.extend($.fn);
		this.length = len; // $.fn has length = 0, which messes everything up
		return this;
	};
}
})(jQuery);

And you could use it like:

	$.namespace('danny');
	$.namespace('danny2');
	$.fn.danny.foo = function() {return this.css('color', 'green')};
	$.fn.danny2.foo = function(x){alert(x); return this; };
	// now we have two different methods "foo"
	$('p').danny().foo(); // colors paragraphs green
	$('p').danny2().foo('Hello, world'); // alerts 'Hello, world'
	$('p').danny().foo().danny2().foo('Hello, world'); // chaining works
	$.fn.danny.add = function(a,b) { alert(a+b); return this;}; // defines a function with the same name as a real jQuery one
	$('p').danny().add(1,2).$().add('div'); // the $() plugin restores the real jQuery namespace to a chain

The namespacing is per-chain only; $('p').danny() does not affect any subsequent statements. Plugins that call pushStack will reset the namespacing, but in general the namespace function should be called right before the method, so that should not be an issue.

This is inefficient, obviously, adding an extra function call and possible a lot of copying with extend, but for most code that is insignificant.

Avoiding Bloat in Widgets

A while back, Justin Palmer wrote an excellent article on "Avoiding Bloat in Widgets." The basic premise (no suprise to anyone who's ever dealt with object-oriented programming) is that your widgets should not do everything possible; they should do one thing well but be flexible enough to allow others to modify them.

He describes two ways of extending objects: subclassing and aspect-oriented programming (AOP). Subclassing creates new classes, while AOP modfies the methods of a single object. Both can be useful.

So let's make Palmer's Superbox widget (it just moves randomly about the screen with mouse clicks):

var Superbox = {
	init: function(){
		this.element.click(function(){
			$.data(this,'superbox').move();
		});
	},
	move: function(){
		this.element.css (this.newPoint());
	},
	newPoint: function(){
		return {top: this.distance(), left: this.distance()};
	},	
	distance: function(){
		return Math.round (Math.random()*this.getData('distance'));
	}
};
$.widget ('yi.superbox', Superbox);
$.yi.superbox.defaults = { distance: 200 };

I've factored apart a lot of the code, so we have plenty of "hooks" to use to extend the method without copying code. The $.data(this,'superbox') is the idiom to get the widget object from a DOM element.

Subclassing Widgets (The First Try)

Now let's make a new class, supererbox, that moves rather than jumps to its new location. I'll use Douglas Crockford's prototypal inheritance pattern to simplify subclassing (you could use a fancier one like Dean Edward's base2, or manipulate prototypes yourself).

function object(o){
	function F(){};
	F.prototype = o;
	return new F;
}

// utility function
// if eval weren't evil, it would just be eval('$.'+name);
function widgetNamed(name){
	var name = name.split('.');
	var namespace = name[0];
	name = name[1];
	return $[namespace][name];
}

$.widget.subclass = function (name, superName){
	$.widget(name); // Slightly inefficient to create a widget only to discard its prototype, but it's not too bad
	
	// $.widget ought to return the created object, obviating this call
	var widget = widgetNamed(name);
	var superclass = widgetNamed(superName);
	
	widget.prototype = object(superclass.prototype);
	var args = Array.prototype.slice.call(arguments,1); // get all the add-in methods
	args[0] = widget.prototype;
	$.extend.apply(null, args); // and add them to the prototype
	widget.defaults = object(superclass.defaults);
	return widget; // address my complaint above
};

And use it like this:

$.widget.subclass ('yi.supererbox', 'yi.superbox', {
	// overriding and new methods
	move: function(){
		this.element.animate(this.newPoint(), this.getData('speed'));
	},
	home: function(){
		this.element.animate({top:0, left:0}, this.getData('speed'));
	}
});
$.yi.supererbox.defaults.speed = 'normal';

The function signature is $.widget.subclass(name <String>, superName <String>, [newMethods <Object>]*), where you can use as many newMethod objects as you want. This lets you use mixin objects, like $.ui.mouse, that add a specific set of methods.

Getting Subclassing Right

This is pretty good as it stands, but the ever-astute reader will note that there are a number of problems with this method:

1. Overriding methods replace the superclass methods entirely. There's no way to get at the original move if, for some reason, we wanted to call it.
2. Methods in the superclass that refer to $.data(this,'superbox') will fail in subclassed code. The subclassed objects are attached to $.data(this,'supererbox'). This didn't matter in our supererbox example, since we overrode the only method that mentioned superbox itself. But it would be a fatal problem it we, e.g., overrode newPoint.
3. Subclasses shouldn't have to keep track of constructing and deconstructing their superclasses. As is it, a subclass needs to somehow call or copy the superclass init in its own init, and the superclass destroy in its own destroy. This didn't matter in our example, since we didn't use init or destroy, but it could be a big problem.

So we add some slightly kludgy code to keep track of all the superclass methods:

$.widget.subclass = function (name, superName){
	$.widget(name); // Slightly inefficient to create a widget only to discard its prototype, but it's not too bad
	
	// $.widget ought to return the created object, obviating this call
	var widget = widgetNamed(name);
	var superclass = widgetNamed(superName);

	widget.prototype = object(superclass.prototype);
	var args = Array.prototype.slice.call(arguments,1); // get all the add-in methods
	args[0] = widget.prototype;
	$.extend.apply(null, args); // and add them to the prototype
	widget.defaults = object(superclass.defaults);
	// create the superclass chain, a hash of widget objects indexed by their names
	superName = superName.split('.')[1]; // remove the namespace
	widget.supers =  $.extend({}, superclass.supers); // get the old superclasses
	widget.supers[superName] = superclass; // and add the new
	
	// address the third problem above by making the init method of the subclass call the init method of the superclass
	var init = widget.prototype.hasOwnProperty('init') ? widget.prototype.init : function(){};
	widget.prototype.init = function(){
		this.element.data(superName, this); // address the second problem by adding this under the superclass's name as well
		superclass.prototype.init.apply(this); // address the third problem by calling the superclass's init
		init.apply(this); // do the real init
	};
	// now do the same for destroy, if needed
	if (widget.prototype.hasOwnProperty('destroy')){
		var destroy = widget.prototype.destroy;
		widget.prototype.destroy = function(){
			destroy.apply(this);
			superclass.prototype.destroy.apply(this);
		}
	}
	return widget; // address my complaint above
};

// address the first problem by creating method to call the superclass method
// use as this.callSuper($.yi.superbox, 'foo', arg1, arg2); after mixing in the CallSuper class
var CallSuper = {
	callSuper: function(superclass, method){
		return superclass.prototype[method].apply(this, Array.prototype.slice.call(arguments, 3));
	}
};

We now have a new widget called supererbox that is just like superbox but moves smoothly.

Calling Superclass Methods

If we want to use the superclass methods in our method, we mixin the CallSuper object and use callSuper:

$.widget.subclass('yi.superboxwithtext', 'yi.supererbox', CallSuper, {
	move: function(){
		var count = this.getData('count') || 0;
		++count;
		this.setData('count', count);
		this.element.text('Move number '+count);
		this.callSuper($.yi.supererbox, 'move'); // note that we could just as well use $.yi.superbox for the original, "jumpy" move
	}
});

Aspect Oriented Programming

Aspect oriented programming addresses some of these problems, by keeping a reference to the superclass method. New methods don't so much override the old ones as supplement them, adding code before or after (or both) the original code, without hacking at the original class definition.

We'll create a mixin object for widgets that's stolen straight from Justin Palmer's article:

$.widget.aspect =  {
  yield: null,
  returnValues: { },
  before: function(method, f) {
    var original = this[method];
    this[method] = function() {
      f.apply(this, arguments);
      return original.apply(this, arguments);
    };
  },
  after: function(method, f) {
    var original = this[method];
    this[method] = function() {
      this.returnValues[method] = original.apply(this, arguments);
      return f.apply(this, arguments);
    }
  },
  around: function(method, f) {
    var original = this[method];
    this[method] = function() {
      this.yield = original;
      return f.apply(this, arguments);
    }
  }
};

And we use it just like we might use $.ui.mouse: $.widget('ns.foo', $.extend({}, {...methods for foo...}, $.widget.aspect) or, with our subclassing, $.widget.subclass('ns.foo-with-aspects', 'ns.foo', $.widget.aspect).

For example, let's say we have a cool plugin to make an element pulsate (I know, UI has a pulsate method that does this):

$.fn.pulse = function (opts){
	opts = $.extend ({}, $.fn.pulse.defaults, opts);
	for (i = 0; i < opts.times; ++i){
		this.animate({opacity: 0.1}, opts.speed).animate({opacity: 1}, opts.speed);
	}
	return this;
};
$.fn.pulse.defaults = {
	speed: 'fast',
	times: 2
};

And we'll create a version of supererbox that allows for AOP:

$.widget.subclass ('yi.supererbox2', 'yi.supererbox', $.widget.aspect);

And we'll create a supererbox object, then make it pulse before moving:

$('#experiment4').supererbox2().supererbox2('before','move', function() {
	this.element.pulse();
});

Or even make it pulse before and after moving:

$('#experiment5').supererbox2().supererbox2('around','move', function() {
	this.element.pulse();
	this.yield();
	this.element.pulse();
});

Note that once we added the aspect methods to create supererbox2, we didn't create any new classes to get this new behavior; we added the behavior to each object after the object was created.