Another question to ask is whether all this is actually worth the effort – even when reduced through automation. On Big Red Tin, the print.css is 595 bytes, the delay in rendering is negligible.

Chris and Jeff at Digging into WordPress picked up the article and posted it on their site. In turn it was picked up elsewhere and became the surprise hit of the summer at Big Red Tin. Not bad when one is shivering through a bitter Melbourne winter.

As a result of the interest, I decided to convert the code from the original post into a plugin and add it to the WordPress plugin directory.

Further Testing

As I warned in the original article, I’d tested the code in very limited circumstances and found it had worked. Fine for a code sample but not enough for a sub version-1.0-release plugin. Additional testing showed:

1. Stylesheets intended for IE, through conditional comments, were loading in all browsers
2. When loading multiple stylesheets, the correct order was not maintained in all browsers

If jQuery was available I wanted to use it for JavaScript event management otherwise I’d use purpose-written JavaScript. There’s no point, after all, of worrying about the rendering delay caused by 600-1000 bytes only to load a 71KB (or 24KB gzipped) file in its place.

Other things I wanted to do included:

1. Put the PHP in a class to reduce the risk of clashing function/class names
2. Put the JavaScript in its own namespace
3. Keep the output code as small as possible

To support conditional comments for IE required adding each stylesheet within a separate <script> tag, using this method the output HTML takes the following form:

<script>
  // add global print.css
</script>
<!--[if IE 6]>
  <script type='text/javascript'>
    // add ie6 specific print.css
  </script>
<![endif]-->

This violates my aim to keep output as small as possible but footprint has to take second place to bug-free. I could have translated the code to use JavaScript conditional comments by translating the IE version to the JavaScript engine it uses but this could lead to future-proofing problems.

To maintain the order of stylesheets, I added each event to an array of functions and then used a single event to loop through the array of functions. If jQuery is used, I add multiple events because jQuery runs events on a first in first out basis.

Putting the PHP in a class and the JavaScript in its own namespace is fairly self-explanatory. Google is your friend if you wish to read up further on this.

Minimising the footprint was also a simple step. I wrote the JavaScript out in full with friendly variable names. Once I was happy with the code, I ran the code through the YUI JavaScript compressor, commented out the original JavaScript in the plugin file and output the compressed version in its place.

The JavaScript is output inline (within the HTML) to avoid additional HTTP requests. I was in two minds about this because browser caching is lost in the process. So it may change in a later version.

I’ve worked out another way to keep the footprint small. Rather than creating a function to pass the stylesheet’s URL and ID to brt_print.add(url, id), I wrote out the full function for each style sheet. I’ll fix that in the next release.

You can download the Delay Print CSS Plugin from the WordPress plugin repository.

As with most WordPress sites we use plugins to enhance WordPress, including Donncha O Caoimh‘s excellent WordPress MU Domain Mapping plugin. As the name implies, the domain mapping plugin allows us to use top level domains for each site rather than being stuck with sub-domains. In the case of this blog, without the plugin it would reside at bigredtin.pressgiant.net.

Taking care with plugins

Many plugins are tested for the single site version of WordPress only. I don’t have a problem with this as most plugins are released under the GPL and free in terms of both speech and beer. If I’m not paying for software, it’s up to me to test it in the fringe environment of WordPress MS.

Now that WordPress is WordPress MS is WordPress, more developers may test in both environments but they certainly can’t be expected to test with all manner of combinations of plugins.

The standout problem

One of the standout problems when using plugins with WordPress MS is when they define a constant for the plugin’s url as the script starts executing, the PHP code may look similar to:

<?php

  define('PLUGIN_DIR', get_bloginfo('url') . "/wp-content/plugins/peters-plugin");

  function plugin_js_css(){
    wp_enqueue_script('plugin-js', PLUGIN_DIR . '/script.js');
    wp_enqueue_style('plugin-css', PLUGIN_DIR . '/style.css');
  }

  add_action('init', 'plugin_js_css');

?>

The above stands equally for themes mapping the stylesheet directory at the start of execution:

<?php

  define('THEME_DIR', get_bloginfo('stylesheet_directory') );

  function theme_js_css(){
    wp_enqueue_script('theme-js', THEME_DIR . '/script.js');
    wp_enqueue_style('theme-css', THEME_DIR . '/style.css');
  }

  add_action('init', 'theme_js_css');

?>

The get_bloginfo and bloginfo functions return information about your blog and your theme settings including the site’s home page, the theme’s directory (as in the second code sample above) or the stylesheet url. bloginfo outputs the requested information to your HTML, get_bloginfo returns it for use in your PHP.

Outside of code samples, bloginfo and get_bloginfo are interchangeable throughout this article.

The problems occur when a subsequently loaded plugin needs to change something retrieved from bloginfo. In this site’s case, Domain Mapping changes all URLs obtained through bloginfo, but it could be a plugin that simply changes the stylesheet url to a subdomain to speed up page load.

In a recent case, a plugin – let’s call it Disqus – was defining a constant in this manner. As result an XSS error was occurring when attempting to use Facebook Connect. Replacing the constant with a bloginfo call fixed the problem.

The improved code for the first sample above is:

<?php

  function plugin_js_css(){
    wp_enqueue_script('plugin-js', get_bloginfo('url') . '/wp-content/plugins/peters-plugin/script.js');
    wp_enqueue_style('plugin-css', Pget_bloginfo('url') . '/wp-content/plugins/peters-plugin/style.css');
  }

  add_action('init', 'plugin_js_css');

?>

bloginfo doesn’t hit the database everytime

I presume the developers set their own constants because they’d like to avoid hitting the database repeatedly to receive the same information.

Having run some tests on my local install of WordPress, I can assure you this is not the case. Running bloginfo('stylesheet_directory') triggers a db call on the first occurrence, the information is then cached for subsequent calls.

I realise I sound incredibly fussy and that I’m suggesting we protect against edge cases on our edge cases. You’re right, and it’s not the first time, but as developers it’s the edge cases that we’re employed to avoid.

In this section we’ll deal with a more complicated example and use Google’s AJAX libraries API to lower your bandwidth costs. We’ll also take what we’ve learnt about including JavaScript and apply it to our CSS.

A more complicated example

The sample code yesterday included a simple example of using the same JavaScript file throughout your site. Let’s spice things up slightly by introducing the following circumstance. Consider that you have three JavaScript files:

• base.js is the base JavaScript file to be used throughout the site. It uses the jQuery library and must load in the HTML <head>;
• posts.js loads on pages and posts and only calls functions from the base JavaScript file but doesn’t use the jQuery library directly. It can load in the HTML footer.
• archives.js loads on all other pages throughout your site (except admin). It calls functions from your base JavaScript file and makes direct use of the jQuery library. It can load in the HTML footer.

In this situation, you could change your base.js to use another library – say, Prototype – and it would have no effect on the posts.js. So, posts.js can be said not to depend on jQuery directly.

Changing libraries would require edits to the third file, in which case archives.js does depend on jQuery directly.

Registering the Files

The code to register those JavaScript files and conditions with WordPress is:

wp_register_script (
  'mytheme-base', /* handle */
  get_bloginfo('template_url') . '/base.js', /* source */
  array('jquery'), /* requires jQuery */
  1.0 /* version 1.0 */
);

wp_register_script (
  'mytheme-posts', /* handle */
  get_bloginfo('template_url') . '/posts.js', /* source */
  array('mytheme-base'), /* requires base.js */
  1.0, /* version 1.0 */
  true /* load in footer */
);

wp_register_script (
  'mytheme-archives', /* handle */
  get_bloginfo('template_url') . '/archives.js', /* source */
  array('jquery', 'mytheme-base'), /* requires jQuery & base.js */
  1.0, /* version 1.0 */
  true /* load in footer */
);

This code says to WordPress:

• If loading posts.js, also load base.js;
• If loading archives.js, also load jQuery and base.js;
• If loading base.js, also load jQuery;

Each of these are separate checks (if) rather than a series of options (if, else if).

Enqueueing the files

All the hard work has been done registering the files, WordPress knows what each file requires to work and where in the HTML (<head> or footer) the <script> tags should be inserted.

Now it’s a simple process of checking if the visitor is loading a post or page and requesting the appropriate file.

We need to delay the check slightly, otherwise WordPress won’t know if the user is on a page, post or elsewhere. The first step is to enclose the check in a function.

function que_scripts(){
  if (!is_admin()) { //visitors only
    if (is_singular()) { // pages & posts
      wp_enqueue_script('mytheme-posts');
    }
    else {
      wp_enqueue_script('mytheme-archives');
    }
  }
}

Then tell WordPress when to execute the function. For this we use the action wp_print_scripts. This runs the code above before WordPress attempts to output the <script> tags to your HTML.

add_action('wp_print_scripts', 'que_scripts')

There is no need to enqueue jQuery or base.js directly. WordPress knows to add those to the HTML based on the dependancies listed when registering the files.

Using the Google AJAX Libraries API

Loading all these libraries from your own server may seem like a waste of your bandwidth considering you could be loading the libraries directly from Google’s servers.

With a bit of luck, your visitor will have Google’s version of the libraries in their browser’s cache already and your site will load a little quicker.

It’s a bit messy to do this yourself, especially since jQuery needs to be kept in noConflict mode. Fortunately Jason Penny has developed a plugin, called “Use Google Libraries”, to do the hard work for you.

“Use Google Libraries” is the first plugin I add when setting up sites for me and my clients.

Making our super-broken example super-fabulous

If, when developing their theme and plugin, George and Richard from our example in Part 1, had used the wp_register_script and wp_enqueue_script WordPress functions to load their JavaScript, WordPress would know that only one version of jQuery needs to be loaded for both the theme and the plugin to work.

As WordPress releases come in fits and bursts, sometimes the version of the JS libraries included with WordPress fall behind the current version of the library available otherwise.

This is a small price to pay for the knowledge that our sites will remain super-fabulous rather than super-broken, at least when it comes to the JavaScript.

A bonus for CSS

By now the reasons for using wp_register_script and wp_enqueue_script should be clear. If you want to go that one step further, you can use the equivalent functions for your CSS.

As CSS should always be loaded in the HTML <head>, there is no option to load the CSS files in the footer of the HTML. Otherwise the CSS functions take the same arguments as their JavaScript equivalents. The CSS functions are:

• wp_register_style
• wp_enqueue_style

The four parameters they take are:

$handle

(required for both functions) Name of the style sheet

$source

(required for wp_register_style) – URL of the script. Also required by wp_enqueue_style if the style is unregistered.

$dependancies

(optional) – an array of handles the style sheet depends on

$version

(optional) – version number

WordPress doesn’t include any style sheets bases, such as YUI CSS, in the default distribution, so the main purpose of the CSS functions is to allow you to keep track of your version numbers and to call in style sheets only as they’re needed.

Conditional comments

Unfortunately the WordPress functions for JavaScript do not allow for conditional comments, so scripts targeting older versions of IE (okay, I’m referring to PNG fixers for IE6) need to be coded directly into your theme’s header.php or footer.php.

On the other hand, the CSS functions do allow for conditional comments, in a round-about fashion. Let’s register a CSS file we’ll be targeting at IE6.

wp_register_style (
  'mytheme-ie6', /* handle */
  get_bloginfo('template_url') . '/ie6.css', /* source */
  array('mytheme-css'), /* requires mytheme-css (not shown) */
  1.0 /* version 1.0 */
);

Behind the scenes WordPress is adding the stylesheet to the object $wp_styles. To add the conditional comments you need to access the object more directly. To target the above to IE6, the command is:

$wp_styles->registered['mytheme-ie6']->extra['conditional'] = 'IE 6';

If, as in the complicated example above, you need to check where a user is before enqueueing your stylesheet, again you need to enclose the enqueueing command in a function and run it on an action, in this case the action wp_print_styles.

For example, to output the IE6 stylesheet above on pages and posts only, the full code would be:

function que_styles(){
  if (!is_admin()) { //visitors only
    if (is_singluar() {
      wp_enqueue_style('mytheme-ie6');
    }
  }
}

add_action('wp_print_styles', 'que_styles')

Conclusion

The methods described in this tutorial may appear to complicate matters for little pay off, especially if you’re developing a theme or plugin for your own site.

Replacing your <script> tags with the code above, it is true, will have almost no effect on the HTML or JavaScript output by WordPress. What’s worse, if you use the $ alias for jQuery in your JavaScript, you’ll need to edit both the theme’s php and JavaScript files.

These functions, wp_register_script and wp_enqueue_script, aren’t about now, however, they’re about “then”.

• Then… I activated this plugin and my JavaScript stopped working.
• Then… I changed the theme and my favourite plugin stopped working
• Then… I looked at the source code, and two copies of jQuery were being sent to every visitor

The WordPress developers have seen the problems JavaScript conflicts can cause, and developed these functions to make your theme or plugin more robust. It’s the added robustness, for such little effort, that make these functions worth using.

It’s also possible your theme or plugin will work perfectly well without these functions on its own. Problems will arise when your theme or plugin both use the same JavaScript library or if Prototype and jQuery are both used on the same site.

These functions are used to add JavaScript to the html, either in the head or the footer.

Introducing wp_register_script and wp_enqueue_script

For the rest of this article I’ll refer to development of your theme. The tutorial applies equally to development of your plugin, but there’s only so many times the phrase “your theme or plugin” can appear in a page.

In this first part, we’ll look at:

• Defining the problem;
• The libraries included with WordPress;
• Defining the functions we’ll be using and;
• The functions for registering and enqueueing your scripts.

The problem defined

Imagine you’ve used a theme on your WordPress site for months or years without a problem. It uses jQuery to add AJAX functionality to your site and it’s called George’s Super Theme.

You decide to add a plugin to your WordPress site and add more AJAXy goodness to your site. This plugin also uses jQuery for the JavaScript and it’s called Richard’s Fabulous Plugin.

You activate the plugin and instead of the super-fabulous result you were looking for you end up with a super-broken site. None of the JavaScript is working and your visitors are stuck on the home page, with nowhere to go.

Looking at the HTML of your WordPress site, you see the following lines:

<script type='text/javascript'
  src='/wp-content/themes/george/jquery-1.4.2.js'></script>
<script type='text/javascript'
  src='/wp-content/plugins/richard/jquery-1.3.2.js'></script>

Both the theme and the plugin are attempting to load the jQuery library. each uses a different version, which further complicates matters.

In this particular case, the theme is expecting jQuery version 1.4.2 and the plugin is replacing it with version 1.3.2. Anytime the theme attempts to use a function added to jQuery in version 1.4 or later, an error occurs preventing the JavaScript from running.

Even if the site was running as expected, it’s a waste of your users’ bandwidth.

Fortunately the WordPress developers envisioned this problem and sort to solve it by including the most common JavaScript libraries with WordPress and developing the functions that are the subject of this tutorial.

Libraries included with WordPress

WordPress comes with a number of JavaScript libraries pre-registered, so you need not include these libraries in your theme. All you need to do is include them as dependencies of your custom JavaScript and WordPress will do the work.

Some of the libraries included with WordPress are:

• jQuery – with the handle ‘jquery’, runs in no conflict mode
  • WP 2.9.2 includes version 1.3.2 of jQuery
  • WP 3.0 will include version 1.4.2 of jQuery
• Scriptaculous – with the handle ‘scriptaculous’
• SWFObject – with the handle ‘swfobject’
• Prototype – with the handle ‘prototype’
• A full list of pre-registered script can be found in the codex.

The functions defined

The WordPress codex defines wp_enqueue_script as “a safe way of adding JavaScripts (sic) to a WordPress generated page”.

wp_register_script is similar and can be thought of as a safe way of introducing JavaScript to WordPress, without adding it to the generated page.

The difference between these functions are fully explained in the sections Registering your scripts and Enqueueing your scripts below.

Both functions take the same five parameters:

$handle

(required for both functions) Name of the script

$source

(required for wp_register_script) – URL of the script. Also required by wp_enqueue_script if the script is unregistered.

$dependancies

(optional) – an array of handles the script depends on

$version

(optional) – version number

$in_footer

(true/false, optional) – if true, place script above the HTML </body> tag, otherwise place the script in the HTML <head>

These functions only work as expected if both wp_head() and wp_footer() are included in header.php and footer.php respectively.

Registering your scripts – wp_register_script

wp_register_script gives WordPress knowledge of your script without adding it to your HTML. Used by itself, it has no effect on your HTML whatsoever.

You can use it if you wish to register your various JavaScript files in one block of php within your theme’s functions.php file, allowing you to update version numbers, dependancies and handles in one place.

If the use of the JavaScript depends on particular conditions being met, such as the user being on a particular post, you can then enqueue your scripts elsewhere without losing track of where you should update version numbers.

If your theme’s JavaScript can be loaded in the footer and relies on the jQuery library, you would register your script with the following code:

wp_register_script (
  'mytheme-custom', /* handle WP will know JS by */
  get_bloginfo('template_url') . '/custom.js', /* source */
  array('jquery'), /* requires jQuery */
  1.0, /* version 1.0 */
  true /* can load in footer */
);

At this stage, this has no effect on your HTML, you need to use wp_enqueue_script to do that.

Enqueueing your scripts – wp_enqueue_script

wp_enqueue_script outputs your JavaScript to the HTML of the page, either as a result of the wp_head() or the wp_footer() call in your PHP. If you have pre-registered your script (as above), the full code is:

if (!is_admin()) {
  wp_enqueue_script('mytheme-custom');
}

Combined with the code above, this line of code will load both jQuery and your theme’s JavaScript. The only reference to jQuery is needed in the dependancies. There is no need to register or enqueue it yourself.

The check that your visitor is outside of the admin area, !is_admin() – is important, as these functions can be used to add JavaScript to both the visitor and admin areas.

More often than not, you’ll want to leave the admin area alone.

A shortcut

It’s possible to enqueue your script without registering it first. This comes in handy if your theme uses a single JavaScript that is loaded on every page, outside the admin area, of your blog.

The code to do this is:

if (!is_admin()) {
  wp_enqueue_script (
    'mytheme-custom', /* handle WP will know JS by */
    get_bloginfo('template_url') . '/custom.js', /* source */
    array('jquery'), /* requires jQuery */
    1.0, /* version 1.0 */
    true /* can load in footer */
  );
}

Again, our custom code requires the jQuery Library.

Aside: noConflict for jQuery and Prototype

As mentioned earlier, jQuery runs in noConflict mode. The reason being that in jQuery’s standard mode it includes the $ variable as an alias. WordPress also includes Prototype, which includes the JavaScript variable $.

Imagine if your theme uses jQuery and you add a WordPress plugin that makes use of Prototype, whichever is loaded second would override the $ variable of the former. Either your theme’s or the WordPress plugin’s JavaScript would crash as a result.

If your theme uses jQuery and you’d still like to make use of the $ alias, it’s possible to do so without breaking the plugin’s JavaScript. In your JavaScript file, just wrap your code between these two lines:

(function($) {
  /* your code */
})(jQuery);

– source

Under no circumstances should you reintroduce the $ alias for jQuery, it could lead to problems down the track.

A shorter aside: throughout this post I’m using the example of JavaScript requiring jQuery. The reasons are two-fold: a) it’s the library we use at Soupgiant and Big Red Tin and, b) as Twitter’s Dustin Diaz said recently of jQuery: ‘they won‘.

Now Available: Part Two

In part 2 of this tutorial we’ll further illustrate dependancies, lower your bandwidth costs and show you how to use similar functions to load your stylesheets.