One of the great features of WordPress is that anyone can extend the capability of a WordPress site. But this can also be one of the downfalls of WordPress because when someone extends WordPress the wrong way it can cause many problems and things to stop working on a site.
Have you ever installed a new plugin on your site and some functionality that worked prior to installing that plugin stops working? What do you do when the theme and three plugins all want to install jQuery? WordPress has a unique way of handling the inclusion of scripts to your WordPress site that prevents these issues from breaking your website.
If you think back to the days of coding up your HTML/CSS websites and you wanted to add a script to your site, you would simple add that script link into the < head >< /head > section of your HTML page. We do NOT want to perform this method with our WordPress theme. We do NOT want to hard-code a script file link into the header.php template file of our active theme. Why? Keep reading.
Now if you have been following these iThemes Tuesday Tutorial series you may be wanting to jump ahead and raise your hand and say, “Why not use the wp_head() hook you taught us earlier?” That would be a great idea except what if every plugin that wanted to use jQuery did this? You would then have 11 different versions of jQuery getting loaded on your WordPress site and this would cause problems. So, we do NOT want to perform this method on our site.
The Right Way
Luckily there is a right way of adding scripts to your WordPress site. WordPress has a special action hook that occurs inside the < head > section of your site. That hook is called wp_enqueue_scripts. We can hook into this placeholder with our own function which will tell WordPress everything it needs to know about what scripts we want to add to our site like:
- what version is the script
- where the script is located
- what other scripts the script we want to add depend on to function properly
- the name of the script
- and even whether we want to load the script at the top or bottom of the html page
- jQuery Masonry
- Tons of jQuery UI elements like Accordion, Autocomplete, Slider, Progressbar, Tabs, Tooltips, Dialogs, and more
- Tons of jQuery Effects like Bounce, Explode, Fade, Highlight, Scale, Slide, Shake, and more
- jQuery Hotkeys
- and many more
Let’s take the above code snippet apart. First locate the line that says wp_enqueue_script( ‘name-of-script’ );. This is simply telling WordPress to add the name-of-script script to our website. But WordPress has questions like, where is that script and does this script require any additional scripts added to our site in order to function properly. We actually provide those answers in the link above.
wp_register_script(‘name-of-script’, get_stylesheet_directory_uri() . ‘/js/custom.js’ array(‘jquery’));
Several final tips to help you remember the process:
- wp_enqueue_scripts is the action hook in WordPress we add all our scripts (and styles). The scripts in the hook name are PLURAL because we are able to add multiple scripts into the same hook.
- wp_enqueue_script is the singular function that identifies the name of the script we want to add to our site. It will live INSIDE a function that hooks into wp_enqueue_scripts. And it is the singular form of script because it deals with only one script at a time. (This is one of the things that trips up new WordPress developers, figuring out which one is the singular form and which one is the plural form.)
- wp_register_script is the way we communicate to WordPress about the location, dependencies, handle/name, version number and more.
If you would like to dive deeper into these functions, I encourage you to check out these pages of the WordPress Codex: