Javascript and WordPress — The Definitive Guide

Using cus­tom Javascript code in a WordPress theme or plu­gin is, in many cases, a given. Fortunately, WordPress comes bundled with a selec­tion of pop­u­lar Javascript lib­rar­ies (jQuery, Prototype and oth­ers) for use with your plu­gins and themes. Many users, how­ever, simply write the ‘<script>‘ tags in the header.php file of their theme or as part of a func­tion in their plu­gin that is run in the header of the theme being used. This is a poten­tial prob­lem area that can have you, the developer, sit­ting for ages look­ing at your code and won­der­ing why plu­gin ‘X‘ isn’t work­ing cor­rectly when theme ‘Y‘ is act­ive. This guide aims to provide an under­stand­ing of how to cor­rectly enqueue Javascript in WordPress and how to avoid poten­tial Javascript conflicts.

Okay, what are we doing here?

We’re going to enqueue the Javascript files, used by our WordPress plu­gin or theme, using the cor­rect method and the wp_enqueue_script()func­tion. We will be adding an action to the init() and, inside a func­tion within our theme or plu­gin, run­ning the wp_enqueue_script() func­tion. We will also be includ­ing the Javascript in the admin­is­tra­tion area only, cre­at­ing depend­en­cies between our vari­ous cus­tom Javascript files and enqueuing the scripts on only a spe­cific page in the admin­is­tra­tion area.

How do we enqueue the Javascript?

Okay, you will need:

1. 1 x cus­tom func­tion in either your theme’s functions.php file or in your plugin.
2. 1 x selec­tion of Javascript files required by your theme or plugin.
3. 1 x add_action() line within your code.

Lets fol­low this like a recipe. The above ingredi­ents each form part of the recipe we need to fol­low in order to cor­rectly enqueue Javascript in WordPress.

1. Write a func­tion in your theme or plu­gin that will run the vari­ous enqueue commands.

This func­tion is the heart of enqueuing the Javascripts in WordPress. It tells the sys­tem which scripts to include, what they require (if any­thing) and in what order to enqueue the scripts. An example of this func­tion may look like this:
function matty_enqueue_theme_js () {
wp_enqueue_script('matty-functions', TEMPLATE_URL . 'js/functions.js', array('jquery'), '1.0', false);
} // End matty_enqueue_theme_js()

• The ‘TEMPLATE_​URL‘ con­stant can be defined in your functions.php file as:
  define( 'TEMPLATE_URL', trailingslashit( get_stylesheet_directory_uri() ) );
  Or, altern­at­ively, it can be replaced with:
  trailingslashit( get_stylesheet_directory_uri() )

Okay. Lets run through this func­tion and work out what it does.

For each Javascript file you wish to include, add another wp_enqueue_script() line to the func­tion. This line reads as follows:

The name by which I would like to refer to this Javascript file is ‘matty-​​functions‘. It is loc­ated at TEMPLATE_​URL . ‘js/functions.js’ *, requires jQuery to run and has a ver­sion num­ber of 1.0. The ‘false‘ at the end denotes whether or not the script is to be loaded in the footer of the theme (on wp_footer()). If false, the script will load in wp_head() of the cur­rent theme.

Each para­meter can be explained as follows:

$handle — A lower­case text string, no spaces, that is the “iden­ti­fier” of the Javascript file being loaded on that line. Can be used if one of your files requires another of your files in order to run.

$src — The full URL path to the Javascript file being loaded.

$deps — Does your script require any­thing to run? It could require a spe­cific lib­rary (for example, jQuery) or another of your Javascript files being loaded in (referred to by its $handle).

$ver — The ver­sion num­ber of the script being loaded. This is an optional parameter.

$in_​footer — Should the script be loaded in the footer or in the header? If set to false, the script will load in the header. This is an optional para­meter that defaults to ‘false‘.

And hey presto! We’ve got a func­tion that we can tell to include all our Javascripts!

Run the func­tion when the WordPress wp_​head() action occurs.

No sweat. We’re going to run the above func­tion on the WordPress wp_head()action (when the sys­tem ini­tial­ises). This is how we do it: add_action('wp_head', 'matty_enqueue_theme_js', 1);

Explaination? Okay.

When the WordPress wp_head() func­tion runs, add the ‘matty_​enqueue_​theme_​js‘ func­tion to the list of func­tions to run. Give it a pri­or­ity set­ting of 1 (this can be used to con­trol which func­tions execute before others).

Easy, right?

What Javascript lib­rar­ies are already bundled with WordPress?

In a word; loads. Here’s a com­pre­hens­ive list of Javascript lib­rar­ies bundled with WordPress. Try to stick to one lib­rary, as it will greatly min­im­ize poten­tial con­flicts between your scripts. Where pos­sible, be sure to use the bundled ver­sion of the script your code requires, as it will min­im­ize load times and gen­er­ally be a lot easier to work with your scripts (unless the ver­sion you require is not yet bundled with WordPress… *cough* jQuery 1.4 *cough*.).

I only want the Javascript in the WordPress amin­is­tra­tion area. How do I do that?

No sweat. Simply run the fol­low­ing script instead of the above add_action():

add_action('admin_print_scripts', 'matty_enqueue_theme_js');

To include the Javascript on only one par­tic­u­lar admin­is­tra­tion page, run some­thing like the following:

add_action('admin_print_scripts-widgets.php', 'matty_enqueue_theme_js');

The above line will enqueue the Javascript only on the wid­gets screen of the admin­is­tra­tion area.

One of my scripts relies on another. What do I do?

Remember that ‘$handle‘ para­meter we dis­cussed earlier? Lets use it.

When one script relies on another script (note: not a bundled lib­rary but another cus­tom Javascript file), the ‘handle’ para­meter is used in the ‘$deps‘ to let the script know that another script is required. Lets take a look at our func­tion again:

function matty_enqueue_theme_js () {
wp_enqueue_script('matty-some-cool-code', TEMPLATE_URL . 'js/some-cool-code.js', array('jquery'), '1.0', false);
wp_enqueue_script('matty-functions', TEMPLATE_URL . 'js/functions.js', array('jquery', 'matty-some-cool-code'), '1.0', false);
} // End matty_enqueue_theme_js()

See what we did there? We added the handle of the first line to the depend­en­cies array of the second line. Therefore, ‘matty-​​some-​​cool-​​code’ requires jQuery ** to run, and ‘matty-​​functions’ requires both jQuery and ‘matty-​​some-​​cool-​​code’ in order to run. Please note that, because I have spe­cified that my scripts require jQuery, there is no need to load the jQuery lib­rary itself on it’s own line.

Right. Lets sum it up.

What did we dis­cuss here today? We learned how to cor­rectly enqueue Javascript files in WordPress, how to cre­ate depend­en­cies between files and how to load Javascript lib­rar­ies that come bundled with WordPress.

And all the code we dis­cussed above:
function matty_enqueue_theme_js () {
wp_enqueue_script('matty-some-cool-code', TEMPLATE_URL . 'js/some-cool-code.js', array('jquery'), '1.0', false);
wp_enqueue_script('matty-functions', TEMPLATE_URL . 'js/functions.js', array('jquery', 'matty-some-cool-code'), '1.0', false);
} // End matty_enqueue_theme_js()

add_action('init', 'matty_enqueue_theme_js', 1);
I hope this post is found use­ful. If you have any quer­ies, please post them in the comments.

* TEMPLATE_​URL is a con­stant I have setup that holds the dir­ect URL path to the cur­rent theme’s dir­ect­ory. This is the path as it is typed in a web browser, begin­ning with ‘http://‘.

** Notice how jQuery is required by both Javascripts but is only loaded once in your code? This is why we use the wp_enqueue_script() action… to avoid a) mul­tiple ver­sions or instances of a script being included and b) to avoid script con­flicts because of these load issues.

Related Posts

• More tips for styl­ing the WordPress tinyMCE editor
• Styling the tinyMCE editor in WordPress
• Enhancing the com­ments list in WordPress
• Storing a Twitter user­name with com­ments in WordPress
• Getting the inform­a­tion of a root page in WordPress