WordPress People, Please Enqueue Your Scripts

Or more simply, “How to Include Scripts in WordPress.”

It’s a problem I see far too often. People like to include their scripts in header.php or index.php or some other template file. Please do not do this.

It’s easy, for sure. But it’s horrible for making changes to. If you put some javascript in the template, WordPress won’t know it exists. What does this mean? Well in practice it often means things like jQuery being imported twice. And libraries like jQuery are often downloaded from CDNs, if you have one grab from Google CDN, and one from MaxCDN or your own host, then it will be downloaded twice. Or what if the versions don’t match. WordPress is a Content Management System. Let it manage.

wp_enqueue_scripts is not all that difficult to work with. I’ll admit, every time I use it I first look it up in the codex, but that only takes a few seconds. Here’s what I see:

The handle is the name WordPress will remember it as. Sometimes the handle is all you need. If you wanted to include jQuery, for example, and you wanted to get it from your WordPress instance, just use

 

. WordPress already knows where to find it and will put the code in for you. If you are adding your own script you can put any name here you want. I often come up with something like ‘stp_Animations’, I like to stick my initials in there to make sure it doesn’t conflict with any other script names.

The src is exactly what you might guess, a string of the url of where to find your script. The trick here is to refer to the right folder. You don’t want to hard code an address, so you will want to use one of three functions to get the first part of the address. plugins_url(), get_template_directory(), get_stylesheet_directory() are your friends here.

deps is the most important part here. I see it as the main reason to use wp_enqueue_script. It can sometimes be tricky to get WordPress to include your script in the order that you choose, there is no guarantee here. But the reality is, you don’t usually care what order WordPress includes your script in, do you? You only care if your script depends on another script. So if I enqueue my script wp_enqueue_script( ‘myscript’ , ‘http://steve.thomaspatel.com/js/myscript.js’, array( ‘jquery’ ) ), I don’t know when the script will be inserted, but I do know it will come after jQuery. And the reason that parameter is an array is because I can have multiple dependencies.

ver keeps track of version numbers if you are versioning your scripts. When I am enqueueing my own scripts this doesn’t usually matter to me, I’ll put a 1.0 or a 0.0.1 is often a favorite of mine. And finally there is in_footer. In general it is good practice to have your scripts loaded last, after everything else on the page has been rendered your scripts are allowed to enter the picture.

And I almost forgot to mention one of the most useful reasons for this method. Whether you use a plugin specifically to minify your js, or if you use a broader site speeder upper like W3 Total Cache, the good ones like to combine your scripts into one file. This sometimes drastically speeds up download times because it requires fewer connections with the host, and less negotiation. But how is the plugin supposed to know where to find your scripts? Or how to remove them before inserting the combined script? It has to ask WordPress, and WordPress only knows if you have enqueued your script correctly.

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>