Adding Custom JavaScript

Applies to: Theme Blvd Framework 2.6+

I’d imagine most people reading this, and wanting to add their own custom JavaScript to their WordPress website, probably already have a basic idea of how JavaScript works in web development, in general. So in this tutorial, I’ll outline how to get all this setup properly from your Theme Blvd child theme, to begin incorporating your custom scripts.

And if you’ve read about all of this before, feel free to skip to the code roundup at the end of the article.

WordPress Theme Handbook: Including CSS & JavaScript

Overview

Whether you’re incorporating third-party scripts or your own custom-written JavaScript into your WordPress website, it’s important to do it correctly, using WordPress’s enqueue system. So, this will require some basic PHP understanding.

Many people new to WordPress development, but familiar with including scripts generally in web development, often want to just copy header.php to their child theme directory and start including scripts directly within the <head>. — Don’t do this. Keep reading!

I’d suggest organizing all of your JavaScript files within a directory, assets/js/ of your child theme. Then, from your child theme’s functions file, you’ll enqueue those scripts.

How-To

Now, I’ll outline specifically how to do everything discussed in the last section.

File Organization

First, you’ll need to put all of your JavaScript files within your child theme. Personally I like to create a directory called /assets, where I then organize all of my assets — i.e. JavaScript files, CSS files, images, etc.

So, create a directory called /assets and a directory within that called /js, and then place your third-party JavaScript files in it.

/assets/js/foo.js
/assets/js/bar.js

And if you’re wanting to incorporate your own, custom written JavaScript, make sure to create a file for that, as well.

/assets/js/script.js

Note: If you are including third-party JavaScript files, you’ll most likely be writing your own JavaScript also, in order to make those run.

Setup Your Custom JavaScript File

Now, if you’ve decided to create your own custom JavaScript file, there’s a good chance you’ll want to utilize jQuery. — jQuery is a JavaScript library, that’s extremely popular in the WordPress community. With almost any theme you use, and definitely including your Theme Blvd theme, it’ll already be running on your website, anyway.

So, if you’d like to utilize jQuery, here’s an example of how to set up within your script.js file, when DOM is ready.

jQuery(document).ready(function($) {

	"use strict";

	// All of your custom JavaScript, which can utilize 
	// jQuery, with DOM ready...
	// $('.foo') ...

}(jQuery));

Hook a Function for Your Scripts

Next, we need to set up a function and hook it to wp_enqueue_scripts, which is where WordPress processes included scripts and stylesheets. You’ll do this from your child theme’s functions.php.

/**
 * Add any javascript or CSS files.
 */
function my_scripts() {

   // Include stylesheets and scripts...

}
add_action('wp_enqueue_scripts', 'my_scripts');

Enqueue Your Scripts

And then we need to actually enqueue our scripts. So, within the my_scripts() function you just created, we need to call wp_enqueue_script() for each script we’re including.

wp_enqueue_script( 'foo', esc_url( get_stylesheet_directory_uri() . '/assets/js/foo.js' ) );

In the above line, you can see we’ve passed in the following two parameters to wp_enqueue_script() —

A unique handle for the script.
The URL to the JavaScript file in our child theme.

And if any of our scripts, require other scripts outside of what we’re doing to load before it, we can pass an array of their handles, for the third parameter. For example, if our “foo” script required that jQuery be loaded, we’d modify it like the following.

wp_enqueue_script( 'foo', esc_url( get_stylesheet_directory_uri() . '/assets/js/foo.js' ), array('jquery') );

Note: If you’re including custom CSS files, you’ll do that within this function, as well, using wp_enqueue_style(). This might seem strange, but it was announced awhile back that separate hooks for enqueueing CSS files have been deprecated. It’s now considered best practice to enqueue all stylesheets and scripts in a single function, hooked to wp_enqueue_scripts. Learn More

Conclusion

So here’s a roundup of everything we’ve discussed through the article, putting it all together.

First, you’ll organize all your scripts in a directory of your child theme like /assets/js/, including your custom script.js file.

/assets/js/foo.js
/assets/js/bar.js
/assets/js/script.js

And if you’re utilizing jQuery from within your custom script.js file, it might be set up something like the following.

jQuery(document).ready(function($) {

	"use strict";

	// All of your custom JavaScript, which can utilize 
	// jQuery, with DOM ready...
	// $('.foo') ...

}(jQuery));

And in order to include those scripts, your child theme’s functions.php should have something like the following.

/**
 * Add any javascript or CSS files.
 */
function my_scripts() {

    // Third-Party Scripts
    wp_enqueue_script( 'foo', esc_url( get_stylesheet_directory_uri() . '/assets/js/foo.js' ) );
    wp_enqueue_script( 'bar', esc_url( get_stylesheet_directory_uri() . '/assets/js/bar.js' ) );

    // My Custom Script (requiring jQuery)
    wp_enqueue_script( 'my-script', esc_url( get_stylesheet_directory_uri() . '/assets/js/script.js' ), array('jquery') );

}
add_action('wp_enqueue_scripts', 'my_scripts');