An Introduction to Asset Handling in WordPress

Share this article

As a WordPress theme or plugin developer, there will come a time during your development process that you will need to include third party scripts or stylesheets in your plugin or theme. Sure, simply linking the assets in the header or footer would definitely work, but adhering to standard practice using the provided WordPress API will ensure that your theme or plugin will play nice with other plugins in the WordPress ecosystem.

If you want to provide maximum compatibility with other plugins and themes available, asset handling in WordPress is definitely a skill you should master.

This article is targeted to the beginner WordPress developer, with the assumption that you have a working knowledge of how WordPress action and filter hooks work.

WordPress Asset Handling

The Basics

WordPress has provided a few basic functions to help the developer correctly load custom assets of their theme or plugin. The four main functions that you will use frequently are wp_register_script, wp_enqueue_script, wp_register_style and wp_enqueue_style.

Let’s go through these four major functions one by one.

wp_register_script( $handle, $src, $deps, $ver, $in_footer );

I’m just going to go ahead and paste the description provided in the codex for this function.

Registers a script file in WordPress to be linked to a page later, which safely handles the script dependencies.

Only $handle and $src arguments are required, while the latter three is optional.

$handle is the name of the script and should be unique. This is the most important part when enqueuing your script as the $handle will be the identifier of which script is to be loaded.

$src is the URL to the script. You can get the proper URL using provided built in functions such as plugin_url(), get_template_directory_uri() and get_stylesheet_uri(). For a remote URL, protocol-agnostic URL such as //ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js can be used.

$deps should be an array of scripts’ handle of which your script depends on. By defining them here, WordPress will load those dependencies first before loading your custom scripts.

$ver is simply your script’s version, and it will be appended as a query string in your src parameter of script tag.

$in_footer is a Boolean flag that will tell WordPress whether to load your script in head section of document, or in the footer instead. Make sure that the theme properly includes wp_head() and wp_footer() correctly for this to work.

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

This function is similar to wp_register_script with the exception that only $handle parameter is required. If you have already registered your scripts prior to execution using wp_register_script, you can directly enqueue them using wp_enqueue_script('your-registered-handle').

This is the actual function that will link your script to the generated page, so this function needs to be used in conjunction to wp_register_script.

wp_register_style( $handle, $src, $deps, $ver, $media );

This is the counterpart function for wp_register_script, only that this function will handle all your stylesheet registration. Let’s go through each of the arguments for this function.

$handle is the unique identifier to your stylesheet, similar to the one for your wp_register_script and wp_enqueue_script. This is a required parameter and your handle should be unique to your WordPress installation.

$src will be the URL to your CSS file. Again, you can either link it to the local file in your theme or plugin, and it also works with a remote URL.

$deps will handle all your CSS’s dependency, which should be defined as an array of the styles handles.

$ver is optional parameter where you can define your CSS version, and it will be appended to the URL as the query string as well.

$media is the CSS media types of your CSS. The complete list of acceptable value can be found on this page.

wp_enqueue_style( $handle, $src, $deps, $ver, $media );

This function will link your CSS to the generated page, similar to how wp_enqueue_script works. So basically, you can either enqueue your previously registered CSS, or you can enqueue the CSS on the go by defining the $src parameter as well.

When Do We Enqueue Them?

There are three proper hooks recommended to enqueue your scripts and stylesheets.

Use wp_enqueue_scripts action hook whenever you want to enqueue your script to the front end of your site. Don’t be confused with the name, as the same hook can be used to enqueue your style as well.

How about the admin page? Well, you can hook your enqueue function on the admin_enqueue_scripts and all your scripts and styles will be loaded on the administrative side of things correctly. To load your scripts and styles specifically on the login page, login_enqueue_scripts action hook is provided.

Enqueue Versus Register

At a glance, it seems redundant to register your scripts and stylesheets first, before enqueuing them. So why do we need to use wp_register_script and wp_register_style in the first place, when in reality we can directly just use wp_enqueue_script and wp_enqueue_style instead? Well, technically, you don’t need to.

But if you want to dynamically load your scripts and stylesheets based on various conditions, you better register them first so you can enqueue them anytime you want at any point of execution without repeating yourself.

Let’s look at this simple example:

wp_register_script( 'my-custom-js', ... );
	wp_register_script( 'my-second-js', ... );

	if ( is_page( 32 ) ) {
		wp_enqueue_script('my-custom-js');
	}

	if ( $var ) {
		wp_enqueue_script('my-second-js');
	}

Based on this snippet, you can see that we first register two custom scripts, my-custom-js and my-second-js. Based on several conditions, in this case, when the page loaded is of ID 32, or $var is set to true, we can dynamically enqueue them.

Registering them first is also useful whenever you want to rely on the same script on a different part of the website. As pointed out earlier, there are two different hooks that need to be used in order to load your scripts and stylesheets on front end facing side and administrative side. So by registering them first, you would just need to register them once, and enqueue them in both related hooks.

What’s Already Included?

Many developers resort to including a third party library of their own, which then leads to big plugin or theme sizes and the potential for incompatibilities. WordPress includes some useful JavaScript libraries of its own, so why not utilize that instead?

An exhaustive list of what’s already included with its respective handle is listed on this page under Handles and Their Script Paths Registered by WordPress section. This list may get outdated, so if you want to peek directly at the source, take a look at wp-includes/script-loader.php source code, specifically inside the wp_default_scripts function.

You can find a lot of useful libraries that can be reused without the need of shipping it inclusively with your plugin or theme.

Additional Functionalities

Besides the four main functions to register and enqueue your scripts and styles, WordPress also provides a handful of functions that can help with regards to managing your plugin or theme assets. Let’s take a look at some of them.

Making Your PHP Variables Available on the Client Side with wp_localize_script

Although this function is primarily used to provide proper localized translation of strings (thus the name) to your client side code, it can be used virtually to make any data that you have on the server side available on the client side as well.

wp_localize_script( $handle, $name, $data );

As the above code suggests, this function will accept three required parameters. $handle refers to the handle of the script you are attaching the data for. It is important to note that the script must be either registered or enqueued first to make sure wp_localize_script works correctly.

$name is the variable name that will be available on the client side, and will contain all your specified $data that you defined in an array.

Here’s a simple snippet to explain what this function does:

wp_register_script( 'my-custom-js', ... );

	$args = array(
				'foo' => 'bar'
			);

	wp_localize_script( 'my-custom-js', 'my_var', $args );
	wp_enqueue_script( 'my-custom-js' );

When the my-custom-js is enqueued, WordPress will handle the given data to make it available on the client side code. Since the $args will be JSON-encoded and assigned to the variable called my_var, you can always access the value back in your script like you normally do on any JavaScript object.

<script>
	console.log( my_var.foo ); // print out "bar" in console
</script>

Enqueuing All Related Scripts for WordPress Media Library with wp_enqueue_media

If you want to use the native WordPress media uploader in your plugin or theme, you will need to enqueue all the related assets required before you can access all the available related APIs. To make things easier, WordPress provides a helper function that will help you enqueue all the related scripts, styles and templates related to the Media API.

wp_enqueue_media( $args );

The only parameter is $args, which is optional, and can be used if you want to enqueue all related assets associated with a specific post. I won’t delve too much into how to use the available API to implement the native media uploader in your plugin or theme since it deserves an article on its own, but here’s a little snippet to get you started.

wp_enqueue_media(); 						// basic usage, enqueue all related scripts, styles and templates
wp_enqueue_media( array( 'post' => 32 ) ); 	// enqueue all related assets for post with ID of 32

Adding Metadata to Stylesheet with wp_style_add_data

This function works only for the stylesheet, and is particularly useful when you want to add metadata such as conditional comments, RTL support and an alternate title to your custom stylesheet.

wp_style_add_data( $handle, $key, $value );

All three parameters are required. Let’s go through each of them to see what they represent.

$handle is the specific stylesheet handle that we want to add our metadata to.

$key is the data point. There are five accepted values which are conditional, rtl, suffix, alt and title

$value is the data string in conjunction to the previously specified $key.

Here’s a example snippet on how we can take advantage of this function to load our stylesheet specific to Internet Explorer only.

wp_enqueue_style( 'custom-ie-style', get_template_directory_uri() . '/css/ie.css' );
wp_style_add_data( 'custom-ie-style', 'conditional', 'IE' );

That’s it! Once your stylesheet is linked to the generated page, this is what is actually printed on the head part of the document.

<!--[if IE]>
		<link rel="stylesheet" id="custom-ie-style-css" href="http://www.example.com/wp-content/themes/example/css/ie.css" type="text/css" media="all">
<![endif]-->

Automatically Cache Busting Using filemtime

This is not actually WordPress specific, but I kept finding myself using this code time and again in my client projects. What it actually does is take advantage of the version argument in the wp_enqueue_script and related functions as a cache busting method by checking the file last modified time. Obviously, this only works for the local file, since we are using filemtime PHP function to detect the last modified timestamp of that file.

Here’s how we define the version argument, in example of wp_enqueue_script function:

wp_enqueue_script( 'my-custom-js', get_template_directory_uri() . '/js/custom.js', array(), get_template_directory() . 'js/custom.js' );

Note that filemtime requires the path of your file, not the URL, thus in above snippet, we are using get_template_directory function instead to get the path to our theme directory.

From now onwards, any modifications to the file will result in different version value, and our query string will get updated accordingly.

Conclusion

As a responsible WordPress developer, it’s vital that you to apply best practices to your development process, and that includes learning how to properly load assets in your custom plugin or theme. This will ensure your plugin or theme is compatible with other plugins or themes, as well as reducing conflicts and bugs as WordPress evolves.

Frequently Asked Questions on Asset Handling in WordPress

What is the significance of asset handling in WordPress?

Asset handling in WordPress is crucial for the efficient functioning of your website. Assets include scripts, styles, images, and other files that contribute to the overall look and functionality of your site. Proper asset handling ensures that these files are loaded correctly and efficiently, improving your site’s performance and user experience. It also helps in avoiding conflicts between different scripts and styles, ensuring that your site functions smoothly.

How can I enqueue scripts and styles in WordPress?

Enqueuing is the recommended method of linking JavaScript and CSS files to WordPress. To enqueue scripts, you can use the wp_enqueue_script() function, and for styles, the wp_enqueue_style() function. These functions tell WordPress when to load the files, where to load them, and in what order, ensuring that your scripts and styles are loaded correctly.

What are dependencies in WordPress asset handling?

Dependencies are scripts or styles that must be loaded before a particular script or style. For example, if you have a script that relies on jQuery, then jQuery is a dependency for that script. When you enqueue a script or style in WordPress, you can specify its dependencies, and WordPress will automatically handle the loading order to ensure that all dependencies are loaded first.

How can I handle assets in a WordPress plugin?

Handling assets in a WordPress plugin is similar to handling them in a theme. You can use the wp_enqueue_script() and wp_enqueue_style() functions to enqueue your scripts and styles. However, you need to use plugins_url() function to get the correct URL for your plugin assets.

How can I optimize asset handling for better performance?

There are several ways to optimize asset handling in WordPress for better performance. These include minifying your scripts and styles, combining multiple files into one, and using a content delivery network (CDN) to serve your assets. You can also use plugins that handle these optimizations automatically.

What is the role of wp_register_script() and wp_register_style() functions?

The wp_register_script() and wp_register_style() functions allow you to register a script or style with WordPress without actually enqueuing it. This can be useful if you have a script or style that is used in multiple places and you want to avoid enqueuing it multiple times.

How can I handle assets in a child theme?

When handling assets in a child theme, you need to enqueue them in your child theme’s functions.php file. However, you also need to ensure that the parent theme’s styles are loaded first. This can be done by specifying the parent theme’s handle as a dependency when enqueuing your child theme’s styles.

How can I handle inline scripts in WordPress?

Inline scripts can be handled in WordPress using the wp_add_inline_script() function. This function allows you to add extra code to a registered script, which can be useful for adding configuration data or initializing a script.

What is asset versioning and how can I use it?

Asset versioning is a technique used to force browsers to download a new version of an asset when it has been updated. In WordPress, you can specify a version number when enqueuing a script or style. When you update the asset, you can change the version number to force browsers to download the new version.

How can I handle localization in WordPress scripts?

Localization in WordPress scripts can be handled using the wp_localize_script() function. This function allows you to pass data from PHP to your JavaScript files, which can be useful for translating text or passing configuration data.

Firdaus ZahariFirdaus Zahari
View Author

Firdaus Zahari is a web developer who comes all the way from Malaysia. His passion revolves around (but is not limited to) WordPress and front-end development.

asset handlingChrisBpluginplugin developmentpluginsWordPress
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form