Introduction to SEO

View more presentations from randfish.

More info from the original SEOMoz blog post.

Update: “not a bug, it’s a feature”! See below for more, but the gist of it is that Firefox’s behaviour here is right according to the HTML 5 specs, but not according to the HTML 4.01 specs…

The problem change

Firefox 4.0 beta — as well as IE and Opera — do not send name/value for input type=”image”; only .x and .y coordinates are sent.

Note, this is when clicking the input image with a mouse. When navigating using keyboard, focusing on it, and pressing enter, then the name does get submitted.

Earlier Firefox, Chrome (latest) do send name/value, which is what we’d expect…

Example

This form submits using a GET so you can see the submitted name/value pairs in the querystring:

What does W3C spec say?

17.4.1 Control types created with INPUT says this for input type image:

When a pointing device is used to click on the image, the form is submitted and the click coordinates passed to the server. The x value is measured in pixels from the left of the image, and the y value in pixels from the top of the image. The submitted data includes name.x=x-value and name.y=y-value where “name” is the value of the name attribute, and x-value and y-value are the x and y coordinate values, respectively.

The previous quote implies name=value should not be sent for input type=image

But 17.4 The Input Element says this as part of the input name attribute formal definition:

 name        CDATA          #IMPLIED  -- submit as part of form --

That implies the name should be submitted too, even for input type=image (and assuming that, then the value of the input should be submitted too, which seems to be confirmed by section 17.13.2 Successful controls in the spec, which notes: A successful control is “valid” for submission. Every successful control has its control name paired with its current value as part of the submitted form data set.)

So, I think Firefox 4 has introduced a bug…?

Update: not a bug

The bug I raised has been updated and turns out that this is per HTML 5 spec, while I was comparing what I saw with the implementations in earlier versions of Firefox and with the HTML 4.01 spec…

IE (and Opera) also only send .x and .y, so I guess they settled on that given most sites are probably still catered for/assume IE as the predominant browser…

Workarounds

One possible workaround is this, but ugly:

1. Detect the browsers to do this for (feature detection would be better…)
2. Capture the form submit event and find the button that caused this, or capture the button click event
3. Append a hidden input like this (jQuery example, assuming button is the button you have captured):

   $(form).append('<input type="hidden" name="' + button.name + '" value="' + button.name + '" />').submit();

If you’ve already been working around this for IE, as the problem has been there for ages, then apply this for firefox 4 too (annoying and ugly to do browser specific code, I know)

Third workaround: don’t use input type=image, use input type=submit + CSS, or button etc.

When transforming XML via XSLT, make sure the output setting for indenting is turned off and honoured by your code.

Turning it off will

• Speed up the transform time
• Reduce the output size

How is XSLT output indent turned off?

Indenting output should be off by default. If for whatever reason it is not, it can be turned off simply by using this:

<xsl:output indent="no" />

I have seen a lot of .NET XSLT ignore this important setting. Sometimes it is because the output is written to a stream or something else which doesn’t take the output settings from the XSLT.

When transforming to an XmlWriter in .NET, be sure to correctly create the XML Writer using the overload that takes in output settings obtained from a loaded XSLT. E.g:

XslCompiledTransform xslt = GetXslt(XsltPath);

// The 2nd argument honours XSLT the output settings!
using (XmlWriter w = XmlWriter.Create(sb, xslt.OutputSettings))
{
    XsltArgumentList args = GetXsltArgs();

    XPathNavigator navigator = _someXmlData.CreateNavigator();

    if (navigator == null)
        throw new NullReferenceException("navigator");

    if (w == null)
        throw new NullReferenceException("w");

    xslt.Transform(navigator, args, w);
}

(xsl:output has many other useful attributes worth looking into.)

What kind of savings do you get?

The savings will differ for many reasons (the XML document size, the structure of the XML, the types of transformation being done etc etc), so it is hard to give a definitive savings. But here’s an illustrative example:

A few weeks back, a colleague at work was having trouble with an XSLT that was taking a long time to transform.

We started to have a look; I was expecting to find inefficient XPath, or an XML document structure that wasn’t conducive to decent transformation speed, or something like that.

However, I noticed the first thing was his output was set to be indented, and the XML input was HUGE.

So, the first thing we did was turn it off.

That alone reduced a 12 minute transform (on a 300MB document) to just 1 minute!

In another scenario, a 70K XML document was taking about 0.25 seconds to transform. Turning off indenting shaved a few more milliseconds (can’t remember exact amount now) — and saved about 2K in the output HTML that it generated.

Why can this make such a difference?

I think the specifics may vary depending on the XSLT parser you are using, but I believe it is basically this:

• Each newline/white space/tab(s) created for the indent requires an extra text node to contain these characters which requires extra memory (though at this point may not add that much time to the transformation).
• When the transform is then saved to a file, or written out to an output stream strings are often involved. String processing can be expensive in many programming languages, so each of these indented text nodes needs handling. For very large documents (as above) this can require a lot of unnecessary processing.

But doesn’t this make the output harder to read?

The consumer of a transformation result is likely to be another process such as another XSLT in a pipeline, another process, or even a web browser.

None of these typically care about the extra white space, which also would require more processing when loading.

If you need to view the XML, it may be worth keeping the indent off and manually opening it in a text editor that has the ability to “pretty print” it for you. (Warning: some editors and IDEs, e.g. Visual Studio, can do automatically pretty print an XML document for you when you open it, making you think the XML itself had the indented output!)

Other savings are still possible

Turning off the indent is just one of many things you can look into. Other things include the following (though your mileage may vary):

• Use attributes instead of elements (where possible; usually this is for simple values, such as numbers, dates, and very limited strings, and where the element is not expected to be indented)
• Look at the XML structure to see if can be improved to make XSLT processing easier
• Cache the XSLT Processor
• Cache the output

I’ll try to expand on some of those in future posts.

Some more detailed XSLT performance tips which also created cleaner code were covered in an earlier post.

Unfortunately inner elements can break rounded borders as Richard Rutter described when using <img> elements inside an element with border-radius. He also provided a useful solution which is webkit only, unfortunately.

Inner elements with background colors can also break border-radius. But there is a way around that too: apply border-radius to the offending inner elements too.

The problem

Here’s an example (view in Firefox 2+ or Safari/Chrome) where border-radius gets broken:

(If you are reading this in an RSS feed reader, you might need to go to the page to see the example properly)

A div containing a blockquote and a paragraph to mention the source of the quote:

Notice the bottom corners aren’t right: the background of the source paragraph breaks through the rounded corners.

The rounded corners are achieved using something like this:

.blockquote-with-source {
  border:1px solid #e8eac8;
  border-radius:10px;
  -moz-border-radius:10px;
  -webkit-border-radius:10px;
}

(The above code is of course slightly more than necessary due to both mozilla and webkit implementing them via their rendering prefixes.)

The ideal solution

overflow:hidden on inner elements should do the trick, but doesn’t work in Safari, Chrome or Firefox (although will work for the webkit-based ones for images as Richard Rutter points out in the above link).

Workaround for non-image elements with backgrounds

There are a few ways to work around this:

Apply border-radius to the inner element breaking the rounded corners

If you are using background color (or background image) on the inner HTML element, you can apply border-radius to them too:

In the case of the above example, we just need rounded corners on the bottom left and bottom right of the source paragraph:

.source {
    border-radius-bottomleft:10px;
    border-radius-bottomright:10px;
    -moz-border-radius-bottomleft:10px;
    -moz-border-radius-bottomright:10px;
    -webkit-border-bottom-left-radius:10px;
    -webkit-border-bottom-right-radius:10px;
}

The final styled quote would then look like this:

(If you inspect the above with Firebug or equivalent, you’ll notice I used slightly different CSS classes so it just fits with the current theme on this blog, but the principle is the same.)

Drawback to the above workaround

The main one I can think of is that you have to maintain the border radius value in more than one place — CSS variables would be nice here

Thick enough borders hide the problem

If your design allows it, thick borders on the element using border-radius may do the trick.

In the example below, I use a thick border on the left side of the containing div, with border radius only on the bottom right of the source paragraph:

The thickness of the border is the same as the size of the radius, though you don’t have to do that.

Drawback to the above workaround

When using one thick border as above, it doesn’t render as nicely in webkit as it does in gecko. Don’t know if that is vagueness in the spec, or what…

However, if all four borders are given the same width, then it seems ok.

Workaround for image elements

As Richard Rutter commented, putting an image as a CSS background image would do the trick, but that isn’t always ideal or possible (e.g. an image that is important as part of the content is better marked up as <img>).

Are there other, perhaps better, ways to deal with this?

Web standards is generally a good thing. When done well, it can help to create lean pages, improve markup quality, provide better accessibility and can be easier to maintain (even while supporting IE6!)

One claim often made in the past to promote web standards is that following web standards (using CSS-based layouts, proper use of heading elements in markup, etc) will improve SEO.

Though this might be desirable, it is not the case; most sites on the web don’t follow web standards and most rank very high in their areas. Search engines are not going to penalize the 90+ % of sites that don’t follow web standards; that’s like shooting themselves in the foot!

As I describe in an earlier post on search engine ranking vs indexing while there are technical things one can do to ensure the site gets indexed well (e.g. URL canonicalization, good use of the <title /> element, etc), for ranking it is mostly about having good content that people will link to.

But as Matt Cutts, head of Google’s web spam team notes in this very short video, using CSS-based layouts or table-based layouts will have no bearing on search engine friendliness:

There are many good reasons to follow web standards principles, to use CSS-based layout and progressive enhancement but SEO, unfortunately, is not one of them.

Update 30 June 2009: A couple of decent articles recently talk about similar things:

1. SEO Best Practices: SEOmoz’s New Policies Based on Updated Correlation Data
2. The Triviality of On-Page HTML Tag Optimization
   

Still, I have been using display:table on a much larger site for about 6 months now, so I thought I might as well post this as it is, and perhaps follow up with more examples later.

Also, about 3 weeks after I started this draft, Rachel Andrew and Kevin Yank wrote a book on CSS display:table for layout, as well as a useful summary article! I do recommend looking at that article for finer details.

No need for css float for layout in modern browsers

For a few years now, web developers doing CSS-based layouts have used floats or absolute positioning for layout web sites to avoid using non-semantic HTML <table>s.

While doable, extra hoops often have to be jumped through (mostly for IE) and some seemingly simple things can be harder than necessary (like equal height columns).

However, for a simpler solution, CSS-based display:table, display:table-row, display:table-cell etc are all usable today across Firefox 2+, Safari 3+, Opera 9+ and IE8.

Example:

Consider the following HTML:

<body>
	<div id="header">
		<!-- header -->
	</div>

	<div id="content-body-wrapper">
		<div id="content-body">
			<div id="primary-nav">
				<!-- some navigation column here -->
			</div>
			<div id="secondary-nav">
				<!-- some additional column here -->
			</div>
			<div id="content">
				<!-- main content here -->
			</div>
		</div>
	</div>

	<div id="footer">
		<!-- footer -->
	</div>
</body>

And the CSS to style it to get equal height columns:

#content-body-wrapper {
    display:table;
    border-collapse:collapse;
}

#content-body {
    display:table-row;
}

#primary-nav, #secondary-nav, #content {
    display:table-cell;
}

#primary-nav, #secondary-nav {
    width:20%;
}

#content {
    width:60%;
}

And that’s it!

The above is just the layout bit of the CSS. Here are some screenshots (click for full size) with content and very basic styling just to see the equal height column effect:

The first is with Firefox 3 and the second with IE8.

You can actually omit extra divs, even the one that gets display:table and the browser is required to create an anonymous table for you.

Isn’t using table for layout wrong?

This is not the same as using the structural html table elements for layout purposes — that indeed is an inappropriate use for tables.

This is using CSS to give table-like display, which is fine as it leaves the HTML (and document structure) in tact.

What about IE 7 and 6?

IE7 and 6 of course remain problems, but you can use conditional comments and give them older techniques that attempt to achieve this.

Some limitations or issues

Some limitations of css display:table I have come across, however, include these:

• Lack of colspan/rowspan equivalents
• Like HTML tables, a CSS cell can expand in width based on content (as well as height).

On the last one I noticed this when using things like <pre> even with overflow:auto with the thought that just like inside floated columns with widths assigned this would result in those <pre> blocks getting horizontal scrolls if they became too wide.

Instead, as with HTML tables, they push out the cell they are in. The only workaround I knew to this was to give a px or em width to such elements. (It also applies to large images in a cell.)

That being said, display:table seems a lot cleaner!

CSS3 has an advanced layout module in the works but there are not any browser implementations of it (that I am aware of), so in the interim this could be a useful approach.

More info

• W3C specifications on CSS display:table
• Rachel Andrew: Everything you know about CSS is wrong

Translations

Update: May 2010. Translated into Belorussian, by Ucallweconn

A CDN is a network of servers around the world to serve content from your site from the nearest physical location. All the large sites (Yahoo, Google, Amazon, etc) use them.

After reading the above post, I was also curious to find out how if Google App Engine helps in the following:

• Compression
• Expires headers and versioning

A comment in the original post implies compression is on by default, which is what I’d expect.

Using far future expires headers can be a great performance boost for your site, and is easy to apply to assets such as images, CSS, and JavaScript files.

At the same time, if you change such a file you want to be sure your repeat visitors will not see the old one because it was cached far into the future.

So, with a simple URL Rewrite Rule we can make things like /css/version-1/site.css point to /css/site.css.

If you update site.css, you can change the version number. Browsers will not have a file from this new path in their cache so will download it and cache it into the future again.

Is it possible to do this with Google App Engine? It looks promising…

If I can find a spare moment, I may try this out on this site (which, admittedly doesn’t get that much traffic to make it worth bothering about!) — and then I’ll try it on a site that takes up most of my spare time, which gets a LOT of traffic, where it would actually be worth doing!

So, following on from my recent post about turning jQuery code into richer, unit testable plugin code, I thought I’d describe the quick process of doing so here. (It’s worth reading Snook’s post first though!)

The general steps discussed to achieve this are as follows:

1. Add additional keyboard accessibility
2. A first attempt plugin
3. A plugin that might be unit testable

Add additional keyboard accessibility

I posted a comment on Snook’s post to say additional hover and blur events should do the trick, so here is an example applied to one of the four demo menus he had with those events added:

$('#d a')
    .css( {backgroundPosition: "0 0"} )
    .mouseover(function(){
        $(this).stop().animate({backgroundPosition:"(0 -250px)"}, {duration:500})
    })
    .mouseout(function(){
        $(this).stop().animate({backgroundPosition:"(0 0)"}, {duration:500})
    })
// I added these event handlers:
    .focus(function(){
        $(this).stop().animate({backgroundPosition:"(0 -250px)"}, {duration:500})
    })
    .blur(function(){
        $(this).stop().animate({backgroundPosition:"(0 0)"}, {duration:500})
    })

A first attempt plugin

The above code as a plugin might look something like this:

(function($) {
    $.fn.animatedBackground = function(options) {

    // build main options before element iteration by extending the default ones
    var opts = $.extend({}, $.fn.animatedBackground.defaults, options);

    function startAnimation() {
        $(this).stop().animate(
           {backgroundPosition:opts.backgroundPositionStart},
           {duration:opts.duration}
        );
    }

    function stopAnimation() {
        var animationConfig = { duration:opts.duration };
        if (opts.complete)
            animationConfig.complete = opts.complete;

        $(this).stop().animate(
            {backgroundPosition:opts.backgroundPositionEnd},
            animationConfig
        );
    }

    // for each side note, do the magic.
    return $(this)
        .css( {backgroundPosition: opts.backgroundPositionInit} )
        .mouseover(startAnimation)
        .mouseout(stopAnimation)
        .focus(startAnimation)
        .blur(stopAnimation)
    };

    // plugin defaults
    $.fn.animatedBackground.defaults = {
        backgroundPositionInit : "0 0",
        backgroundPositionStart : "(0 0)",
        backgroundPositionEnd : "(0 0)",
        durationStart : 500,
        durationEnd : 500,
        complete : null
    };
})(jQuery);

The above is just a quick 2 minute thing — I am sure with more thought the plugin options could be made even more flexible. But this will do for the purpose of this post.

For each of the 4 demo menus Snook provided, you could then call them as follows:

$(function(){
    $('#a a')
        .animatedBackground(
            {
                backgroundPositionInit : "-20px 35px",
                backgroundPositionStart : "(-20px 94px)",
                backgroundPositionEnd : "(40px 35px)",
                durationEnd : 200,
                complete : function(){
                    $(this).css({backgroundPosition: "-20px 35px"});
                }
            }
        );

    $('#b a')
        .animatedBackground(
            {
                backgroundPositionStart : "(-150px 0)",
                backgroundPositionEnd : "(-300px 0)",
                durationEnd : 200,
                complete : function(){
                    $(this).css({backgroundPosition: "0 0"});
                }
            }
        );

    $('#c a, #d a')
        .animatedBackground(
            { backgroundPositionStart : "(0 -250px)" }
        );
});

(Examples c and d are combined with one selector, while a and b each have more complex options.)

In the “simple” cases (c and d) a very small amount of code is needed to use the plugin. For (a and b) if you were only going to use this once, it might be questionable whether the plugin for this is worth the effort!

Unit testable plugin?

Some plugins might be so small that unit testing them may not seem beneficial or worth the effort. In this particular case, it is not clear if it is necessary. However, for the purpose of this post at least it may be a useful exercise. So, these might be some things to bear in mind:

• The bulk of the plugin relies on animate() which works asynchronously. Unit testing asynchronous calls can be tricky with QUnit. More importantly, we are not trying to unit test animate() but our plugin code instead.
• The function handler for each mouse/focus/blur event could be made into a default plugin function
• Unit tests can then replace the default function with a mock function to confirm that the rest of the plugin works with the various configuration options passed in.

To achieve the above, a simple step might just be to make the private startAnimation() and stopAnimation() methods public.

This can be done a few ways, e.g. keep those private methods and make them call the public ones, or wherever the private ones are called, make them call the public ones, etc.

The two public methods would look something like this:

$.fn.animatedBackground.startAnimation = function($el, opts) {
    $el.stop().animate(
        {backgroundPosition:opts.backgroundPositionEnd},
        {duration:opts.duration}
    );
}

$.fn.animatedBackground.stopAnimation = function($el, opts) {
    var animationConfig = { duration:opts.duration };
    if (opts.complete)
        animationConfig.complete = opts.complete;

    $el.stop().animate(
        {backgroundPosition:opts.backgroundPositionEnd},
        animationConfig
    );
}

Here’s a page with a unit testable version of the plugin which also has the original menu examples

Was it worth adding extra code to make it unit testable?

The testable plugin version is a bit larger than the original (ignoring minification and gzipping benefits to remove a lot of the difference).

Was it therefore worth changing in this way from the original?

In my opinion, the initial plugin version would probably suffice, especially if likely to be used across a few small projects.

If, on the other hand, you were going to use it in a more critical scenario, then unit testing what you can could be useful.

A principle of test driven development is to write unit tests first. In this case as it was existing code, it seemed okay to do it in the order described above. Furthermore, sometimes it feels tricky to always stick to that principle religiously, and writing unit tests afterwords might be okay if the plugin is smallish, perhaps?

Summary

So, many thanks for Jonathan Snook for his post. That technique is useful for me in some other projects.

This post hopefully shows that even small snippets of code can be turned into a plugin, sometimes unit testable ones. Whether that is worth your efforts depends on your need and audience.

It’s by-line of “write less, do more” really seems apt.

But sometimes, by writing just that little bit extra, you can do even more.

For example, I often try to do the following:

• Make most jQuery code into reusable plugins
• Use the jQuery plugin development pattern for added flexibility
• Use QUnit to unit test JavaScript
• Combine the two approaches to drive out a richer API for the plugin

By unit testing with QUnit, I find I often need to trigger additional events or add additional code from within the plugin so the test can be meaningful.

But this extra code isn’t only useful for testing, it becomes a useful part of the plugin’s API, improving its functionality and flexibility without sacrificing maintainability and readability of the code.

I’ll try to demonstrate that in this post.

Make most of your jQuery code into reusable plugins

In many cases, where there is a block of jQuery code initializing something, it is a candidate for a plugin.

It took me a little while before I gave jquery plugins a go, thinking it will be complex and I won’t have time. But, it turns out to be really simple, elegant and useful for both simple and complicated scenarios.

Example to create a dynamic side note toggler

Lets take a simple example for illustration: suppose I have some HTML that acts as an aside, or side note, and that I want to toggle its appearance.

Lets say we agree this kind of HTML format for it (or microformat):

<p>Some text before the side note.</p>

<div class="side-note">
	<p>Any HTML could go here including</p>
	<ul>
		<li>Bulleted lists</li>
		<li>Tabular data</li>
		<li>Images</li>
	</ul>

	<div class="side-note">
		<p>Even nested side notes, if that is of any use!</p>
	</div>
</div>

<p>Some text after the side note.</p>

The first way I’d do it might be something like this:

$(document).ready(function() {
    $('.side-note').each(function() {
        $(this)
            .addClass('dynamic-side-note')
            .hide()
            .wrap('<div class="dynamic-side-note-container"></div>')
            .before('<h3 class="toggler"><a href="#">Side note:</a></h3>')
            .parent(0).find('> h3.toggler > a').click(function() {
                $(this).parents('.dynamic-side-note-container').eq(0).find('> .dynamic-side-note').slideToggle();
                return false;
            });
    });
});

I could have added a click event handler to the h3 header above, but using an anchor adds keyboard accessibility.

(The CSS selector could also be improved, e.g. to narrow it down to only side-notes in some content div, e.g. $('#content .side-note').)

Here is a working example

As a simple jQuery plugin

The above works. But, we can move most of the above code into a jQuery plugin.

Why bother? We can gain a bit more flexibility, such as the ability to use any selector, not rely on a side-note class. We could pass in other parameters such as what the text for the side note toggler/header should be, etc.

As a first attempt, the plugin might look something like this:

$.fn.sideNotes = function() {
    // returning this way allows chaining
    return $(this)
        .addClass('dynamic-side-note')
        .hide()
        .wrap('<div class="dynamic-side-note-container"></div>')
        .before('<h3 class="toggler"><a href="#">Side note:</a></h3>')
        .parent(0).find('> h3.toggler > a').click(function() {
            $(this).parents('.dynamic-side-note-container').eq(0).find('> .dynamic-side-note').slideToggle();
            return false;
        });
};

We then just need to invoke the plugin:

jQuery(function() {
    $('.side-note').sideNotes();
});

(Note how you could use any selector now not just .side-note as above.)

Here is a working example using the simple plugin

Plugins also make it easier to pass in more options for configuration. The next example uses a useful pattern for plugin development that also shows a nice way to handle plugin options:

Use the jQuery plugin development pattern for added flexibility

The post, A Plugin Development Pattern (for jQuery), from the Learning jQuery blog is really useful.

It provides a good way to write plugins that also get the following features:

• Configurability by passing in options
• Default options to keep invoking code small and neat
• A closure where you split your code out into manageable private functions, etc., if you need
• Ensuring that your plugin support chaining
• And more

Using some of those ideas, here is what we might come up with for the sideNotes plugin:

(function($) {
    $.fn.sideNotes = function(options) {

    // build main options before element iteration by extending the default ones
    var opts = $.extend({}, $.fn.sideNotes.defaults, options);

    // for each side note, do the magic.
    return $(this)
        .hide()
        .wrap('<div class="dynamic-side-note"></div>')
        .before('<h3 class="toggler"><a href="#">' + opts.sideNoteToggleText +'</a></h3>')
        .parent(0).find('> h3.toggler > a').click(function() {
            $(this).parents('.dynamic-side-note').eq(0).find('> .side-note').slideToggle();
            return false;
        });
    };

    // plugin defaults
    $.fn.sideNotes.defaults = {
        sideNoteToggleText : 'Side note:'
    };
})(jQuery);

And invoking the plugin is the same as before:

jQuery(function() {
    $('.side-note').sideNotes();

    // or overriding the default side note toggle text:
    // $('.side-note').sideNotes({ sideNoteToggleText : 'As an aside:' });
});

Here is a working example using the plugin pattern

Unit testing the jQuery plugin

As the plugin code is reasonably well encapsulated, we can create some unit tests for this plugin.

Unit testing jQuery (as with any code) gives you confidence in maintaining it. For example, when refactoring code, unit tests give you confidence that you can do it without breaking things. Plugins, almost by definition are good candidates for unit testing.

Examples of unit tests for this plugin

Our example side note plugin is quite simple, so the unit tests will likely be small in number. Types of tests we might include are the following:

• Test that we can expand/collapse a side note
• Test that we can expand/collapse a side note many times and ensure the toggle state reported is correct each time
• Test that when the side note plugin has run, all the side notes are collapsed initially
• Test that we can change the toggle text to something else

And so on.

Remember, the unit tests should not test the slideToggle() method we happened to use (as that should be unit tested itself, and we may use other ways of toggling the side note in the future). Instead, we just need to unit test our code and plugin functionality.

So ideally, we might even want to “mock” the slideToggle(), if necessary.

Use QUnit to unit test JavaScript

QUnit is a unit testing framework, used internally by jQuery itself for all its core JavaScript, and now opened up and documented for others to use, too. It is a simple framework to support the creation and execution of tests.

The tests are run in a browser. You could automate it against all your target browsers by using something like Selenium.

The framework is in its early days (a setup and teardown set of methods would be nice, for example), but is rich enough to get started with it.

Here is a QUnit test page for the side note plugin

(I included a manual test area as this can sometimes be useful where visual confirmation is useful or automated tests of some parts is not possible/easy. Having this all in one place can be handy.)

Using unit tests and plugins helps create a richer API for the plugin

To write testable code, you may find you need to provide more hooks in the code. Yet, you probably don’t want to pollute your code so much that it is detrimental to performance or maintainability.

Triggering events on the plugin for added flexibility

In the unit test example page, how did we manage to get unit tests to confirm a side note had been toggled when we didn’t have any callback for it?

The first idea people might have is to pass a callback that a plugin user can point to in the options when invoking the plugin, something like this:

jQuery(function() {
    $('.side-note').sideNotes(
        {
            toggled : function() { console.log('side note was toggled'); }
        }
    );
});

That looks useful; the unit test can provide a callback when it invokes the plugin.

However, that limits us to just one observer, the one that invoked the side note plugin in the first place.

But we can go one step further: trigger events. This allows more than one observer to watch for the event. This is achieved using jQuery’s trigger() and bind() methods.

By having unit tests watching for these events, it does not distort the plugin code; it enhances its API making the event useful for a real plugin user, if they need it.

In our side note plugin example, when we call slideToggle() we can trigger an event when the toggling has completed:

// all the stuff that gets to the
// slide toggle bit comes here!
.slideToggle( function() {
    $(this).trigger('sideNoteToggled');
});

If your code cares when this happens, you can bind to this event, something like this:

$('.side-note').bind('sideNoteToggled', eventHandlerGoesHere);

(A fuller example below uses trigger() to also pass the expanded/collapsed state in conjunction with some ARIA information.)

Providing default implementations that can be replaced (or mocked for unit testing)

One particular challenge I had with unit testing this side note example was that the slideToggle() method used by the plugin, internally runs asynchronously (using setTimeout etc).

Writing normal unit test code means the test can finish before the animation has run.

Even though I tried to use setTimeout() on the tests themselves to try and make them wait for the sideNote to finish toggling, and passing in the fastest speed possible to the slideToggle method, it wasn’t always right, and not consistent across all browsers.

This gave me the opportunity to do a few things:

• Encapsulate the call to slideToggle in another method
• Make that method the default implementation, but overrideable
• Use this to provide a mock slide toggler for testing purposes

With jQuery’s plugin architecture providing a default implementation is quite straight forward:

$.fn.sideNotes.toggle = function() {
    $(this).slideToggle(function() {
        $(this).trigger('sideNoteToggled');
    });
};

Mocking the slideToggle() call is nice because we don’t want to test external code in our unit tests; that should have been unit tested by whoever wrote that (the jQuery team I imagine! I’ll have to look at their unit tests when I get a moment to see how they overcome asynchronous issue — there is some mechanism to provide stop() and start() methods for AJAX testing and I tried this here, but still wasn’t getting consistent results).

In our example, we can overwrite the the default toggle method to simply use toggle() instead of slideToggle(), which is a non-animated version that runs and completes immediately.

This makes writing the testing code a bit simpler too. (There are one or two bits that I did that didn’t feel too great in my opinion, such as the way I chose to expose the post toggle action, but that is perhaps for another day to sort out!)

To override the default implementation, you can redefine sideNotes.toggle in your code, something like this:

$.fn.sideNotes.toggle = function() {
    $(this).toggle().trigger('sideNoteToggled');
};

Example QUnit test code

So taking the above considerations this is what we might have in our QUnit unit test code:

This code block shows a test util object to help instrument the test, and then at the bottom, an example of a mock object to replace the slideToggle() call.

(function(){
    var testUtils = {
        isExpandedCount : 0,
        isCollapsedCount : 0,

        defaultTestOptions : {
            selector : '#example .side-note',
            sideNoteOptions : {},
            speed : 'fast'
        },

        // a crude setup like method, which QUnit currently doesn't have
        init : function(options) {
            testUtils.reset();

            var opts = $.extend({ sideNoteOptions : {} }, testUtils.defaultTestOptions, options);

            // tests assume the relevant HTML is present on the page the test is running
            $(opts.selector)
                .bind('sideNoteToggled', testUtils.sideNoteToggled)
                    .sideNotes(opts.sideNoteOptions);

            return $(opts.selector);
        },

        sideNoteToggled : function(event, isExpanded) {
            isExpanded ? testUtils.isExpandedCount++ : testUtils.isCollapsedCount++;

            $(event.target).trigger('sideNoteToggleCaptured');
        },

        // until there is an explicit tear down method this will have to do
        reset : function() {
            $('#example .side-note').unbind('sideNoteToggled');
            testUtils.isExpandedCount = 0;
            testUtils.isCollapsedCount = 0;
        }
    };

    // mock the slideToggle. We are not testing that.
    function mockSideNoteToggle() {
        $(this).toggle();

        $.fn.sideNotes.toggled.call(this);
    }

    // keep the original implementation if we want to use it later
    $.fn.sideNotes.originalToggler = $.fn.sideNotes.toggle;

    // override the default toggle method with the mock
    $.fn.sideNotes.toggle = mockSideNoteToggle;
})();

We can then write unit tests, such as this one (note this code would go inside the anonymous function used above):

module("Single toggle tests");

test("Test side note is expanded when toggled", function() {
    var $sideNote = testUtils.init();

    $sideNote.each(function() {
        equals($(this).attr('aria-expanded'), 'false', "Side not starts as collapsed");
    });

    $('#example')
        .find('.side-note:eq(0)').bind('sideNoteToggleCaptured', function() {
            equals(testUtils.isExpandedCount, 1, "A node has been expanded");
            equals(testUtils.isCollapsedCount, 0, "No nodes have been collapsed after initialization");
            equals(this['aria-expanded'], true, "Node’s aria state is expanded");
        })
        .end()
            .find('.toggler > a:eq(0)').click();
            // calling click() is like simulating the user action to start the test
});

In the above example, the following is happening:

1. The call to init() creates/initializes the sideNote plugin
2. We then assert that the ARIA state reports each side note is not expanded
3. We then find each side note and bind to the sideNoteToggleCaptured event (which is raised by the unit test utility shown earlier, not by the plugin itself)
4. We then simulate a user action by finding the toggler and clicking it
5. The simulated click() makes the plugin eventually trigger the sideNoteToggled event, which the testUtils object will catch.
6. The test util will catch that event and update the various testing counters and itself trigger the sideNoteToggleCaptured event.
7. Finally at this point, we can run our assertions, such as confirming the expected number of times the side note was expanded/collapsed and what the expected ARIA state should be (in this example seen by the use of the equals() function).

See the full example for more unit tests

The additional tests in the full example also show the side note being dynamically created per test run, so you don’t always have to have the HTML set up exactly as needed for every test, manually.

The unit test code in that example can probably be further improved by refactoring those test() functions into a helper function where you pass in callbacks to run when the test has completed, how many clicks you want to invoke, etc, but that is for another time!

Final plugin code

Here is the final plugin code (with some additional options not discussed above):

(function($) {
    $.fn.sideNotes = function(options) {

        // build main options before element iteration
        var opts = $.extend({}, $.fn.sideNotes.defaults, options);

        // iterate and process each matched element
        return $(this)
            .addClass('dynamic-side-note').hide()
            .attr('aria-expanded', false)
            .wrap('<div class="dynamic-side-note-container"></div>')
            .before('<' + opts.toggleElement + '><a class="toggler" href="#">' + opts.sideNoteToggleText +'</a></' + opts.toggleElement + '>')
            .parent(0)
                .find(opts.toggleElement + '.toggler > a')
                    .click(doToggle);

        // example of private method
        function doToggle() {
            $(this)
                .parents('.dynamic-side-note-container').eq(0)
                    .find('> .dynamic-side-note').each( function() {
                        $.fn.sideNotes.toggle.call(this, options);
                    });

            return false;
        }
    };

    // plugin defaults
    $.fn.sideNotes.defaults = {
        sideNoteToggleText : 'Side note:',
        speed : 'normal',
        toggleElement : 'h3'
    };

    // default implementation for the toggler (public. i.e. overrideable)
    $.fn.sideNotes.toggle = function(options) {
        $(this).slideToggle(options.speed, $.fn.sideNotes.toggled);
    };

    // default callback when toggle completed (public. i.e. overrideable)
    $.fn.sideNotes.toggled = function() {
        this['aria-expanded'] = this['aria-expanded'] === true ? false : true;

        $(this).trigger('sideNoteToggled', this['aria-expanded']);
    };
})(jQuery);

Is the additional lines of code for a plugin worth it?

The plugin used in the unit tested example is larger in terms of lines of code than the very first attempt, above.

In this case, the lines of code is still quite small, and as plugins get even larger the percentage difference is likely to be small (the size difference is more noticeable in smaller code samples, such as this contrived side note example).

Minimizing and gzipping JavaScript, plus using far future expires header for better caching would further reduce the percentage difference in file sizes of the two approaches.

Depending on your needs, this may be a reasonable trade-off in return for additional flexibility.

Summary

So, in many cases, jQuery code can be made reusable by making it into a plugin. Any time you find yourself writing a block of code, say inside a $(document).ready() block, consider converting it into a plugin and calling it.

When making the plugin, consider the following:

• Provide various options for flexibility
• Write unit tests to test your plugin
• Trigger important events inside your plugin to aide unit testability, and in doing so, increase flexibility of your plugin even more.

When you get the hang of this, it is probably better to write the unit tests before the actual plugin code. This will help focus on what is needed and what the plugin needs to expose in terms of capability. To be honest, at times I have found it easier to retrofit a plugin with unit tests. I probably need to be a bit more disciplined to write tests first!

(While there are a number of enhancements that could be added to this, the main thing I’d probably do is rename the plugin to something more generic than just a side note toggler, but I will leave that for the reader to do, and remember to refactor the unit tests accordingly!)

Hope that is useful?

This will allow you to write web pages that refer to those scripts rather than copies on your own site, reducing your bandwidth, but also leveraging the infrastructure capabilities of Google, such as their content distributed network (which means users would be served those files from a location much closer to them), properly compressed, minified, cacheable files, etc.

In addition, if your visitors have been to other sites using the same technique, they would not need to download the same libraries all over again, and with increasingly rich web sites, these files can get quite large.

So, if you use jQuery, you can use this in your web pages:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js"></script>

Of course, this is not for everyone, and it may be worth bearing in mind some concerns raised by Peter Michaux, who also provides a useful way to handle the scenario where you think access to Google from the user’s location might be restricted (e.g. blocked from a paranoid office!):

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js"></script>
<script type="text/javascript">
  if (!jQuery) {
    // load from your own server
    document.write('<script type="text/javascript" src="/js/jquery.min.js"><\/script>');
  }
</script>

Still, it could be a useful technique to further improve the download/load performance for a number of sites.

A number of months back, Yahoo was the first to announce something like this when they said they would host their YUI library for you so it is good to see others getting into this.