Big Red Tin » WordPress

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.

Thesis V WordPress, Pearson V Mullenweg

Peter Wilson — Thu, 15 Jul 2010 01:33:38 +0000

Reading my WordPress feeds this-morning, it appears a war of words broke out overnight between Matt Mullenweg (the lead developer of WordPress) and Chris Pearson, the developer of the Thesis theme.

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:

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

<$mt:EntryTitle$>

    <$mt:EntryBody$> <$mt:EntryMore$>

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.

Getting the bloginfo correctly

Peter Wilson — Tue, 13 Jul 2010 02:12:30 +0000

This site runs on an WordPress MS install, along with a number of other small sites. You can see the full list of sites on the directory page.

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:

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

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:

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.

‘Skip to Content’ Links

Peter Wilson — Thu, 08 Jul 2010 02:03:45 +0000

Big Red Tin co-author, Josh, and I were discussing the positioning of Skip to Content links on a website. In the past I’ve placed these in the first menu on the page, usually positioned under the header.

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.

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