Categories
English WordPress

wp_enqueue your scripts and styles.

The ease of making a WordPress theme is both a blessing and a curse. It allows people to get started with programming relatively easy — most hosting providers have PHP / MySQL, and the majority have a WordPress quick-install. However, this easiness comes with a dangerous pitfall — it’s easy to do the wrong thing. The classic example of this is query_posts (hint: never use it).

Today, I’ll talk about wp_enqueue_script and wp_enqueue_style. If you have ever made a plugin that requires additional stylesheets or scripts in the front-end, you know exactly what this is (and why it’s important).

The easy way out in this situation is to manually write scripts and styles in header.php like this:

...
<script src="<?php echo get_template_directory_uri(); ?>/hello.js"></script>
...
<?php wp_head(); ?>
...

Although this will work, you may start to notice funny things happening when you want to use jQuery.

...
<script src="<?php echo get_template_directory_uri(); ?>/hello.js"></script>
<script src="<?php echo get_template_directory_uri(); ?>/my_jquery.js"></script>
...
<?php wp_head(); ?>
...

The problem here is that WordPress actually uses jQuery internally for the admin bar. And, it doesn’t know that you’ve packaged your own version of jQuery — so it actually loads twice, when the admin bar is showing. This can cause problems that are time-consuming to fix, and just a waste of time.

WordPress has a mechanism to deal with this, wp_enqueue_script and wp_enqueue_style. These functions will determine the order of scripts and styles based on dependencies, and will only output the styles / scripts that are needed. This kills a few birds with one stone: loading everything in the correct order, making sure nothing is loaded twice, and not wasting bytes on scripts or styles that won’t be used by the current page.

Enough talk! Let’s get into the code.

First, you’ll need a functions.php, with the following code.

/**
 * Enqueue theme scripts and styles
 */
add_action( 'wp_enqueue_scripts', 'THEME_NAME_register_scripts' );
function THEME_NAME_register_scripts () {
  // wp_register_script( script identifier, absolute URI, array of dependencies, version )
  wp_register_script('home', get_template_directory_uri() . '/js/home.js', array('jquery'), filemtime(dirname(__FILE__) . '/js/home.js'));

  if (is_home()) {
    wp_enqueue_script('home');
  }
}

In this example, there is a JavaScript file called “home.js” in the “js” directory. This file requires jQuery, so it will be loaded after jQuery has finished loading. At the bottom of the function, the is_home() conditional is used to load the script only when the home page is showing.

Instead of using conditional tags in the wp_enqueue_scripts action, you can also register your scripts in the enqueue action, then enqueue them in the actual template file. Add the following to the template file, before get_header();:

add_action('wp_enqueue_scripts', function() { wp_enqueue_script('home'); }, 15);

This will load the ‘home’ script that we set up in the earlier snippet.

Have fun! I would be interested to hear feedback — any cool uses of wp_enqueue, et cetera.

Documentation

The syntax of wp_enqueue_style and wp_register_style is similar to the script counterparts, and they go in the same wp_enqueue_scripts action.

Documentation for wp_enqueue_style

Documentation for wp_register_script, including the scripts that WordPress has pre-packaged for you!

Documentation for wp_enqueue_script