Big Red Tin » JavaScript

jQuery 1.5 as jQuery 1.5.0

Peter Wilson — Tue, 07 Sep 2010 02:53:48 +0000

In early 2009, I wrote a post on browser caching times for the Google AJAX Libraries API.

The cheat notes are that three different URLs point to the current edition of jQuery and each URL is cached in the browser for a different length of time:

The point of my post was that, when using Google’s AJAX Library to host jQuery, or any of the other libraries, it is best to specify the exact version to receive the full benefit of hosting on the same server as gazillions of other web sites, that being, your visitors don’t need to download the library for every site they visit. I was reminded of this when Dave Ward appeared on episode 32 of the official jQuery podcast.

When jQuery 1.4 was released, the Google URL being publicised by the jQuery team was http://…/jquery/1.4/jquery.min.js – while Google had set it up as http://…/jquery/1.4.0/jquery.min.js. I had two problems with this:

The publicised URL, coming from the official jQuery team, was only cached for 1 hour;
Anyone using the publicised URL would automatically be upgraded to jQuery 1.4.1 upon its release, regardless of their expectations.

My request to John Resig and the jQuery team is to avoid confusion by officially numbering the next version as jQuery 1.5.0 and publicising the URL that contains the full version number.

That means that for most people the default version of jQuery they download will be updated least often. It means that the people building the websites have more control over which version of jQuery their end users download and when.

It may seem trivial now but if your visitors leave your site while they’re waiting for jQuery to download, you’ll think it less so.

I’d love to hear your thoughts in the comments below or via @bigredtin on Twitter. If you agree, why not let the jQuery team know via Twitter.

JavaScript Localisation in WordPress

Peter Wilson — Wed, 01 Sep 2010 20:00:45 +0000

Recently on Twitter @iamcracks asked

Attention WordPress Wizards & Gurus. Is it possible to “get WordPress to write a custom field into a javascript variable”?

– source

While I wouldn’t be so bold as to claim I’m either a wizard or a guru, I happen to know the answer to @iamcracks question.

A while back I wrote a two part tutorial on using JavaScript the WordPress way, the code below builds on that. The first step is to load the JavaScript in functions.php using wp_enqueue_script() as detailed in the earlier tutorial:

This outputs the html required for the JavaScript when wp_footer() is called in footer.php

Localising the script is done using the function wp_localize_script() it takes three variables:

$handle – (string) the handle defined when registering the script with wp_enqueue_script
$javascriptObject – (string) name of the JavaScript object that contains the passed variables.
$variables – (array) the variables to be passed

To pass the site’s home page and the theme directory, we’d add this function call below the wp_enqueue_script call above:

 get_bloginfo('url'),
  'theme_dir' => get_bloginfo('stylesheet_directory')
  )
);
...
?>

The output html would be:

Accessing the variables within JavaScript is done using the standard dot notation, for example brtSampleVars.theme_dir to access the theme directory.

Using a post’s custom fields is slightly more complicated so I’ll write out the code in full:

 $allPostMeta['myTwitter'][0],
      'joshsTwitter' => $allPostMeta['joshsTwitter'][0]
      )
    );
    rewind_posts();
  }
}

add_action('wp_print_scripts', 'brt_load_scripts');
?>

Only pages and posts have custom fields so the check at the start of the function has become is_singlular() to check the user is on either a post or a page, earlier we were testing if the user was anywhere on the front end. The arguments for wp_enqueue_script have not changed.

the_post() needs to be called to start the loop and initiate the $post object so the associated custom fields can be accessed in the following line and put in an array.

With the custom fields easily available, the information can then be passed to wp_localize_script() as earlier demonstrated. The final step is to rewind the loop so next time the_post() is called, from either single.php or page.php, the post data is available.

The html output from the sample above would be:

Delay Print Stylesheets Plugin

Peter Wilson — Fri, 27 Aug 2010 02:17:29 +0000

A few weeks ago I wrote a post in which I adapted an idea from a zOompf article to delay the loading of print stylesheets until after a web page has fully rendered. I finished that post with the following point/question:

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:

Stylesheets intended for IE, through conditional comments, were loading in all browsers
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:

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

To support conditional comments for IE required adding each stylesheet within a separate

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.

Delay loading of print CSS

Peter Wilson — Wed, 28 Jul 2010 05:03:50 +0000

Recently I stumbled across an article on zOompf detailing browser performance with the CSS print media type. In most recent browsers, Safari being the exception, the print stylesheet held up rendering of the page.

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:

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 = "";
  }
  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:

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 js_printcss($tag, $handle){
  global $wp_styles, $printCSS;
  if ($wp_styles->registered[$handle]->args == 'print') {

    $tag = "";

    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 "";
  }
}

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 "";
 }

}
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.

Update Aug 23, 2010: Fixed a type in the code block redefining js_printcss.

Update Aug 27, 2010: I’ve decided to release this as a plugin, get the skinny and the plugin from the followup article.

JavaScript the WordPress Way / Part 2

Peter Wilson — Fri, 04 Jun 2010 00:00:20 +0000

In Part 1 we discussed the conflicts that can occur on a WordPress site if themes and plugins add JavaScript using

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 tag, otherwise place the script in the HTML

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.

Charging for themes? Do the right thing!

Peter Wilson — Thu, 12 Nov 2009 00:23:42 +0000

Of all the WordPress functions, I think wp_register_script, wp_register_style, wp_enqueue_script, and, wp_enqueue_style are the most elegant. It’s possible to get away with using only the wp_enqueue_* functions, but I prefer to use both for a little bit more control.

For the uninitiated, these functions allow you to add JavaScript and CSS files to the header (or footer, in later versions of WP) without running of the risk of another plugin adding the same file, that is, you avoid the following:

If you develop themes or plugins for WordPress and are unaware of these functions, you should refer to the codex to get the low down on at least wp_enqueue_script, and wp_enqueue_style – these register and queue the files, the wp_register_* functions register the file ready to be queued for output.

The Rant

Despite the value these functions can add to themes and plugins, they are under-utilised in development. The functions have wider adoption in plug-in development, but it’s still well below 100%. In theme development adoption is virtually non-existent (at least in the themes I’ve used).

This failure to code properly is evenly spread across both free and paid themes. I?m happy to look the other way for free themes. After all, the motivation behind the theme may have been to learn WordPress development.

In commercial themes, particularly those above the US$30-$35 price point, it’s downright frustrating that these products haven’t been developed properly.

When someone purchases a theme, they shouldn’t have to debug the product to find out why a JavaScript framework is being included twice. The reason for the purchase is that they either don’t want to, or know how to, develop.

Avoiding costly mistakes

Evaluating a commercial theme on behalf of a client triggered this rant. At $195, it’s quite expensive in the world of WordPress. As I was viewing the source code of the online demo, I discovered the faux pas. We’ll advise against using that theme as a starting point. In fact, within short time we’d found a theme $195 cheaper that would do the job.

Looking at the source code of a demo site is usually enough to tell you how the theme is inserting its scripts:

Both and
The jsapi file is not cached, so a additional 5K is downloaded for every page hit on your website; if a visitor loads more than three pages an hour then the advantage of the longer caching time is lost. As always, it’s a matter of compromise.

* A minor update to jQuery has been released since the original article was written.