Using custom JavaScript code in a WordPress theme or plugin is, in many cases, a given. Fortunately, WordPress comes bundled with a selection of popular Javascript libraries (jQuery, Prototype and others) for use with your plugins and themes. Many users, however, simply write the `<script>` tags in the header.php file of their theme or as part of a function in their plugin that is run in the header of the theme being used. This is a potential problem area that can have you, the developer, sitting for ages looking at your code and wondering why plugin `X` isn’t working correctly when theme `Y` is active. This guide aims to provide an understanding of how to correctly enqueue Javascript in WordPress and how to avoid potential Javascript conflicts.
Okay, what are we doing here?
We’re going to enqueue the Javascript files, used by our WordPress plugin or theme, using the correct method and the wp_enqueue_script()function. We will be adding an action to the wp_print_scripts() action and, inside a function within our theme or plugin, running the wp_enqueue_script() function. We will also be including the Javascript in the administration area only, creating dependencies between our various custom Javascript files and enqueuing the scripts on only a specific page in the administration area.
How do we enqueue the Javascript?
Okay, you will need:
- 1 x custom function in either your theme’s functions.php file or in your plugin.
- 1 x selection of Javascript files required by your theme or plugin.
- 1 x
add_action()line within your code.
Lets follow this like a recipe. The above ingredients each form part of the recipe we need to follow in order to correctly enqueue Javascript in WordPress.
1. Write a function in your theme or plugin that will run the various enqueue commands.
This function is the heart of enqueuing the JavaScripts in WordPress. It tells the system which scripts to include, what they require (if anything) and in what order to enqueue the scripts. An example of this function may look like this:
function matty_enqueue_theme_js () {
wp_enqueue_script('matty-functions', get_template_directory_uri() . 'js/functions.js', array('jquery'), '1.0', false);
} // End matty_enqueue_theme_js()
Okay. Lets run through this function and work out what it does.
For each Javascript file you wish to include, add another wp_enqueue_script() line to the function. This line reads as follows:
The name by which I would like to refer to this JavaScript file is `matty-functions`. It is located at get_template_directory_uri() . ‘js/functions.js’ *, requires jQuery to run and has a version number 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 current theme.
Each parameter can be explained as follows:
$handle – A lowercase text string, no spaces, that is the “identifier” 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 anything to run? It could require a specific library (for example, jQuery) or another of your Javascript files being loaded in (referred to by its $handle).
$ver – The version number 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 parameter that defaults to `false`.
And hey presto! We’ve got a function that we can tell to include all our JavaScripts!
Run the function when the WordPress wp_print_scripts() action occurs.
No sweat. We’re going to run the above function on the WordPress wp_head()action (when the system initialises). This is how we do it: add_action('wp_print_scripts', 'matty_enqueue_theme_js', 1);
Explaination? Okay.
When the WordPress wp_print_scripts() function runs, add the `matty_enqueue_theme_js` function to the list of functions to run. Give it a priority setting of 1 (this can be used to control which functions execute before others).
Easy, right?
What JavaScript libraries are already bundled with WordPress?
In a word; loads. Here’s a comprehensive list of Javascript libraries bundled with WordPress. Try to stick to one library, as it will greatly minimize potential conflicts between your scripts. Where possible, be sure to use the bundled version of the script your code requires, as it will minimize load times and generally be a lot easier to work with your scripts (unless the version you require is not yet bundled with WordPress… *cough* jQuery 1.4 *cough*.).
I only want the Javascript in the WordPress aministration area. How do I do that?
No sweat. Simply run the following script instead of the above add_action():
add_action('admin_print_scripts', 'matty_enqueue_theme_js');
To include the Javascript on only one particular administration page, run something like the following:
add_action('admin_print_scripts-widgets.php', 'matty_enqueue_theme_js');
The above line will enqueue the JavaScript only on the widgets screen of the administration area.
One of my scripts relies on another. What do I do?
Remember that `$handle` parameter we discussed earlier? Lets use it.
When one script relies on another script (note: not a bundled library but another custom Javascript file), the ‘handle’ parameter is used in the `$deps` to let the script know that another script is required. Lets take a look at our function again:
function matty_enqueue_theme_js () {
wp_enqueue_script('matty-some-cool-code', get_template_directory_uri() . 'js/some-cool-code.js', array('jquery'), '1.0', false);
wp_enqueue_script('matty-functions', get_template_directory_uri() . '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 dependencies 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 specified that my scripts require jQuery, there is no need to load the jQuery library itself on it’s own line.
Right. Lets sum it up.
What did we discuss here today? We learned how to correctly enqueue Javascript files in WordPress, how to create dependencies between files and how to load Javascript libraries that come bundled with WordPress.
And all the code we discussed above:
function matty_enqueue_theme_js () {
wp_enqueue_script('matty-some-cool-code', get_template_directory_uri() . 'js/some-cool-code.js', array('jquery'), '1.0', false);
wp_enqueue_script('matty-functions', get_template_directory_uri() . 'js/functions.js', array('jquery', 'matty-some-cool-code'), '1.0', false);
} // End matty_enqueue_theme_js()
add_action( 'wp_print_scripts', 'matty_enqueue_theme_js', 1 );
I hope this post is found useful. If you have any queries, please post them in the comments.
* get_template_directory_uri() should be changed to get_stylesheet_directory_uri() if the JavaScript file is within a child theme.
** 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) multiple versions or instances of a script being included and b) to avoid script conflicts because of these load issues.
Leave a Reply