Adding Scripts to WordPress the Right Way

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

Before we get into how to tell WordPress all about the script we want to add it is important to understand that WordPress already comes preloaded with TONS of Javascript libraries/files. You can see a full list of Javascript files over on the WordPress Codex. Here are a few that you might not know are already included in your WordPress installation.

• jQuery
• 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
• ThickBox
• jQuery Hotkeys
• TinyMCE
• and many more

Now that you know that WordPress has tons of Javascript files just waiting to be utilized we can start looking at how to add our own scripts. Below you will see a completed function that will be hooked into the wp_enqueue_scripts WordPress hook. 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’)); In the wp_register_script function we first give our script a name or a handle that we can reference. In this line of code it is ‘name-of-script’. Then we give the location on our website that we have stored that script. The get_stylesheet_directory_uri() tells WordPress to go look up the folder of our active theme directory followed by the folder ‘/js/’ and inside that folder WordPress will find a custom.js file. Finally inside the array() part of the function we list any Javascript libraries that our custom.js file may require to function properly. In this case we are telling WordPress to make sure to load the jQuery library (that is already included in WordPress and we already talked about earlier in this post) before the custom.js file. And that’s it. Now we can register and enqueue all of our Javascript files and even if all of our new files are dependent of jQuery, WordPress will only load a single instance of jQuery and eliminate the problems of colliding javascript files. 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:

• wp_enqueue_scripts
• wp_register_script
• wp_enqueue_script