What are best practices for including jquery plugins

by

Why you shouldn’t hardcode javascript files

There are several reasons why you shouldn’t hardcode links to javascript files:

  • It sidesteps WordPress’ queuing of javascript files which is designed to handle dependencies for you.
  • Plug-ins exist which force scripts to be loaded in the footer (hard-coding would mean they couldn’t do this, and may even break your plug-in).
  • Hardcoding means other plug-ins cannot de-register or replace your script (they should be able to). Nor can then easily use your script while avoiding loading the file twice.
  • By registering a script (wp_register_script()) you are then free to use wp_enqueue_script() in any widgets, shortcodes or templates. Better still, the script is only enqueued if the appropriate tempate, widget or shortcode is used: impossible if its hardcoded.
  • Using wp_register_script()/wp_enqueue_script() allows you or other plug-ins to make use of wp_localize_script() (originally intended for passing localised strings, but more widely used for passing options stored in the database which can then be used in your javascript files.
  • There are problably more reasons…

Where to store the javascript files?

There’s no set location to store javascript files (in your plug-in/theme). I tend to put them in a folder name js or assets/js. Something that makes sense.

How to load javascript files

First check that the jQuery plug-in (or any javascript library for that matter) isn’t already included in WordPress itself. (There’s a list here: http://codex.wordpress.org/Function_Reference/wp_register_script#Handles_and_Their_Script_Paths_Registered_by_WordPress). If it’s there, use that.

Never use your own copy of a javascript library/plug-in which is included in core. Doing so will probably break your and others’ plug-ins.

It usually makes sense to register and enqueue your script separately:

add_action( 'init', 'wpse125424_register_scripts' );
function wpse125424_register_scripts(){

    wp_register_script( 
        'my-script-handle', //unique handle for our script
        plugins_url( 'js/my-script.js', __FILE__ ), //url to script
        array( 'jquery' ), //list any dependencies
        '1.0' //version, for cache busting
    );
}

and then call wp_enqueue_script('my-script-handle') whenever you require the javascript file to be loaded (e.g. in a function responsible for a widget or shortcode).

The advantage of this is clear: your scripts are registered in one, easily maintained place, and divorced form the the business of queuing the script which can take place ‘on the fly’ and possibly subject to some contorted logic.