Adding Scripts Properly to WordPress Part 1 – wp_enqueue_script

To load your script in the footer, simply pass it a 1 (or true).

Aside from the excellent documentation from WordPress, you’ll find my regurgitated version below (gross, I know).

Great care should be used when setting the scripts to load in the footer as some themes do not have this functionality built in (the theme must make use of the wp_footer function call).

The ver argument is simply the version of the JavaScript file for caching purposes. If you are supplying your own script, it’s a good idea to supply a version.

The outcome in this scenario is that jQuery and another_script will load before my_script.

Likewise, if you have previously registered your script (using wp_register_script), you can call your script by calling:

So How Does wp_enqueue_script Work?

Here’s an example:

The handle argument is a string that names your script, or references someone else’s.

 wp_enqueue_script('handle', 'src', 'deps', 'ver', 'in_footer'); ?>

An example of it in use is: 

And for those not using a class (classes help avoid conflicts with other plugins):

For example, the handler ‘jquery’ is built-in. Do you want to supply your own version of jQuery?

 wp_enqueue_script('jquery'); ?>

For example, you can add the jQuery script to any page by calling:

Themers would use:

 wp_enqueue_script('my_script'); ?>

The function wp_enqueue_script takes in five arguments, with the last four being optional.

Src

Fortunately, WordPress has two such action hooks you can tap into: admin_print_scripts and wp_print_scripts.

The admin_print_scripts hook allows you to add scripts in the admin panel, while the wp_print_scripts hook allows you to add scripts everywhere else.

 wp_enqueue_script('my_script', WP_CONTENT_URL . 'plugins/my_plugin/my_script.js'); ?>

With this technique, however, you should have a pretty darn good reason for not including the default scripts.  After all, you’ll essentially be running a piece of software that may not be fully tested and/or compatible with WordPress.  

 wp_enqueue_script('my_script', WP_CONTENT_URL . 'themes/my_theme/my_script.js'); ?>

Deps

jQuery is built into WordPress by default, so calling it via dependency is no problem as long as you queue it via wp_enqueue_script.

The in_footer argument (since WP 2.8) determines if the script will load in the header or footer (header is the default).

wp_enqueue_script('my_script', WP_CONTENT_URL . 'plugins/my_plugin/my_script.js', array('jquery', 'another_script'));
?>

One last thing (err, warning?) to take note of is naming your handler for wp_enqueue_script.  If you are using a third-party script (say, Colorbox), use common sense in naming the handler.  There’s no reason to name it “lightbox” or “mybox”.  The handler name should be obvious, right? 

As you might imagine, this presented a ton of problems. Scripts were loaded twice, out of order, or even when they weren’t needed at all.

Before that, it was every plugin or theme author for himself. If you wanted to add in a script, it was hard-coded in.

This prevents duplicate JavaScript files from loading, which is always a good thing.

Ver

The wp_enqueue_script function is the first step in loading your scripts properly. Not only can you add your script, but you can also specify the dependencies (e.g., jQuery), and the version number.

wp_enqueue_script('my_script', WP_CONTENT_URL . 'plugins/my_plugin/my_script.js', array('jquery', 'another_script'), '1.0.0');
?>

The src argument is asking for the URL of the file. If you supply the src of the script, the wp_enqueue_script function automatically registers your script for others to use (no need to use wp_register_script).

In_footer

The version is string based and looks like this:

wp_enqueue_script('my_script', WP_CONTENT_URL . 'plugins/my_plugin/my_script.js', array('jquery', 'another_script'), '1.0.0', true);
?>

As you update your JavaScript file, update the ver argument.  If you don’t, you’ll inevitably run into caching issues with WordPress.

Naming Your Handler

The deps argument is an array of dependencies. For example, if your script requires jQuery or other JavaScript files, it’ll load these files before your plugin’s JavaScript file.

The another_script dependency assumes you have already used wp_enqueue_script to assign it a handle and a src.

Starting in WordPress 2.1 (if I remember correctly), the awesome folks at Automattic gave us the even awesomer function of wp_enqueue_script.

Adding your wp_enqueue_script code is as simple as adding an action inside your plugin or theme code.

wp_deregister_script(array('jquery'));
wp_enqueue_script('jquery', 'your-jquery-path.js');
?>

See that array up there (it’s pretty, I know)?  That’s what’s calling your dependencies. 

Instead, use the function wp_deregister_script to remove the WordPress reference and supply your own.

Great, I have wp_enqueue_script down. Now what?

The same goes for the built-in scripts with WordPress.

How about ruin everybody’s day and give it a handler of ‘jquery.js’? The result will inevitably be two jQuery instances loading on the same page and causing mayhem with other scripts.

add_action('admin_print_scripts', array(&$this, 'add_admin_scripts'));
?>

An example of the code being used inside of a class constructor is:

You have to call wp_enqueue_script from the appropriate hook in WordPress.

add_action('admin_print_scripts', 'add_admin_scripts');
?>

For the above example, we have a callback method of add_admin_scripts.  An example of it in use is:

Furthermore, some themes and plugins had the JavaScript embedded within the plugin’s or theme’s PHP file just to capture a few PHP variables. Not good! In order to add scripts properly to JavaScript, you must always keep your PHP and JavaScript separate. And by separate, I mean separate files. There’s just no excuse anymore (I’ll get into this in Part 2 of this series).

function add_admin_scripts() {