Add custom javascript files to the wordpress site

text-x-javascript-icon

Use wp_enqueue_script() in an init hook, or if in the admin only then in an admin_menu or admin_init hook. It might look something like this (which assumes you are calling from your theme’s functions.php file; note how I reference the stylesheet directory):

<?php
add_action('init', 'mysite_init');
function mysite_init() {
 $ss_url = get_bloginfo('stylesheet_directory')
 wp_enqueue_script('mysite-scripts',"$ss_url/js/mysite-scripts.js");
}


That’s the basics.

Pre-defined and Multiple Dependent Scripts

But let’s say you want to include both jQuery and jQuery UI Sortable from the list of default scripts included with WordPress and you want your script to depend on them? Easy, just include the first two scripts using the pre-defined handles defined in WordPress and for your script provide a 3rd parameter to wp_enqueue_script() which is an array of the script handles used by each script, like so:

<?php
add_action('init', 'mysite_init');
function mysite_init() {
 $ss_url = get_bloginfo('stylesheet_directory')
 wp_enqueue_script('jquery');
 wp_enqueue_script('jquery-ui-sortable');
 wp_enqueue_script('mysite-scripts',"$ss_url/js/mysite-scripts.js",array('jquery','jquery-ui-sortable'));
}

Scripts in a Plugin

What if you want to do it in a plugin instead? Use the plugins_url() function to specify the URL of your Javascript file:

<?php
define('MY_PLUGIN_VERSION','2.0.1');
add_action('init','my_plugin_init');
function my_plugin_init() {
 wp_enqueue_script('jquery');
 wp_enqueue_script('jquery-ui-sortable');
 wp_enqueue_script('my-script',plugins_url('/js/my-script.js',__FILE__),array('jquery','jquery-ui-sortable'),MY_PLUGIN_VERSION);
}

Versioning your Scripts

Also note that above we gave our plugin a version number and passed it as a 4th parameter towp_enqueue_script(). The benefits of using script version number is that if multiple plugins or the theme enqueue the same script by version number more than once WordPress will only send one copy to the browser.

Load Scripts only on pages where needed

The 1st rule of Web Performance says to Minimize HTTP Requests so whenever possible you should limit the scripts to load only where needed. For example if you only need your script in the admin limit it to admin pages using the 'admin_init' hook instead:

<?php
define('MY_PLUGIN_VERSION','2.0.1');
add_action('admin_init','my_plugin_admin_init');
function my_plugin_admin_init() {
 wp_enqueue_script('jquery');
 wp_enqueue_script('jquery-ui-sortable');
 wp_enqueue_script('my-script',plugins_url('/js/my-script.js',__FILE__),array('jquery','jquery-ui-sortable'),MY_PLUGIN_VERSION);
}

Load Your Scripts in the Footer

If your scripts is one of those that need to be loaded into the footer there is a 5th parameter ofwp_enqueue_script() that tells WordPress to delay it and place it in the footer (assuming your theme did not misbehaved and that it indeed calls the wp_footer hook like all good WordPress themes should):

<?php
define('MY_PLUGIN_VERSION','2.0.1');
add_action('admin_init','my_plugin_admin_init');
function my_plugin_admin_init() {
 wp_enqueue_script('jquery');
 wp_enqueue_script('jquery-ui-sortable');
 wp_enqueue_script('my-script',plugins_url('/js/my-script.js',__FILE__),array('jquery','jquery-ui-sortable'),MY_PLUGIN_VERSION,true);
}

Finer Grained Control

If you need finer grained control than that Ozh has a great article entitled How To: Load Javascript With Your WordPress Plugin that details more.

Loading Scripts from Google’s AJAX CDN

Assuming you are not familiar Google has a lot of the standard open-source libraries like jQuery hosted so that sites can load the files from Google and increase the likelihood that jQuery will already be in a visitor’s browser’s cache because so many other sites are loading jQuery from exactly the same location! To load jQuery from Google’s AJAX CDN you’d need to usewp_deregister_script() and then wp_register_script() like so (note I’m using the latest version as of this writing even though Google will continue to host older versions):

<?php define('MY_PLUGIN_VERSION','2.0.1'); add_action('admin_init','my_plugin_admin_init'); function my_plugin_admin_init() {   wp_deregister_script('jquery');   wp_register_script( 'jquery','http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js');   wp_enqueue_script('jquery');   wp_enqueue_script('jquery-ui-sortable');   wp_enqueue_script('my-script',plugins_url('/js/my-script.js',__FILE__),array('jquery','jquery-ui-sortable'),MY_PLUGIN_VERSION,true); }

Disabling Scripts to Gain Control

Justin Tadlock has a nice article entitled How to disable scripts and styles in case you want to:

  1. Combine multiple files into single files (mileage may vary with JavaScript here).
  2. Load the files only on the pages we’re using the script or style.
  3. Stop having to use !important in our style.css file to make simple CSS adjustments.
Passing Values from PHP to JS with wp_localize_script()

On his blog Vladimir Prelovac has a great article entitled Best practice for adding JavaScript code to WordPress plugins where he discusses using wp_localize_script() to allow you to set the value of variables in your server-side PHP to be later used in your client-side Javascript.

Really Fine Grained Control with wp_print_scripts()

And finally if you need really fine-grained control you can look into wp_print_scripts() as discussed on Beer Planet in a post entitled How To Include CSS and JavaScript Conditionally And Only When Needed By The Posts.

Epiloque

That’s about it for Best Practices of including Javascript files with WordPress. If I missed something (which I probably have) be sure to let me know in the comments so I can add an update for future travelers.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s