WordPress is an open-source project with low barriers to entry for developers and users alike. With that comes many ways to do a variety of tasks. But despite the many workarounds one thing you should always do is add scripts to WordPress themes and plugins the “WordPress Way”.
That and capitalize the P in “WordPress”. Looking at you /r/Wordpress.
https://giphy.com/gifs/do-not-want-BtedgmzGNCiuk
Why do we use wp_enqueue_scripts to include CSS and JavaScript?
A typical WordPress site does not exist in a vacuum. There’s a ton of themes and plugins that can be added to a WordPress site bringing with it different functionality.
Enqueueing scripts1 allows developers of said themes and plugins the ability to make sure their styles and scripts are being added in efficiently, when they’re needed, and with the proper dependencies.
Say your plugin includes a script that is dependent on jQuery to function properly. Using wp_enqueue_script allows you to set jQuery as a dependency and WordPress handles the rest.
It also allows us to avoid duplicate scripts using the $handle parameter (which we’ll cover shortly). This helps to prevent several themes and plugins all trying to load their own copy of a script2.
Getting the Hook Setup
The first step to adding scripts is hooking into the wp_enqueue_scripts action. This is typically done in a theme’s functions.php or a plugin’s activation functions.
We’ll be using the built in add_action( $tag, $function_to_addd ); in order to connect a custom function we’re making to hold our wp_enqueue_script() and wp_enqueue_style() calls. We’ll call this function pre_properly_enqueued_scripts(). With pre_ of course represenenting our prefix used on all functions created in our plugin or theme3.
Here’s the code:
function pre_properly_enqueued_scripts() {
// This is where we'll enqueue our scripts and styles soon
}
add_action( 'wp_enqueue_scripts', 'pre_properly_enqueued_scripts' );
Scripts vs Styles
Now that we’ve hooked into the wp_enqueue_scripts action we’re ready to add in our script or style. While both of those use the same wp_enqueue_scripts hook, they use different functions. JavaScript files use wp_enqueue_script and CSS files use wp_enqueue_style.
The functions take almost identical arguements with the only difference being the final argument for each. Let’s go over the 4 they share first.
$handle – The name of the script or style. This can be used to identify the script for other purposes such as removing in cases of conflict. Here’s a list of handles used in core.
$src – Where the file is located.
$deps – This is where you can declare a script or scripts, using an array, that the new script is dependent on.
$ver – Sets a version number for the script. This is great for cache busting.
For the final parameter wp_enqueue_script uses $in_footer which defaults to true and loads the script in the footer. If set to false it will load your script in the the head element.
wp_enqueue_style uses $media which can be used to set the media the stylesheet displays on such as ‘all’, ‘screen’, ‘print’ or ‘handheld’.
Here’s an example loading in a script and style.
function pre_properly_enqueued_scripts() {
wp_enqueue_style( 'slider-style', get_template_directory_uri() . '/css/slider.css', array(), '1.1', 'all');
wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array ( 'jquery' ), 1.1, true);
}
add_action( 'wp_enqueue_scripts', 'pre_properly_enqueued_scripts' );
Showing Scripts or Styles Only When Needed
One common cause of WordPress slowdown is unnecessary scripts being loaded on sites when they aren’t needed. For example, if we had a gallery that could only be used on a post single page we could check that we’re on a single detail page using is_singular() then load the script if we are.
function pre_properly_enqueued_scripts() {
wp_enqueue_style( 'slider-style', get_template_directory_uri() . '/css/slider.css', array(), '1.1', 'all');
wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array ( 'jquery' ), 1.1, true);
if ( is_singular() ) {
wp_enqueue_script( 'single-script', get_template_directory_uri() . '/js/single-script.js', array ( 'jquery' ), 1.1, true);
}
}
add_action( 'wp_enqueue_scripts', 'pre_properly_enqueued_scripts' );
Registering Scripts and Styles
The wp_register_script and wp_register_style functions allow you to handle all of the script setup before actually calling the script. This can be useful in instances where you’ll be adding a script in several areas of the code.
Registered scripts will also be enqueued automatically when listed as a dependency for another script that is enqueued later. This can help to keep your code clean and tidy.
function pre_properly_enqueued_scripts() {
wp_register_script( 'registered-script', get_template_directory_uri() . '/js/script.js', array ( 'jquery' ), 1.1, true);
wp_register_script( 'another-script', get_template_directory_uri() . '/js/script.js', array ( 'jquery' ), 1.1, true);
if ( is_singular() ) {
wp_enqueue_script( 'single-script', get_template_directory_uri() . '/js/single-script.js', array ( 'jquery', 'registered-script', 'another-script' ), 1.1, true);
}
}
add_action( 'wp_enqueue_scripts', 'pre_properly_enqueued_scripts' );
Hopefully this guide helps you add scripts to WordPress themes and plugins. Thanks for reading and feel free to leave any questions in the comments!
- Fancy talk for adding.
- As long as the $handles are the same. A way to standardize these would be great.
- Because we’re all doing that right? It is a standard code practice.
