Update: See Conditional Script Loading Revisited for WordPress 3.3 and newer.

If you’re involved in WordPress development, a challenge that you’re going to face sooner or later is how to include JavaScript files efficiently.

In this tutorial, I’m going to show you the best way to do that.

Let’s say you have a plugin that adds a custom shortcode. The shortcode needs some JavaScript code which requires jQuery.

If you’re just starting out with WordPress development, you might be tempted to write something like this:

How a WordPress Youngling does it

add_action('wp_head', 'add_my_script');
 
function add_my_script() {
?>
<script type="text/javascript" src="<?php bloginfo('wpurl'); ?>/wp-content/plugins/my-plugin/jquery.js"></script>
<script type="text/javascript" src="<?php bloginfo('wpurl'); ?>/wp-content/plugins/my-plugin/my-script.js"></script>
<?php
}

Let’s see what’s wrong with that approach:

Firstly, since WordPress 2.6, the user can move the wp-content directory wherever he wants. What does that mean? That’s right: instant plugin breakage.

Secondly, if the user installs another plugin that also uses jQuery, the page will end up with jQuery being loaded twice.

Fortunately, WordPress lends us a hand with these two problems:

How a Padawan does it

add_action('template_redirect', 'add_my_script');
 
function add_my_script() {
	wp_enqueue_script('my-script', plugins_url('my-script.js', __FILE__), array('jquery'), '1.0', true);
}

The above script ultimately does what the first one does, except:

• it gets the correct URL to the file
• it checks if jQuery has already been included or not
• the script tag is written in the footer, so the page loads faster

That’s an obvious improvement. But what if the shortcode appears on a single page?

You’re needlessly including a file 99% of the time, causing slower page loads.

Notice that in the last two examples, we’ve been using the template_redirect action.

The trouble with wp_enqueue_script() is that you have to call it before wp_head() fires. So, before the page is rendered, you have to decide if you should add your script or not. Not an easy call to make, is it?

Well, there’s a secret method that will let you enqueue scripts after the entire page has been displayed.

The Jedi Knight way

add_action('init', 'register_my_script');
add_action('wp_footer', 'print_my_script');
 
function register_my_script() {
	wp_register_script('my-script', plugins_url('my-script.js', __FILE__), array('jquery'), '1.0', true);
}
 
function print_my_script() {
	global $add_my_script;
 
	if ( ! $add_my_script )
		return;
 
	wp_print_scripts('my-script');
}

In this case, the script will be enqueued only if the $add_my_script global was set at some point during the rendering of the page.

The key here is that you’re calling wp_print_scripts() directly, instead of relying on WordPress to do it for you.

It will still check if jQuery was already enqueued or not.

You can set the $add_my_script flag from any function or method, including from a shortcode handler:

add_shortcode('myshortcode', 'my_shortcode_handler');
 
function my_shortcode_handler($atts) {
	global $add_my_script;
 
	$add_my_script = true;
 
	// actual shortcode handling here
}

So, the script will be added if [myshortcode ...] was found in any of the posts on the current page.

Nothing more to do here, except wrap it up in a nice class:

The Jedi Master way

class My_Shortcode {
	static $add_script;
 
	static function init() {
		add_shortcode('myshortcode', array(__CLASS__, 'handle_shortcode'));
 
		add_action('init', array(__CLASS__, 'register_script'));
		add_action('wp_footer', array(__CLASS__, 'print_script'));
	}
 
	static function handle_shortcode($atts) {
		self::$add_script = true;
 
		// actual shortcode handling here
	}
 
	static function register_script() {
		wp_register_script('my-script', plugins_url('my-script.js', __FILE__), array('jquery'), '1.0', true);
	}
 
	static function print_script() {
		if ( ! self::$add_script )
			return;
 
		wp_print_scripts('my-script');
	}
}
 
My_Shortcode::init();

I hope this tutorial has helped you on your way to mastering WordPress script loading.

Further reading:

• wp_enqueue_script() reference
• Using plugins_url()
• Shortcode API
• Jedi Ranks

PS: This post was prompted by this question from Artem.