Brandon Aaron

Dimensions Now in jQuery Core

Brandon Aaron — Sat, 10 May 2008 01:51:58 +0000

The Dimensions plugin was originally started by Paul Bakaus. By popular demand my offset plugin was merged with the Dimensions plugin. From that point on I contributed several other methods to Dimensions and helped maintain the plugin with Paul. Dimensions became one of the most widely depended on plugins by developers and other plugins. It was a very common request to have Dimensions moved into the core to help relieve plugin dependency issues. We started by moving the most popular methods into the core but that wasn’t enough. The plugin was still a very common dependency. As of SVN Revision 5345 the Dimensions plugin has been merged into the jQuery core. You can find the documentation for the current Dimensions plugin on the jQuery documentation wiki.

Getting the Scrollbar Width

Brandon Aaron — Sat, 10 May 2008 01:03:56 +0000

I've been asked a few times if Dimensions would provide a method for getting the scrollbar width. In Dimensions 1.0 I created an internal method for finding the scrollbar width to hack around some browser limitations. I eventually found other ways around those limitations and that code is no longer in Dimensions. I know that in some unusual cases it can be useful, so I want to go ahead and provide that code as one of my jQuery snippets. It is just a single method added to the jQuery namespace called getScrollbarWidth.

$.getScrollbarWidth();

Here is an example of it and here is the small script.

jQuery.batch Plugin

Brandon Aaron — Fri, 09 May 2008 03:26:04 +0000

jQuery methods, in most cases, operate on zero or more matched elements. Getter type methods are an exception. The getter methods only return the results for the first matched element. This is overwhelmingly the typical use-case. However, sometimes you might want to get the results for all matched elements in the jQuery collection. Introducing jQuery.batch, a small extension to jQuery that adds such functionality.

jQuery.batch extends the core with plural forms of the getter methods. Methods like attr now have a sibling named attrs. These new methods operate on the whole jQuery collection, returning an array of results. Here are the pluralized methods that jQuery.batch provides.

attrs
styles
widths
heights
vals
texts
htmls

In addition with the core methods the jQuery.batch plugin offers its own plugin method: jQuery.fn.batch. This method takes the name of an existing plugin/method attached to jQuery.fn along with any additional arguments to pass along.

$('a').batch('attr', 'href');

Of course since jQuery.batch already provides the attrs method that could also be written as.

$('a').attrs('href');

Plugin Integration

jQuery.batch makes it easy to integrate with plugins to provide a pluralized sibling by using a method called jQuery.batch.registerPlugin. For example here is the line used within the plugin to register the core methods.

$.batch.registerPlugin( 'attr', ['css','styles'], 'offset', 'width', 'height', 'html', 'text', 'val' );

Basically it is just an argument list of method names. Notice that I passed an array for the css method to manually set the pluralized name to something more desirable. Otherwise, it will just append an 's' to the end of the method name.

Get jQuery.batch

You can download, log issues and create feature requests at the plugins home: http://plugins.jquery.com/project/batch

New Plugin: Live Query

Brandon Aaron — Mon, 20 Aug 2007 04:53:58 +0000

Live Query, previously called Behavior, utilizes the power of jQuery selectors by binding events or firing callbacks for matched elements auto-magically, even after the page has been loaded and the DOM updated.

For example you could use the following code to bind a click event to all A tags, even any A tags you might add via AJAX or a script.

$('a')
.livequery('click', function(event) {
alert('clicked');
return false;
});

Once you add new A tags to the document, Live Query will bind the click event and there is nothing else that needs to be called or done.

When an element no longer matches a selector the events Live Query bound to it are unbound. Also, the Live Query can be expired by calling expire which will no longer bind anymore events and unbind all the events it previously bound.

Live Query can even be used with the more powerful jQuery selectors. The following Live Query will match and bind a click event to all A tags that have a rel attribute with the word "friend" in it. If one of the A tags is modified by removing the word "friend" from the rel attribute, the click event will be unbound since it is no longer matched by the Live Query.

$('a[@rel*=friend]')
.livequery('click', function(event) {
doSomething();
});

Live Query also has the ability to fire a callback function when it matches a new element and another callback function for when an element is no longer matched. This provides ultimate flexibility and untold use-cases. For example the following code uses a function based Live Query to implement the jQuery hover helper method and remove it when the element is no longer matched.

$('li')
.livequery(function(){
$(this)
.hover(function() {
$(this).addClass('hover');
}, function() {
$(this).removeClass('hover');
});
}, function() {
$(this)
.unbind('mouseover')
.unbind('mouseout');
});

See It In Action

I've put together two simple demos that utilize both an event based and function based Live Query on unordered lists.

Get Live Query

Live Query can be downloaded from the Live Query project page. The Live Query documentation is a work in progress but the API is fully documented.

Dimensions 1.1.2

Brandon Aaron — Fri, 17 Aug 2007 18:35:13 +0000

Release early, release often. In the 1.1.1 update there was a regression in Safari with calculating the window width and height. I also fixed a bug in getting the offset of table cells with borders in Mozilla. As usual, you can report bugs, request features and download Dimensions 1.1.2 from the Dimensions project page.

Dimensions 1.1.1

Brandon Aaron — Fri, 17 Aug 2007 14:32:26 +0000

I just released Dimensions 1.1.1 which fixes up an issue when trying to get the document width and height. Grab the zip from the Dimensions project page.

Dimensions 1.1

Brandon Aaron — Mon, 13 Aug 2007 04:32:03 +0000

I just released Dimensions 1.1. It includes a new option to include margins for the outerWidth and outerHeight methods. I've also fixed the issues with Safari 3 and the offset method. This update does require jQuery 1.1.3 or greater. Feel free to grab the zip from the Dimensions project page. Oh and the docs have been updated for 1.1.

Dimensions 1.0.1

Brandon Aaron — Thu, 26 Jul 2007 03:26:57 +0000

I just released Dimensions 1.0.1. It fixes an issue with fixed position elements in Opera and makes it easier to run the test suite locally.

You can download the zip from the Dimensions project page.

Dimensions 1.0

Brandon Aaron — Sun, 22 Jul 2007 23:11:55 +0000

Dimensions 1.0 is final! This is a very big release for Dimensions and includes a lot of bug fixes, new features, an automated test suite and docs. Yup, even docs! So what new features have been added to Dimensions in 1.0?

A position method to get the positioned offset.
An offsetParent method to get the positioned parent.
The scrollTop and scrollLeft methods can now set the value as well as get the value of the scroll offsets.
The offset method has some new options:
- A relativeTo option that provides a way to get the offset relative to a parent element.
- A lite option that provides a very fast way to get the offset but at the price of accuracy when borders and margins are involved.

Lots of testing has gone into the 1.0 release and lots of bugs have been fixed and browser issues have been normalized. For example, Firefox and Opera include the width of the scroll bar when getting the width/height of the window unlike the other browsers. This issue has been normalized in Dimensions and you can count on getting accurate results cross-browser.

An Example

The Dimensions plugin is built to get accurate results and stay out of your way. For example the position method returns an object with a top and left property. This allows us to pass the result directly to the css. Lets say we wanted to make a static element positioned absolute but so that it stays exactly where it was when static.

var css = { position: 'absolute' };
$('#myElement').position(css).css(css);

With just two simple lines of code we can make an element absolutely positioned! In this example I took advantage of the ability to pass in an object to the position method so that I could continue the jQuery chain. I plan on writing about more ways to use the dimensions plugin. So be sure to grab the RSS feed (if you haven't already) to stay up-to-date!

Get Dimensions 1.0

The Dimensions plugin can be downloaded from the Dimensions project page. The zip contains the full source, a minified version and a packed version. You can also grab the latest from SVN http://jqueryjs.googlecode.com/svn/trunk/plugins/dimensions/.

Support, Bugs and Feature Requests

The Dimensions project page has a place to report bugs, issues and request features.

Dimensions 1.0rc1

Brandon Aaron — Mon, 02 Jul 2007 02:10:09 +0000

Hot on the heels of the jQuery 1.1.3 release, here is Dimensions 1.0 release candidate 1! Dimensions 1.0rc1 includes several key new features.

A new method, called position, to get the positioned offset of an element
A new lite option to the offset method that runs much faster
The offset method now works on the body element
The scrollTop and scrollLeft methods are now setters and getters
A new test suite
Updated documentation
And lots of bug fixes

Still to come are more documentation and examples! You can grab Dimensions 1.0rc1 from the Dimensions project page.