The zOomph article suggests a solution, to load print stylesheets using JavaScript once the page has rendered (ie, on the window.onload event), with a backup for the JavaScript impaired. You can see their code in the original article.

Automating the task for WordPress

Most sites I develop are in WordPress so I decided to automate the process. This relies on using wp_enqueue_style to register the stylesheets:

function enqueue_css(){
  if (!is_admin()){
    wp_enqueue_style (
      'bigred-print', /* handle */
      '/path-to/print.css', /* source */
      null, /* no requirements */
      '1.0', /* version */
      'print' /* media type */
    );
  }
}
add_action('wp_print_styles', 'enqueue_css');

The above code will output the following HTML in the header:

<link rel='stylesheet' id='bigred-print-css'  href='/path-to/print.css?ver=1.0' type='text/css' media='print' />

The first step is to wrap the above html in noscript tags, the WordPress filter style_loader_tag is ideal for this.

function js_printcss($tag, $handle) {
  global $wp_styles;
  if ($wp_styles->registered[$handle]->args == 'print') {
    $tag = "<noscript>" . $tag . "</noscript>";
  }
  return $tag;
}
add_filter('style_loader_tag', 'js_printcss', 5, 2);

The filter runs for all stylesheets, regardless of media type, so the function checks for print stylesheets and wraps them in the noscript tag, other media types are left alone.

The first two arguments are the filter and function names respectively, the third argument specifies the timing (5 is the default) and the final argument tells WordPress how many arguments to pass to the filter – two – in this case $tag and $handle.

With the new filter, WordPress now outputs following HTML in the header:

<noscript>
<link rel='stylesheet' id='bigred-print-css'  href='/path-to/print.css?ver=1' type='text/css' media='print' />
</noscript>

The next step is to add the JavaScript to load the stylesheets, we can do this by changing our original function, js_printcss, and making use of a global variable:

$printCSS = '';

function check_for_print($tag, $handle){
  global $wp_styles, $printCSS;
  if ($wp_styles->registered[$handle]->args == 'print') {

    $tag = "<noscript>" . $tag . "</noscript>";

    preg_match("/<\s*link\s+[^>]*href\s*=\s*[\"']?([^\"' >]+)[\"' >]/", $tag, $hrefArray);
    $href = $hrefArray[1];

    $printCSS .= "var cssNode = document.createElement('link');";
    $printCSS .= "cssNode.type = 'text/css';";
    $printCSS .= "cssNode.rel = 'stylesheet';";
    $printCSS .= "cssNode.href = '" . esc_js($href) . "';";
    $printCSS .= "cssNode.media = 'print';";
    $printCSS .= "document.getElementsByTagName(\"head\")[0].appendChild(cssNode);";
  }
  return $tag;
}

The code creates the PHP variable $printCSS globally, which is then called into the function using the global command.

After wrapping the tag in the noscript tags, the new function uses a regular expression to extract the URL of the stylesheet from the link tag and placing it the variable $href.

Having extracted the stylesheet’s URL, the function then appends the required JavaScript to the PHP global variable $printCSS.

The final step is to add the JavaScript to the footer of the HTML using the wp_footer action in WordPress. The PHP to do this is:

function printCSS_scriptTags(){
  global $printCSS;
  if ($printCSS != '') {
    echo "<script type='text/javascript'>\n";
    echo "window.onload = function(){\n";
    echo $printCSS;
    echo "}\n</script>";
  }
}

add_action('wp_footer', 'printCSS_scriptTags');

The above code uses window.onload as dictated in the original article. A better method would be to use an event listener to do the work, for those using jQuery we would change the function to:

function printCSS_scriptTags(){
  global $printCSS;
  if ($printCSS != '') {
    echo "<script type='text/javascript'>\n";
    echo "jQuery(window).ready(function(){\n";
    echo $printCSS;
    echo "});\n</script>";
 }

}
add_action('wp_footer', 'printCSS_scriptTags');

The above solution had been tested for very limited circumstances only and found to have worked. Were I to use the function in a production environment I would undertake further testing.

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.

In brief, Mullenweg believes that, because WordPress is released under the GPLv2 license, all themes and plugins developed for WordPress must also be released under the same license. Pearson disagrees.

This situation has never affected us directly at Soupgiant so we haven’t needed to, and this is important, ask our lawyer if my interpretation is correct. This is a layman’s opinion and should be treated as such.

The battle comes down to these clauses in the GPLv2 license:

You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works.

–source GPLv2 license

Due to the second clause quoted above, I believe that Mullenweg is wrong. WordPress themes can operate on other blogging platforms with minimal changes. This has been done before with the Sandbox theme for WordPress which was successfully ported to Movable Type.

WordPress themes output HTML with a series of calls to the blogging platform. To output the post’s title and contents in our base theme, we use the code:

<h2 class="entry-title"><?php the_title() ?></h2>
<div class="entry-content">
    <?php the_content("Continue reading " . the_title('', '', false)); ?>
</div>

To output the same HTML in a Movable Type theme, we would output:

<h2 class="entry-title"><$mt:EntryTitle$></h2>
<div class="entry-content">
    <$mt:EntryBody$> <$mt:EntryMore$>
</div>

In terms of a page’s output, the above code is a minor part of the page. The theme’s template is mostly made up of HTML and CSS, HTML and CSS operate in the browser and not in the blogging platform. It’s for that reason that I believe that Pearson is correct in this case.

I acknowledge that WordPress hooks may complicate the matter but these hooks output such a minor part of a theme’s HTML, that I consider the theme uses the platform but isn’t derived from the platform. I’ve left plugins out of this discussion as these are a more complicated matter: they can output HTML or they can build on the platform.

The above said, were I to release a WordPress theme I would probably release it under the GPL as a hat tip and thank you to the community that has assisted me so much. However, if the theme was as complicated as the Thesis theme, I may feel differently about the matter when it’s crunch time.

Again, this is a layman’s opinion and should be treated as such. If you have a layman’s opinion too, we’d love to hear it in the comments.

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.

According to the fangs plugin, the JAWS screen reader reads the opening of Soupgiant.com as:

Page has seven headings and forty-three links Soupgiant vertical bar Web Production dash Internet Explorer Heading level one Link Graphic Soupgiant vertical bar Web Production Heading level five Heat and Serve Combine seventeen years of web production experience, twenty years of television and radio experience, put it all in a very large pot on a gentle heat. Stir regularly and serve. Soupgiant goes well with croutons and a touch of parsley.List of five items bullet This page link Skip to Content bullet Link Home bullet Link About bullet Link Contact bullet Link Folio

- my emphasis

That’s a lot of content to get through, on every page of the site, before the Skip to Content link. It would be much better if the skip to content link were earlier on the site.

As the HTML title of the page is read out by JAWS, the best position would be before the in-page title. The opening content would then read as:

Page has seven headings and forty-three links Soupgiant vertical bar Web Production dash Internet Explorer This page link Skip to Content Heading level one Link Graphic Soupgiant vertical bar Web Production

- again, the emphasis is mine

That gives the JAWS user the title of the page and immediately allows them to skip to the page’s content. I don’t read the header of on every page of a site, nor should I expect screen reader users to.

I realise screen readers most likely have a feature to skip around the page relatively easily, regardless of how the page is set up but our aim should not be relative ease, our aim should be absolute ease.

As a result, we’ve decided to move the skip to content links on future sites to earlier in the page.

Sadly, this revelation came up as a result of what I consider to be a limitation of the WordPress 3.0+ function wp_nav_menu, the inability to add items at the start of the menu. I should have considered the accessibility implications much earlier. It serves as a reminder, to all web developers, that we should constantly review our practices and past decisions.

If you’ve recently changed something you’ve always done, we’d love to hear about it in the comments.

When we launched Big Red Tin we didn’t set up Twitterfeed immediately.

With manual tweets we could customise the message to provide more details to Twitter users, one such tweet was:

We’ve defined a new term: Web 1.5 http://redt.in/b0KRut ^pw

– source: @bigredtin

We had Twitterfeed set up at this blog’s old location and took the opportunity to compare click-throughs from manual tweets versus automated tweets.

Manual tweets had a substantially higher click-through rate than the automated tweets. I suspect the reason for this is two fold:

• With so many people using Twitterfeed type services, Twitter users have learnt to ignore tweets that appear auto-generated.
• More information can be included in a manual tweet than might appear in an auto-tweet.

Take the post we were linking to earlier, had we been using Twitterfeed the tweet would have been ‘Blog Post: Web 1.5 http://redt.in/b0KRut‘. This provides so little information as to be next to useless. We would have ignored such a tweet out ourselves.

Many of the posts on this site are scheduled in advance, this allows us to publish at roughly the same time each week.

To schedule the associated tweets we use CoTweet. We have a couple of shared twitter accounts as it is, so CoTweet comes in handy for other purposes, but it’s the scheduling feature we use most of all.

If you use Twitterfeed yourself, try disabling it for a couple of weeks and manually tweet in its place. There’s a good chance you’ll be pleasantly surprised when you compare your bit.ly stats.

We may have been able to fudge it. Call us stupid, but we don’t think ‘fudging it’ is the way to keep clients happy or maintain a low client turnover.

In this situation there are two options:

1. Quote ludicrously high with the aim of missing out on the job. In the event the quote is accepted, the job can be outsourced with a tidy profit.
2. Tell the truth and decline the work

We chose the latter option and used the opportunity to explain our areas of expertise. Selling the company, not the lie.

The natural fear is the potential client will storm out of the meeting, muttering obscenities under their breath.

What actually happens is the potential client realises their current project – or at least the original part of their current project – is a bad fit. They also realise they’re not dealing with sleazy salesmen willing to say anything to get a job and deal with the consequences later.

The second realisation sells a company. It’s something that can be used to convert a single project into a long term relationship.

Ludicrously high quoting, lies or fudging a task may get you more clients but getting clients isn’t the aim, the real aim is to keep them.

The frame of both sites will be pretty similar. We were thinking of different colour schemes [...] as a way of demarcating the two sites.

We haven’t got an exact style in mind, but something relaxed and modern without going over the top – Web 1.5 if you like.

— source: email to Zepol (emphasis added for this post)

The rest of the brief detailed the content separation between Soupgiant and Big Red Tin. We wanted the design to come from the designer to fit the content, not from a committee to fit some other agenda.

In the context of this site’s design, the exact interpretation of Web 1.5 was left to Christa’s devices. As should the exact interpretation of any design brief.

To me, web 1.5 means something like: dump all the cliches of Web 2.0 design, at the same time keep the good bits

“A good bit” may be a feature that is used frequently, such as oversized footers, because it adds something for users of the site. Cliches are those design tricks that add nothing but appear on every second web site, such as elements with faded backgrounds and rounded corners.

It strikes me, as a developer, it must be said that the definition of design is something similar: dump all the cliches and keep all the good bits

Failing to do so risks rendering you a regurgitator, not a designer.

While neither the xHTML nor the CSS on this site validates, we consider it to observe best practices.The HTML fails validation due to the following problems:

• One of the WordPress plugins we use on the site inserts JavaScript with unencoded ampersands in the URL. This isn’t a best practice but unfortunately it’s beyond our control;
• The <html> tag has a class attribute;
• Two of the fields in our comment form have an unrecognised value for the type attribute.

The CSS fails validation due to the following problems:

• We load the YUI 2.7.0 CSS reset, base and fonts files from the Google AJAX API servers. These files contain star hacks for IE targeting;
• We use browser extensions to implement CSS rounded corners and rgba backgrounds;
• Until I started writing this post, we styled a heading with font-size: 145.4545%%.

That last one was a typo, and has since been fixed.

Justifying the invalid CSS

We’d prefer to avoid the star hacks in YUI’s CSS. If we self-hosted the files they’d be moved into the CSS files with our other IE specific hacks and targeted with conditional comments. Our compromise is to load the files from Google’s server with the aim that our site will load faster. Either the user will already have the files in their browser cache, or the user will load the files from a closer, faster server on Google’s global network.

The W3C’s CSS validator also screams at us for using CSS3 browser extensions and rgba backgrounds. While the browser manufacturers are still trying out their implementations of the new specs, we’ve no choice but to use these for the time being. As they iron out their implementations and move them over to the specified properties we can remove these. CSS3 junkies could probably have skipped this paragraph.

Justifying the invalid HTML

This site uses xHTML. We’ve discussed using HTML5 but WordPress, which powers Big Red Tin, isn’t ready to drop the /> from self closing tags. At this stage the HTML5 spec is too dynamic for our liking. Have a late afternoon snooze and the spec is likely to change during your siesta.*

Depending on your point of view, and even what you are coding, it is either fortunate or unfortunate that browsers don’t always follow specs to the letter. We’ve taken advantage of that to throw one of the biggest advantages of HTML5 into our xHTML. In our comments form, we’ve used HTML5 type attributes for two of our fields: <input type=”email” … /> and <input type=”url” … />.

In browsers that do not support these types of inputs the type falls back to the standard of type=”text”. In browsers that do support input types of email and url, it prevents the user from entering an erroneous value. For users of the iPhone or iPad, a special keyboard is presented to make entering an email address or URL easier. In browsers that support the new HTML5 input types, the behaviour is identical regardless of the doc type.

The iPhone displays different keyboards for HTML5 input types

It may be breaking some of the rules of standards. To me it’s not so much about standards as best practices and giving the user the best possible experience on a site, even if this means breaking the rules sometimes.

Don’t take that to mean that we’ll be reverting to table layouts, or insert code such as <a href="#"><h1>Heading</h1></a> into our xHTML. It’s bending the rules around the edges, which is no different to using vendor prefixes to make use of CSS3.

*Yes. I know this is an unfair characterisation. A lot of very important people, with very important lawyers, are working hard to change this.

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.