Including Javascript and CSS Files In A WP Theme

Whether you are tackling your first WordPress theme or adding javascript/css to an existing theme this post provides a brief overview of how to properly link javascript and css. This post assumes a basic understanding of php, html and WordPress and that you are comfortable editing theme files. With that being said let’s get started!

For this post I will be using an example with three files typically needed to load a jquery image slider. The three example files are

  • jquery.js– jquery library
    • jquery needs to be loaded before the image slider since the image slider depends on the jquery library
  • image-slider.js – the javascript file for the image slider
  • image-slider.css – the stylesheet for the image slider

Please note that this guide covers how to link the javascript and css files. Most javascript plugins will not work until the a function to activate the plugin is called. Please refer to the documentation for the jquery plugin you are using for help with this.

Traditional script and style linking

When coding an html page stylesheet and javascript files are loaded into the section of the document. This ensures they load before the body (and any reference to them) and would look something like this:

<head>
<!-- load jquery library -->
<script type="text/javascript" src="js/jquery.js"></script>
<!-- load javascript image slider after jquery library -->
<script type="text/javascript" src="js/image-slider.js"></script>
<!-- load stylesheet for image slider -->
<link rel="stylesheet" href="css/image-slider.css" />
</head>

There are a few things going on here. First, the source of the files being linked are a relative path. That means if the html document is not in the correct location relative to where the javascript and css files are. The alternative is to use an absolute path such as http://www.example.com/js/jquery.js

Second, the order of the links matters. The image slider has to be loaded after the jquery library since it depends on it to run.

You can open your theme’s header.php and add links like the ones above and they will work. This is generally considered bad practice and is not recommended.

Advantages to managing your scripts and stylesheets with WordPress

  • WordPress manages dependancies
    • Once WordPress knows that your image slider depends on jquery it will automatically load jquery first
  • Scripts and styles are managed called in functions.php
    • The code is re-usable. If you want to add it to another theme or create a plugin you can do so easily. Functions.php is also the proper place for code that increases theme functionality.
  • Use php if statements or WordPress functions to decide when to include your scripts/styles
    • An good example if this is if the image slider is only being used on the front page (assuming a static front page is set). Wrap the code in  and now the scripts/styles are only loaded on the front page. Loading only files you need will not only increase your page speeds but it is also considered best practice.

Introduction to wp_enque_script and wp_enque_style

wp_enque_script and wp_enque_style are WordPress functions that allow you to safely add scripts and styles to WordPress head function and is recommended by WordPress; and if you plan on submitting your theme to the repository it is REQUIRED.
As mentioned above these are called from a theme’s functions.php file. If you aren’t familiar with the functions.php file you can read about it on the WordPress Codex which has a good explanation of when to use functions.php and when to use a plugin.

Learning by example

I learn best by example so here is the code that would go into functions.php to properly register the example files.

<?php
//start function to register image slider script
function image_slider_scripts(){
    //register the image slider script with WordPress
    wp_register_script( 'image-slider-script', get_template_directory_uri().'/js/image-slider.js', array( 'jquery' ) );
    //add the image slider script to WordPress' que of scripts
    wp_enqueue_script( array('image-slider-script') );
}//end function to register image slider script

//hook the image_slider_scripts function to wp_enque_scripts action
add_action( 'wp_enqueue_scripts', 'image_slider_scripts' );

//start function to register image slider styles
function image_slider_styles(){
    //register the image slider stylesheet with WordPress
    wp_register_style( 'image-slider-style', get_template_directory_uri().'/css/image-slider.css');
    //add the image slider stylesheet to WordPress' que of stylesheets
    wp_enqueue_style( array('image-slider-style' ) );
}
//end function to register image slider stylesheet

//hook the image_slider_styles function to wp_enque_scripts
add_action( 'wp_enqueue_scripts', 'image_slider_styles' );
?>

Breaking it down

We have two functions and two hooks above. Lets looks at the functions first. image_slider_scripts and image_slider_styles are very similar. I am going to explain image_slider_scripts and let you apply the information to image_slider_styles.

wp_register_script

Our functions uses three parameters of wp_register_script.

  • Script handle (string)
    • The handle is like an alias. It will be used to add the script to WordPress’ queue of scripts. This is not the same as the file name but needs to be unique and preferably descriptive.
  • Source (string)
    • Used to tell WordPress where the file is located.
  • Dependancies (array)
    • Previously registered scripts that the script being registered is dependent on. In our example we are using jquery as a requirement as our script.
    • Useful if you need to register multiple scripts
    • Scripts referenced here must be registered
    • Scripts are referenced by handle

A few things to pay attention to

  • We used get_template_directory_uri() to get the active theme’s location. This creates an absolute path and changes based on the active theme (re-usable code)
  • We used WordPress’ built in jquery as a dependency for our script. Make sure that the version of WordPress you are using (hopefully the most current version) has the minimum jquery library version for the script you are using. If you need to register a newer version of jquery look at how to do so on the WordPress Codex.

wp_enque_script

The only parameter here is an array of registered scripts to add to WordPress’ list of scripts to queue up. Note that this is an array and if you registered multiple scripts (who says you can only have one jquery plugin?) you can queue them all up.
wp_enque_script is what you would wrap in a conditional if you only need the script on certain pages. Our example above was

<?php if( is_front_page() ) { } ?>

which will only enque the script on the front page.

add_action

Finally we use add_action to hook our function to the wp_enque_scripts action. If you don’t know what hooks and actions are you can read more about them on the WordPress Codex

Repeating for the stylesheet

Repeat the process above with wp_enque_style to register your css stylesheet. As I stated at the beginning of the post you will still need to call the jquery function to activate your plugin. This is typically documented on the plugins site or in a read-me file accompanying the download.

How Far Will You Take This

This is a basic example but you can see the potential here. This post is geared toward a theme, but the same principal applies to a plugin. Just replace the get_template_directory_uri() function with the plugin equivalent.

As you can probably tell from my reference to it, I highly recommend the WordPress Codex as a resource. Happy coding!

No Comments
Recent Blog Posts in Web Development
You’ve been putting off a web redesign for far longer than you care to admit. Now the numbers demand it: Your conversion rate is falling faster than Miley Cyrus’s reputation in a...
The quick answer is absolutely! The need for responsive website design is a tricky concept for many business owners to grasp.  People are conditioned to be skeptical and say “no” when they...
WordPress Options Page Plugin Tutorial I use option pages quite a bit when doing WordPress development. So much so that I created an open source WordPress plugin and would like to share...