Adding Scripts Properly to WordPress

Posted by Ronald Huereca / November 16, 2019 /

The following is an excerpt from the upcoming WordPress and Ajax 3rd Edition book. Please visit wpandajax.com to subscribe to updates for the new book.
Ronald Huereca
Ronald Huereca

Way back in time, pre-WordPress 2.1, it was chaos when adding scripts to WordPress. Developers would load their own versions of JavaScript files and there were a lot of JavaScript conflicts. Scripts were loaded twice, out of order, and even would load scripts when in areas that were not needed at all.

Furthermore, some themes and plugins had the JavaScript embedded within the plugin’s or theme’s PHP file just to capture a few PHP variables.  Not good!  In order to add scripts properly to JavaScript, you must always keep your PHP and JavaScript separate.  And by separate, I mean separate files.  There’s just no excuse anymore (I’ll get into this more when I cover localizing (internationalizing) scripts).

Thankfully WordPress 2.1 introduced the function called wp_enqueue_script, which enabled plugin and theme authors to load in their own scripts with a lesser need to load popular libraries like jQuery on their own. Since WordPress ships with jQuery by default, we’ll use that script in this chapter to output something to the console. It’s overkill to use a library for this, but I feel it’s appropriate to at least get a basic look on how to load a script with a dependency like jQuery.

The wp_enqueue_script function is the first step in loading your scripts properly.  Not only can you add your script, but you can also specify the dependencies (e.g., jQuery), and the version number. The function prevents duplicate JavaScript files from loading, which is always a good thing.

So How Does wp_enqueue_script Work?

The function wp_enqueue_script takes five arguments, with the last four being optional. Here’s a quick overview of the function.

wp_enqueue_script( 'handle', 'src', 'deps', 'ver', 'in_footer' );

Handle

The handle argument is a string that names your script or references someone else’s. For example, you can load the jQuery library by just using the following:

wp_enqueue_script( 'jquery' );

Likewise, if you previously registered your script using wp_register_script, you can call your script by calling:

wp_enqueue_script( 'my_script' );

Src

The src argument is asking for the URL of the file.  If you supply the src of the script, the
wp_enqueue_script function automatically registers your script for others to use (no need to use wp_register_script).

An example of wp_enqueue_script in use is: 

wp_enqueue_script( 'my_script', plugins_url( 'my_plugin/my_script.js' ) );

Theme authors would use:

wp_enqueue_script( 'my_script', get_stylesheet_directory_uri() . '/js/my_script.js' );

Deps

The deps argument is an array of dependencies.  For example, if your script requires jQuery or other JavaScript files, it’ll load these files before your plugin’s JavaScript file.

wp_enqueue_script( 'my_script', plugins_url( 'my_plugin/my_script.js' ), array( 'jquery', 'another_script' ) );

In the above example, if another_script isn’t previously registered, your script won’t be loaded.

The another_script dependency assumes you have already used wp_enqueue_script to assign it a handle and a src.

The outcome in this scenario is that jQuery and another_script will load before my_script.

Ver

The ver argument is simply the version of the JavaScript file for caching purposes.  If you are supplying your own script, it’s a good idea to supply a version. I usually see plugin or theme authors set up a PHP constant with the version number and just include that constant as the ver argument. I’ll demonstrate this when we dive into the code later on in this chapter.

The version is string-based and looks like this:

wp_enqueue_script( 'my_script', plugins_url( 'my_plugin/my_script.js' ), array( 'jquery', 'another_script' ), '1.0.0' );

As you update your JavaScript file, update the ver argument.  If you don’t, you’ll inevitably run into caching issues with WordPress.

In_footer

The in_footer argument (since WordPress 2.8) determines if the script will load in the header or footer (header is the default). You may want to load your script in the footer for performance and loading purposes.

To load your script in the footer, simply pass it a 1 (or true). Here’s a quick example:

wp_enqueue_script( 'my_script', plugins_url( 'my_plugin/my_script.js' ), array( 'jquery', 'another_script' ), '1.0.0', true );

Great care should be used when setting the scripts to load in the footer as some themes may not have this functionality built-in (the same problem exists for loading scripts in the header). In my experience, most themes have this set up correctly, so it’s less of a problem nowadays, but is something to troubleshoot in case you run into any issues.

Great, I have wp_enqueue_script Down. Now What?

You’ll have to call wp_enqueue_script from the appropriate hook (action) in WordPress. Fortunately, WordPress has two such hooks you can hook into: wp_enqueue_scripts (for the front-end) and admin_enqueue_scripts (for the admin area).

Let’s dive back into the code we worked on in the last chapter. You can view all the code samples by simply going to https://github.com/wpajax/ and look up Chapter 4. We’ll be adding a new folder and adding a simple JavaScript file that will output “Hello World” to your developer console. Hopefully, it’ll give you a good starting point, so let’s get started.

Here’s the file structure we’ll be working with.

Chapter 4 File Structure

We’ll be adding an init.js file in the js folder. It’s going to use a jQuery onload event and just output to your developer console “Hello World.”

Here’s what is in init.js:

jQuery(function($) {
	console.log('Hello World');
});

And here’s what’s in class-frontend.php:

<?php
/**
 * Primary plugin file.
 *
 * @package   Sample_WPAjax_Plugin
 */

namespace Sample_WPAjax_Plugin\Frontend;

/**
 * Load Frontend Scripts/Styles
 */
class Frontend {

	/**
	 * Register hooks needed for this class.
	 */
	public function register_hooks() {
		add_action( 'wp_enqueue_scripts', array( $this, 'load_scripts' ) );
	}

	/**
	 * Load our Front-end scripts.
	 */
	public function load_scripts() {
		wp_enqueue_script(
			'sample_wpajax_plugin',
			SAMPLE_WPAJAX_URL . '/js/init.js',
			array( 'jquery' ),
			SAMPLE_WPAJAX_VERSION,
			true
		);
	}
}

Things to notice here:

  1. We have a callable method called register_hooks that will register the WordPress action to call wp_enqueue_script.
  2. We have a method called load_scripts, which is called by the WordPress action wp_enqueue_scripts.
  3. We call wp_enqueue_script and pass in a handle, the URL to the file, a dependency (in this case jQuery), a version, and we load the script in the footer.

Finally, in class-plugin.php, we initialize the new frontend class by instantiating it and calling register_hooks:

<?php
/**
 * Primary plugin file.
 *
 * @package   Sample_WPAjax_Plugin
 */

namespace Sample_WPAjax_Plugin;

/**
 * Class Plugin
 */
class Plugin extends Plugin_Abstract {
	/**
	 * Execute this once plugins are loaded.
	 */
	public function plugin_loaded() {

		// Load frontend assets.
		$this->frontend = new Frontend\Frontend();
		$this->frontend->register_hooks();
	}
}

If all is well, you should be able to activate the plugin and browse to the frontend of your site. When you open your developer console, you should see “Hello World.”

Hello World Output

Conclusion

In this chapter, you learned what wp_enqueue_script was. We built upon our sample plugin from chapter 3 to load a frontend script that outputs “Hello World.”

You can view the finished plugin for this chapter at https://github.com/wpajax/chapter-4/.

In the next chapter, I’ll show you how to add internationalization to your script so you can have some PHP variables accessible in your JavaScript file.

Ronald Huereca
Developer at MediaRon
Ronald Huereca is the CEO of MediaRon LLC and enjoys WordPress plugin and theme development.

Connect with the Author

Posted in

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top