Let’s lay some groundwork:
- This example would go in your functions.php file.
- This example assumes your theme is a parent theme.
In this example, I’m registering four scripts, and enqueuing two. I’ll explain it afterward.
Now let’s break it down
We are using an action hook called wp_enqueue_scripts(). It’s your best friend. This hook ensures that your function is registering and enqueuing scripts in the right place and only on the front end.
We’ve prefixed our function. Because, you need to prefix all the things. Use a prefix that makes sense, but isn’t “wp” or something else that could be used by core or other plugins. Your full initials, sitename, etc. are good possibilities.
As a sidenote, I recommend adding the action in your own theme setup function.
We’re registering the scripts with wp_register_script(). Read that page. Get in the practice of providing every parameter of the function every single time you register a script.
- Handle – A name this script will go by. This is how you will enqueue it the short way, or if your user has a child theme and doesn’t want your script, they can dequeue it with this handle.
- Source – The path to the file. I used get_template_directory_uri(), which is a WordPress function that finds the parent theme directory. Never, ever, hard code the path with /wp-content or anything else. Use this function. It works. It’s great. If you are registering your script in a child theme, use get_stylesheet_directory_uri() instead. It’s the same thing, for child themes.
- Dependencies – These are the scripts your script depends on. You may recognize my scripts I’m loading. They’re two different slider scripts. They both depend on jQuery. You can pass multiple dependencies in this array, if necessary. For the script called “info-carousel-instance”, it relies on the “info-caroufredsel” script. Therefore when I enqueue “info-carousel-instance”, WordPress will know it needs to enqueue “info-caroufredsel” as well, if it hasn’t been enqueued already.
- Version – The version of the script you are loading. If you update your script, you can bump the version, and when you change the version here, WordPress will be sure to load the new one, and reset any caching that’s been used on the previous version of your script.
- Load in footer – If you set this to true, your script will be loaded in the footer, and therefore after much of the rest of the page has loaded. I always do this for things like sliders, because that way my slider script won’t prevent more important things on my page from loading. Just think about what you’re loading when you consider whether or not to do this.
wp_enqueue_script() will enqueue scripts.
Definition: to place something into a queue; to add an element to the tail of a queue (line).
This function simply puts the script it is enqueueing in line to be loaded onto the page. WordPress is also smart enough to know if a script you are trying to enqueue has already “been through the line”, if you will, and won’t load the same scripts more than once. Whenever you see a website loading jQuery mutliple times, you now know why – they aren’t enqueueing, or at least not properly.
wp_enqueue_script() takes the same arguments as wp_register_script(), but if you register your scripts first, you can just call them by the handle in wp_enqueue_script, as my example above shows.
As of WordPress 3.3, you can even enqueue scripts in specific page templates. It will load the script in the footer automatically! For instance, I could have enqueued the “home-page-main-flex-slider” script directly in the template part with the slider code.
Register vs. Enqueue
In our function, we’re registering four scripts, and enqueing two. Registering a script makes it available for use. Enqueuing actually pulls the script to the theme. You can register without enqueuing. But to load the script on the page, you need to enqueue. If you register the script as I show, you can then enqueue it by its handle alone. If you don’t register it ahead of time, you’ll need to provide the full parameters in the enqueue function.
The reason I register all of my scripts in this function is simple: it helps me keep track. Sure, I could just enqueue them all in this function with conditionals, but sometimes conditionals get confusing, and I like to take advantage of the ability to enqueue in templates, because it’s simple. I could also skip the register function for the scripts I enqueue right away, but again, I do it for organization. I register them there, together, so that I know what I’ve got and I know what I’m loading on every page versus in specific places. I also tend to make notes in comments by the register function to note where I’m enqueuing, if not immediately.
To load scripts in plugins, plugins_url() will replace get_template_directory_uri() for the path, and your function would be in your plugin file instead of functions.php. To load them in the admin, you’d use the admin_enqueue_scripts() function instead of wp_enqueue_scripts().
But this tutorial is just to show you how to load scripts in themes – meant for the frontend. Please start doing this. If you aren’t, you are doing yourself and your customers (whether buyers of themes or clients) a disservice and certainly causing future headaches.
Also, you’ll see I used the version of jQuery included in WordPress. So should you. You’re making a theme. Use the jQuery included with WordPress. It will always be up to date and compatible with core. It will always work. I’ve seen Otto argue with enough people about this (including me). He’s right. If you think Google’s jQuery is better, use this plugin, or recommend it to your users. For themes you release, just use the WordPress bundled version.
I hope this has helped clear things up for some of you. I’m not the first person to write about it. But maybe I helped it click for some. And as Carl Hancock said (he deals with conflicts daily), “it needs to be drilled into them [me, you, all of us]. So the more articles the better.” Oh, and if I screwed something up, or you have something to add, please let me know.