I picked up a 1/24 scale New Bright 2014 Silverado for about $10 at Target. I chose this model because of the truck bed, so I would have a place to mount a microcontroller in case I decided to mod the car itself later. I also made sure to check what kind of batteries the remote used to make sure I could power it from my RedBoard. The remote uses two AAs, which is a total of 3 volts, so I figured the 3.3v power pin would be perfect. The car itself uses three AAs, which is a total of 4.5 volts, so if I do go down the road of hacking the car, using the 5v power pin should be fine.

The first thing I do whenever I dig into anything new is making sure that it works as I expect, so I can verify the behavior is the same after every step. After my kids played with the car for a bit, I knew everything was working, so it was time to start ripping things apart. The remote was just two pieces of plastic held together with two screws and a few plastic clips. As soon as I opened it, I found something unexpected. The joysticks were actually just two buttons for each axis, not a standard joystick with variable movement along the axes. In hindsight, this should have been obvious since the car didn’t have variable speed and the wheels snapped to a specific position when turning.

Now that I had the remote opened up, I had to get the circuit board out of the plastic. This was just a matter of pulling the battery leads straight out (while compressing the spring for the negative lead), then the circuit board came out very easily. I used some jumper wires to connect the 3.3v and GND pins from the Arduino to the battery contacts and pushed the forward button to make sure powering the remote was going to work. Once I had confirmed this worked, I hooked up two AAs so that I didn’t need to hold the wires in place as I did more testing. I then tested all four buttons just to make sure everything was still working.

At this point, my plan was to replace the buttons with some other component that I could control from the Arduino. I wasn’t really sure what I could use for the replacement though. My only thought was to use a relay, but then I decided to try to trace the circuit and see if there was another way to hook in without desoldering the buttons. I noticed that there were seemingly random solder points connected to each of the buttons (these turned out to be test points for the board), so I decided to try applying voltage to the solder point for the forward button. I already had a script open that blinks an LED every second, so I just used that for my testing, since it would toggle between a HIGH and LOW signal on the pin. I was happy to find out that this worked (once I remembered to connect the GND pin as well to complete the circuit). I then tested the other three solder points to make sure I had identified the correct point for each button.

I was finally ready to start modifying the board. I plugged in my soldering iron and cut six pieces of hookup wire (one for each button and two for power) while the iron was heating up. First up was desoldering the battery leads and adding the new wire leads to connect to the Arduino. Then I soldered a wire to each of the four solder points that corresponded to the four buttons. This is where I made my biggest mistake. I didn’t realize how stiff the hookup wire was and how fragile the solder points would be. When I tried to bend all the wires to plug into my breadboard, I ended up ripping out the wire for reverse. I had to solder the wire directly to the button at that point, but I learned a valuable lesson: bend the wires into their desired shape prior to soldering.

Now that the board was modified, I was ready to write a script to control the car. I decided to keep it simple and just use the arrow keys. Rather than having to hold down the keys, I made each action “sticky” so pressing up once would make the car go forward until you either pressed up again to stop it or pressed down to make it go in reverse. This worked pretty well, but it was very awkward for turning. Modifying the script to treat left and right as momentary actions would make it easier to control. My next step will probably be exposing the controls via a web server so my kids can control the car with their iPads. I never thought I’d be able to do that with a cheap off-the-shelf RC car and just an hour or two of tinkering. After just a few weeks of playing with Johnny-Five, it all seems so simple

var five = require("johnny-five");
var keypress = require("keypress");

keypress(process.stdin);
process.stdin.resume();

var board = new five.Board();

board.on("ready", function() {
	var forward = new five.Led(13);
	var back = new five.Led(7);
	var left = new five.Led(12);
	var right = new five.Led(8);

	forward.on();
	back.on();
	left.on();
	right.on();

	process.stdin.on("keypress", function(_, key) {
		if (!key) {
			return;
		}

		switch (key.name) {
			case "up":
				forward.toggle();
				back.on();
				break;

			case "down":
				back.toggle();
				forward.on();
				break;

			case "left":
				left.toggle();
				right.on();
				break;

			case "right":
				right.toggle();
				left.on();
				break;

			case "c":
				if (key.ctrl) {
					process.exit();
				}
				break;
		}
	});

	this.repl.inject({
		forward: forward,
		back: back,
		left: left,
		right: right
	});
});

Note: This script uses the keypress module.

	ServerName tmp.code.dev
	ServerAlias *.code.dev
	VirtualDocumentRoot /path/to/projects/%1
	
		AllowOverride All
	

This tells Apache that any domain ending with .code.dev should be served by the directory in /path/to/projects/ that has the same name as the beginning of the domain. For example, foo.code.dev would be served from /path/to/projects/foo/. This reduces my per-project setup to just adding an entry in /etc/hosts to map the custom domain to my local machine, e.g., 127.0.0.1 foo.code.dev. Unfortunately, wildcards can’t be used in the hosts file, so this step needs to occur for every project. That’s a little annoying, but it’s easy enough that I was willing to live with it.

As I started working on more sites (as opposed to libraries or frameworks that happen to need a web server), I created another VirtualHost to create nicer domains and handle subdomains. If I’m working on foo.com, I create a directory named /foo.com/ in my projects directory and use the domain local-dev.foo.com for testing.

	ServerName local-dev
	ServerAlias local-dev.*
	VirtualDocumentRoot /path/to/projects/%2+
	
		AllowOverride All
	

Using %2+ tells Apache to use every part of the domain after the first part. You can read more about how the VirtualDocumentRoot interpolation works in the mode_vhost_alias documentation. And of course, I would add 127.0.0.1 local-dev.foo.com to my hosts file.

Testing from physical devices

Unfortunately, there is a big limitation to this setup. When testing from a physical device, such as a phone or tablet, the custom domain won’t map to your local web server. Since the physical device doesn’t know anything about the hosts file on the machine with the web server, trying to load foo.code.dev from the device’s browser isn’t going to work. This generally discouraged me from testing on physical devices because I never had a great solution to this problem. Whenever the need would arise, I’d create another virtual host using my machine’s LAN IP and a random port:

	ServerName local-dev.foo.com
	DocumentRoot /path/to/projects/foo.com
	
		AllowOverride All
	

Then I can connect to 192.168.1.2:1234 instead of local-dev.foo.com from any physical device connected to my network. But I’ve lost the benefit of the wildcard aliasing and now I need to remember which port to use. This can be quite burdensome as the number of sites increases, especially since each site needs to use a different port.

After years of dealing with this, I decided to ask for help on Twitter. I got a few responses, but the one I like the best came from Andrew Sheppard, who pointed me to xip.io.

xip.io to the rescue

xip.io is a free service from 37signals, which provides wildcard DNS for any IP address. Just like we can map *.code.dev to the appropriate directory on our local machine, xip.io can map *.xip.io to the appropriate IP for local testing. The URL structure is nice and simple, just prepend the IP address you want the domain to resolve to; the xip.io DNS server handles the rest. In this case, we’d use 192.168.1.2.xip.io to map the domain to 192.168.1.2.

This solves the DNS issue and removes the need to edit the hosts file for each site. But given a domain of 192.168.1.2.xip.io, we still don’t know which directory to server the site from. To address this, xip.io allows adding as many subdomains as you want. So we can use foo.com.192.168.1.2.xip.io and then create a virtual host that knows how to handle xip.io domains.

	ServerName xip
	ServerAlias *.xip.io
	VirtualDocumentRoot /path/to/projects/%-7+
	
		AllowOverride All
	

Handling DNS on your local machine

Although the xip.io setup does allow for zero-configuration setup, there are a few caveats.

The URLs are long and a bit ugly. I’ve created a simple page, bit.ly/xipio, to generate the xip.io URLs so I don’t need to type the full URL in the tiny address bar on my devices. I also kept my local-dev.* virtual host enabled so that I can use shorter, nicer URLs if I want, though this does require adding an entry in the hosts file as mentioned above, and doesn’t allow testing from physical devices.

The URLs don’t work offline. Obviously if you can’t can’t connect to xip.io, the whole thing is going to fall apart.

The URLs aren’t shareable. Since the domain contains your personal LAN IP, sharing links with other developers working on the same site from their local machine won’t work (unless you happen to have the same LAN IP). However, it’s quite easy for the other person to change the IP after you’ve shared it with them.

More on link sharing

Link sharing is really useful when working on a project with other people, so it’s worth discussing specifically. As I mentioned above, while xip.io URLs can’t just be copy/pasted, they’re fairly easy to work with. However, having a common setup, such as local-dev.* for your projects makes link sharing much easier. If everyone working on the project is using local-dev.foo.com when testing from the main machine, then link sharing just works.

To avoid having everyone edit their hosts file to get the domain mapping to work, another option is to actually create a DNS record for local-dev.foo.com. By creating an A record that points local-dev.foo.com to 127.0.0.1, you can get back to a zero-configuration setup. However, you do have the same offline problem as using xip.io, but that can be solved via the hosts file for any developer that needs offline access to work.

Other solutions

As with most things related to software development, there’s more than one solution to this problem. Matt Surabian wrote an article about using Charles Proxy to test local sites with physical devices in response to my tweet. Using Charles Proxy has a different set of pros and cons, so I suggest reading Matt’s article and determining which solution works best for you.

I’ve come across three main categories of application-specific plugins since I started using jQuery. The first category contains plugins that are useful throughout most of your application, but useless outside of your application. These plugins usually deal with traversing and manipulating common components based on specific markup in your application. This set of plugins can be used on many elements across many pages and therefore get the most reuse. The second category contains plugins that are tied to a specific element that persists across most, if not all, of your application. These are different from the first category because the plugins are never called on more than one element for any page load. You can think of these as Singleton DOM components, such as help dialogs. The final category consists of plugins that are only used on a single page. In many cases these plugins will be used on multiple elements within the page, but the plugin is never loaded on any other page.

One pattern for creating application-specific plugins is to prefix your method names to prevent name collisions. For example, let’s say we have lots of widgets with common markup structures. If we want to be able to navigate from any given element on the page to the widget the element is contained in, we might create a method called nmkWidget.

Let’s assume the widgets have the following shell:

We can define some helper functions for navigating the DOM:

$.fn.nmkWidget = function() {
	return this.closest( ".nmk-widget" );
};
$.fn.nmkWidgetHeader = function() {
	return this.nmkWidget().children( ".nmk-widget-header" );
};
$.fn.nmkWidgetContent = function() {
	return this.nmkWidget().children( ".nmk-widget-content" );
};

This works well for simple plugins like these that don’t have any dependencies or state management beyond the DOM. But what happens if you have a lot of inter-related functionality that you want to organize into a module? jQuery doesn’t have support for namespaces in jQuery.fn, but there is a simple pattern that can help. We can define a method that acts as a pass-thru from jQuery to any object:

var slice = Array.prototype.slice;
$.fn.exec = function( method ) {
	return method.apply( this, slice.call( arguments, 1 ) );
};

Then we can create objects, nested as deeply as we want, and define methods on them as if they were standard jQuery methods:

var nmk = {
	widget: {
		open: function( duration ) {
			return this.nmkWidget().slideDown( duration );
		},
		close: function( duration ) {
			return this.nmkWidget().slideUp( duration );
		}
	}
};

We can then execute them using .exec() in any jQuery chain:

$( elem ).exec( nmk.widget.close );

We can even pass parameters to these methods:

$( elem ).exec( nmk.widget.close, 1000 );

Now we’ve got reusable, modular, namespaced code that can be used directly in jQuery chains. We can use this to define multiple ways to close our widgets without duplicating any logic and without worrying about where we are in the DOM.

// allow any widget to be closed by a close button located in the header
$( ".nmk-widget-close-button" ).live( "click", function() {
	$( this ).exec( nmk.widget.close );
});

// allow adding a new widget, with undo functionality
$( "#add-widget" ).click(function() {
	// generate a new widget and add to the page
	// returns a jQuery object containing the new widget
	var widget = nmk.widget.create();
	$( "
Your new widget has been added. Click here to undo.
;" )
		.click(function() {
			widget.exec( nmk.widget.close );
		});
});

Many web developers seem to think there is some sort of black magic behind long polling, either because the language or web server they use doesn’t support it or because they correlate it with server push technology. In this article, we’ll show how to implement long polling in Node.js and explain why you don’t need to do anything special on the client to support it.

Request types

We’re all familiar with standard web requests: the client requests a resource, the server responds synchronously, then the page is displayed. We’re also familiar with the concept of ajax requests in which the client requests a resource asynchronously and is notified when the server responds. Typically the server doesn’t treat ajax requests asynchronously; a request comes in and the server immediately (and synchronously) processes the request and responds. The asynchronous part just happens on the client where the browser doesn’t block while it waits for the server to respond.

Long polling is an ajax request in which the request and response are both treated as asynchronous operations. Rather than accepting the request and immediately processing to return a result, the server accepts the request and holds on to it until some other event occurs, providing data to send as a response to the original request. Most scripting languages don’t support holding on to requests for long periods of time because the script runs from top to bottom and then immediately responds. Trying to hold on to requests in these languages would require creating a blocking loop that waits for the relevant event to occur and that would quickly kill your server as requests build up. Node scripts run in an event loop, making them ideal for holding on to requests without blocking other processes.

Handling requests in Node

Because Node is specifically built to provide non-blocking I/O, even the Hello World example from the docs shows off an asynchronous response to an HTTP request.

var http = require("http");
http.createServer(function(request, response) {
	setTimeout(function() {
		response.writeHead(200, { "Content-Type": "text/plain" });
		response.end("Hello, World!");
	}, 2000);
}).listen(8000);

When a request comes in, the server will wait two seconds and then respond with “Hello, World!”. The important thing in this example is that the script is not blocking while it waits two seconds. This means that other requests can come in during that two second period and be handled immediately. In this case, those additional requests would also wait for two seconds before getting a response, but the response would come two seconds after the request was initiated, not two seconds after the previous request is closed.

Let’s split the response generation out of the main function to get a better idea of what’s really going on here.

var http = require("http");
var requests = [];

http.createServer(function(request, response) {
	// store the response so we can respond later
	requests.push(response);
}).listen(8000);

setInterval(function() {
	// respond to each request
	while (requests.length) {
		response = requests.shift();
		response.writeHead(200, { "Content-Type": "text/plain" });
		response.end("Hello, World!");
	}
}, 2000);

There are a few differences between this example and the first example. Right away, we can see that when a request comes in we don’t make any attempt to respond to it, we just throw the response object into an array and seemingly ignore it. Next we have a function that runs every two seconds and responds to all the requests that we’re holding on to. Since this interval is based on when the script was started, the request may be held for anywhere between one millisecond and two seconds, depending on how close the request comes in to the next run of the interval. This better represents the standard model for a long polling implementation in which some event not directly related to the request occurs on the server and triggers a response.

A more complex example

Let’s build a script the pipes stdin to HTTP requests. When an HTTP request comes, we’ll check to see if we have any data already stored from stdin. If we do, we’ll just respond to the request immediately; if we don’t, we’ll hold on to the request and respond whenever we detect some action from stdin. Likewise, when we receive data from stdin, we’ll check to see if we have a pending HTTP request. If we do, we’ll respond to the request with the data that just came in; if we don’t, we’ll store the data and respond whenever a request comes in.

var http = require("http");
var pendingResponse;
var chunks = "";

http.createServer(function(request, response) {
	// if we have data, send it
	if (chunks.length) {
		response.writeHead(200, { "Content-Type": "text/plain" });
		response.end(chunks);
		chunks = "";

	// no data sitting around, store the response for later
	} else {
		pendingResponse = response;
	}
}).listen(8000);

process.openStdin().addListener("data", function(chunk) {
	// if we have a pending request, send the data
	if (pendingResponse) {
		pendingResponse.writeHead(200, { "Content-Type": "text/plain" });
		pendingResponse.end(chunk);
		pendingResponse = null;

	// no pending request, store the chunk from stdin for later
	} else {
		chunks += chunk;
	}
});

Preventing timeouts

One problem you might run into with long polling is holding on to the request too long. If you take too long to respond, the request will eventually time out. To prevent this from occurring, you can keep track of when the requests come in, and send an empty response if the request is still open after a certain period of time. When the client receives the empty response, it will start the next long poll request. This can easily be accomplished with a slight tweak to the code above that uses an interval to respond to requests. Instead of just responding to all requests, we would check if the request has been pending for too long, and close it out if it has.

var http = require("http");
var requests = [];

http.createServer(function(request, response) {
	// store the response so we can respond later
	requests.push({
		response: response,
		timestamp: new Date().getTime()
	});
}).listen(8000);

setInterval(function() {
	// close out requests older than 30 seconds
	var expiration = new Date().getTime() - 30000;
	var response;
	for (var i = requests.length - 1; i >= 0; i--) {
		if (requests[i].timestamp < expiration) {
			response = requests[i].response;
			response.writeHead(200, { "Content-Type": "text/plain" });
			response.end("");
		}
	}
}, 1000);

Long polling on the client

As mentioned above, there’s nothing special that needs to be done on the client for long polling. The general concept is just to make an ajax request and when you get a response, handle it and make the ajax request again. This process just loops over and over, handling data whenever the server responds.

Over the past few years, jQuery has dominated the web development community with its simple, yet brilliant, API. The “find elements, do something” pattern and ability to chain function calls together combine to create code that reads like English. jQuery’s simplicity and almost nonexistent learning curve have made it extremely popular among developers and designers alike. Equally as important as its ease of use is its extensibility. With an extension system that makes creating a plugin as simple as writing a function, jQuery has been able to maintain a lean core while offering an almost unlimited amount of functionality.

The combination of jQuery’s simple plugin system and its active community has resulted in over 2,000 plugins being listed in its plugin repository. However, like all core methods, the majority of these plugins only provide stateless functionality. While many of these plugins are useful, there’s a large set of functionality that doesn’t fit into the basic plugin pattern.

A new plugin system

In order to fill this gap, jQuery UI has implemented a more advanced plugin system. The new system manages state, allows multiple functions to be exposed via a single plugin, and provides various extension points. This system is called the widget factory and is exposed as jQuery.widget. In this article, we’ll explore the various features provided by the widget factory by building a simple progress bar plugin using jQuery UI 1.8.

Building a plugin

To start, we’ll create a progress bar that just lets us set the progress once. As we can see below, this is done by calling jQuery.widget with two parameters: the name of the plugin to create and an object literal containing functions to support our plugin. When our plugin gets called, it will create a new plugin instance and all functions will be executed within the context of that instance. This is different from a standard jQuery plugin in two important ways. First, the context is an object, not a DOM element. Second, the context is always a single object, never a collection.

$.widget( "nmk.progressbar", {
	_create: function() {
		var progress = this.options.value + "%";
		this.element
			.addClass( "progressbar" )
			.text( progress );
	}
});

The name of the plugin must contain a namespace, in this case we’ve used the nmk namespace. There is currently a limitation that exactly one namespace must be used. We can also see that the widget factory has provided two properties for us. this.element is a jQuery object containing exactly one element. If our plugin is called on a jQuery object containing multiple elements, a separate plugin instance will be created for each element, and each instance will have its own this.element. The second property, this.options, is a hash containing key/value pairs for all of our plugin’s options. These options can be passed to our plugin as shown here.

$( "
" )
	.appendTo( "body" )
	.progressbar({ value: 20 });

When we call jQuery.widget it extends jQuery by adding a function to jQuery.fn (the system for creating a standard plugin). The name of the function it adds is based on the name you pass to jQuery.widget, without the namespace; in our case “progressbar”. The options passed to our plugin are the values that get set in this.options inside of our plugin instance. As shown below, we can specify default values for any of our options. When designing your API, you should figure out the most common use case for your plugin so that you can set appropriate default values and make all options truly optional.

$.widget( "nmk.progressbar", {
	// default options
	options: {
		value: 0
	},
	_create: function() {
		var progress = this.options.value + "%";
		this.element
			.addClass( "progressbar" )
			.text( progress );
	}
});

Calling plugin methods

Now that we can initialize our progress bar, we’ll add the ability to perform actions by calling methods on our plugin instance. To define a plugin method, we just include the function in the object literal that we pass to jQuery.widget. We can also define “private” methods by prepending an underscore to the function name.

$.widget( "nmk.progressbar", {
	options: {
		value: 0
	},
	_create: function() {
		var progress = this.options.value + "%";
		this.element
			.addClass( "progressbar" )
			.text( progress );
	},
	// create a public method
	value: function( value ) {
		// no value passed, act as a getter
		if ( value === undefined ) {
			return this.options.value;
		// value passed, act as a setter
		} else {
			this.options.value = this._constrain( value );
			var progress = this.options.value + "%";
			this.element.text( progress );
		}
	},
	// create a private method
	_constrain: function( value ) {
		if ( value > 100 ) {
			value = 100;
		}
		if ( value < 0 ) {
			value = 0;
		}
		return value;
	}
});

To call a method on a plugin instance, you pass the name of the method to the jQuery plugin. If you are calling a method that accepts parameters, you simply pass those parameters after the method name.

Note: Executing methods by passing the method name to the same jQuery function that was used to initialize the plugin may seem odd. This is done to prevent pollution of the jQuery namespace while maintaining the ability to chain method calls. Later in this article we'll see alternative uses that may feel more natural.

var bar = $( "
" )
	.appendTo( "body" )
	.progressbar({ value: 20 });

// get the current value
alert( bar.progressbar( "value" ) );

// update the value
bar.progressbar( "value", 50 );

// get the current value again
alert( bar.progressbar( "value" ) );

Working with options

One of the methods that is automatically available to our plugin is the option method. The option method allows you to get and set options after initialization. This method works exactly like jQuery's css and attr methods: you can pass just a name to use it as a setter, a name and value to use it as a single setter, or a hash of name/value pairs to set multiple values. When used as a getter, the plugin will return the current value of the option that corresponds to the name that was passed in. When used as a setter, the plugin's _setOption method will be called for each option that is being set. We can specify a _setOption method in our plugin to react to option changes.

$.widget( "nmk.progressbar", {
	options: {
		value: 0
	},
	_create: function() {
		this.element.addClass( "progressbar" );
		this._update();
	},
	_setOption: function( key, value ) {
		this.options[ key ] = value;
		this._update();
	},
	_update: function() {
		var progress = this.options.value + "%";
		this.element.text( progress );
	}
});

Adding callbacks

One of the easiest ways to make your plugin extensible is to add callbacks so users can react when the state of your plugin changes. We can see below how to add a callback to our progress bar to signify when the progress has reached 100%. The _trigger method takes three parameters: the name of the callback, a native event object that initiated the callback, and a hash of data relevant to the event. The callback name is the only required parameter, but the others can be very useful for users who want to implement custom functionality on top of your plugin. For example, if we were building a draggable plugin, we could pass the native mousemove event when triggering a drag callback; this would allow users to react to the drag based on the x/y coordinates provided by the event object.

$.widget( "nmk.progressbar", {
	options: {
		value: 0
	},
	_create: function() {
		this.element.addClass( "progressbar" );
		this._update();
	},
	_setOption: function( key, value ) {
		this.options[ key ] = value;
		this._update();
	},
	_update: function() {
		var progress = this.options.value + "%";
		this.element.text( progress );
		if ( this.options.value == 100 ) {
			this._trigger( "complete", null, { value: 100 } );
		}
	}
});

Callback functions are essentially just additional options, so you can get and set them just like any other option. Whenever a callback is executed, a corresponding event is triggered as well. The event type is determined by concatenating the plugin name and the callback name. The callback and event both receive the same two parameters: an event object and a hash of data relevant to the event, as we'll see below. Your plugin may have functionality that you want to allow the user to prevent. The best way to support this is by creating cancelable callbacks. User's can cancel a callback, or its associated event, the same way they cancel any native event, by calling event.preventDefault() or returning false. If the user cancels the callback, the _trigger method will return false so you can implement the appropriate functionality within your plugin.

var bar = $( "
" )
	.appendTo( "body" )
	.progressbar({
		complete: function( event, data ) {
			alert( "Callbacks are great!" );
		}
	})
	.bind( "progressbarcomplete", function( event, data ) {
		alert( "Events bubble and support many handlers for extreme flexibility." );
		alert( "The progress bar value is " + data.value );
	});

bar.progressbar( "option", "value", 100 );

Looking under the hood

Now that we've seen how to build a plugin using the widget factory, let's take a look at how it actually works. When you call jQuery.widget, it creates a constructor for your plugin and sets the object literal that you pass in as the prototype for your plugin instances. All of the functionality that automatically gets added to your plugin comes from a base widget prototype, which is defined as jQuery.Widget.prototype. When a plugin instance is created, it is stored on the original DOM element using jQuery.data, with the plugin name as the key.
Because the plugin instance is directly linked to the DOM element, you can access the plugin instance directly instead of going through the exposed plugin method if you want. This will allow you to call methods directly on the plugin instance instead of passing method names as strings and will also give you direct access to the plugin's properties.

var bar = $( "
" )
	.appendTo( "body" )
	.progressbar()
	.data( "progressbar" );

// call a method directly on the plugin instance
bar.option( "value", 50 );

// access properties on the plugin instance
alert( bar.options.value );

Extending a plugin's prototype

One of the biggest benefits of having a constructor and prototype for a plugin is the ease of extending the plugin. By adding or modifying methods on the plugin's prototype, we can modify the behavior of all instances of our plugin. For example, if we wanted to add a method to our progress bar to reset the progress to 0% we could add this method to the prototype and it would instantly be available to be called on any plugin instance.

$.nmk.progressbar.prototype.reset = function() {
	this._setOption( "value", 0 );
};

Cleaning up

In some cases, it will make sense to allow users to apply and then later unapply your plugin. You can accomplish this via the destroy method. Within the destroy method, you should undo anything your plugin may have done during initialization or later use. The destroy method is automatically called if the element that your plugin instance is tied to is removed from the DOM, so this can be used for garbage collection as well. The default destroy method removes the link between the DOM element and the plugin instance, so it's important to call the base function from your plugin's destroy method.

$.widget( "nmk.progressbar", {
	options: {
		value: 0
	},
	_create: function() {
		this.element.addClass( "progressbar" );
		this._update();
	},
	_setOption: function( key, value ) {
		this.options[ key ] = value;
		this._update();
	},
	_update: function() {
		var progress = this.options.value + "%";
		this.element.text( progress );
		if ( this.options.value == 100 ) {
			this._trigger( "complete", null, { value: 100 } );
		}
	},
	destroy: function() {
		this.element
			.removeClass( "progressbar" )
			.text("");

		// call the base destroy function
		$.Widget.prototype.destroy.call( this );
	}
});

Closing comments

The widget factory is only one way of creating stateful plugins. There are a few different models that can be used and each have their own advantages and disadvantages. The widget factory solves lots of common problems for you and can greatly improve productivity, it also greatly improves code reuse, making it a great fit for jQuery UI as well as many other stateful plugins.

You may have noticed that in this article we used the nmk namespace. The ui namespace is reserved for official jQuery UI plugins. When building your own plugins, you should create your own namespace. This makes it clear where the plugin came from and if it is part of a larger collection.

View this example in a new window

History of jQuery.noConflict()

jQuery.noConflict() was added in v1.1 to support loading jQuery on a page with other code that uses the global $ variable. In this version, the only thing that jQuery.noConflict() did was revert the $ variable to what it was before jQuery was loaded. In v1.1.1, this function was modified to also return the jQuery object so that you could assign jQuery to another variable (though it was still also assigned to the global jQuery variable). v1.1.4 introduced a boolean parameter for jQuery.noConflict() to indicate whether the global jQuery variable should be reverted; this option was added to make it easy to load multiple versions of jQuery on the same page.

Using jQuery.noConflict()

Using jQuery.noConflict() to load multiple versions of jQuery is actually pretty simple. There’s essentially just one rule: load your plugins in the correct order. In order for this to work, you have to include one version of jQuery and all of the plugins for that version before including the next version and all of its plugins. You can call jQuery.noConflict() immediately before including the second version or after you have included all the plugins for the second version. Both methods will have the same final outcome, but it may be easier to keep track of what’s going on if you call jQuery.noConflict() immediately before loading the next version in the unlikely event that you need to include more than two versions of jQuery on the same page. Because this method is slightly easier to follow, we’ll use it in our example.

First we need to load both versions of jQuery:

Now we can use either version of jQuery by using the two new variables we’ve created:

jQuery_1_1_3('Use jQuery 1.1.3')
	.click(function() {
		alert('Top: ' + jQuery_1_1_3(this).offset().top + '\n' +
			'jQuery: ' + jQuery_1_1_3.fn.jquery);
	})
	.appendTo('body');

This is great, but you’re probably looking at that code and thinking “I wish I could still use the $ variable.” Well, with a little help from a self-executing anonymous function, you can!

(function($) {
	$('Use jQuery 1.1.3')
		.click(function() {
			alert('Top: ' + $(this).offset().top + '\n' +
				'jQuery: ' + $.fn.jquery);
		})
		.appendTo('body');
})(jQuery_1_1_3);

This is a pattern you’ll see in a lot of plugins (in fact it’s part of what makes this whole thing work). We’ve created a function that accepts a single parameter, $, and we call that function as soon as we define it, passing our jQuery object to it. Now we can reference our jQuery object as $ inside this function. This makes it very easy to rename your global jQuery object while keeping your existing code working with minimal modifications.

View this example in a new window

On-demand page loading

In order to create the dialog on the first click, we’ll take advantage of jQuery’s .one() event binding method. .one() binds a handler to an event, but the handler is only ever run once. Immediately after the handler runs it unbinds itself, preventing further execution. We’ll adapt the example from the previous article to take advantage of .one():

$(document).ready(function() {
	$('#page-help').each(function() {
		var $dialog = $('
');
		var $link = $(this).one('click', function() {
			$dialog
				.load($link.attr('href'))
				.dialog({
					title: $link.attr('title'),
					width: 500,
					height: 300
				});

			$link.click(function() {
				$dialog.dialog('open');

				return false;
			});

			return false;
		});
	});
});

Adding the final touch

Now that we’ve got our dialogs loading on demand, we need to account for network latency, slow connections, etc. Previously we were loading the page contents before the user ever saw the dialog, so any delay was hidden. A simple solution for this is to just show a loading image inside the dialog until the page contents are loaded. We’ll load this image immediately on document ready to make sure that it’s ready for use when the user clicks the link to open the dialog. Loading images are generally very small in terms of file size and they can be cached by the user, so the overhead of loading the image up-front is negligible.

$(document).ready(function() {
	var $loading = $('');

	$('#page-help').each(function() {
		var $dialog = $('
')
			.append($loading.clone());
		var $link = $(this).one('click', function() {
			$dialog
				.load($link.attr('href'))
				.dialog({
					title: $link.attr('title'),
					width: 500,
					height: 300
				});

			$link.click(function() {
				$dialog.dialog('open');

				return false;
			});

			return false;
		});
	});
});

View this example in a new window

what is this?

Making it better

The one thing that this code has going for it is that users without JavaScript will still be able to get to the page with the help content. Of course, a better implementation would move the JavaScript out of the HTML, properly separating content from behavior.  We can spruce this up by loading the content into a dialog instead of a new window:

$(document).ready(function() {
	$('#page-help').each(function() {
		var $link = $(this);
		var $dialog = $('
')
			.load($link.attr('href'))
			.dialog({
				autoOpen: false,
				title: $link.attr('title'),
				width: 500,
				height: 300
			});

		$link.click(function() {
			$dialog.dialog('open');

			return false;
		});
	});
});

How it works

We’re finding the link, loading the contents of the linked page into a div and creating a dialog from that div.  We then bind a click event to the link to show the dialog.  This code by itself will work in many situations.  However, the page you’re linking to may have a heading that you’re already reproducing with the dialog title.  There may also be other elements on the page that won’t make sense in a popup, such as navigational elements or a page footer.  Luckily the .load() function allows us to pass in a selector to find the contents that we care about.  In this example we’ll assume the main content of the page is in a div with an id of content.

$(document).ready(function() {
	$('#page-help').each(function() {
		var $link = $(this);
		var $dialog = $('
')
			.load($link.attr('href') + ' #content')
			.dialog({
				autoOpen: false,
				title: $link.attr('title'),
				width: 500,
				height: 300
			});

		$link.click(function() {
			$dialog.dialog('open');

			return false;
		});
	});
});

View this example in a new window

Problem:

All jQuery UI plugins maintain state, such as the current option values, whether the plugin is enabled or disabled, which plugins have been initialized on the element, etc.  This state persists from the time the plugin is instantiated on the element until it is destroyed, either explicitly by the user calling .pluginName('destroy') or by removing the element (or one of its ancestors) via .remove().  Because of this state management, you cannot instantiate the same plugin on an element multiple times, unless you destroy the plugin instance first.

The problem that users often encounter with dialogs is that they try to instantiate a new dialog every time the user performs some action (generally clicking a link or a button).  This is an understandable mistake because at first glance it seems like calling .dialog() on an element is what causes the dialog to open.  In reality what is happening is that a new dialog instance is being created and then that instance is being opened immediately after instantiation.  The reason that the dialog opens is because dialogs have an autoOpen option, which defaults to true.  So when a user calls .dialog() on an element twice, the second call is ignored because the dialog has already been instantiated on that element.

Solution:

The simple solution to this problem is to instantiate the dialog with autoOpen set to false and then call .dialog('open') in the event handler.

$(document).ready(function() {
	var $dialog = $('
')
		.html('This dialog will show every time!')
		.dialog({
			autoOpen: false,
			title: 'Basic Dialog'
		});

	$('#opener').click(function() {
		$dialog.dialog('open');
		// prevent the default action, e.g., following a link
		return false;
	});
});

View this example in a new window