How To Include Javascript and CSS Stylesheets in WordPress


PHP is one of the easiest programming languages to learn. It powers a number of highly-trafficked websites such as Facebook, Wikipedia as well as popular content management systems like WordPress and Drupal.

With little knowledge of PHP, anyone can learn WordPress and become a plugin developer albeit majority of them do not adhere to standard and best practices. Little wonder there are lots of poorly written and resource-intensive plugins in the plugin directory.

I’ve seen a number of plugins that directly include JavaScript and CSS stylesheets like so:


echo '<link rel="stylesheet" href="http://url-to-plugin-css-folder/style.css" type="text/css" />';

echo '<script type="text/javascript" src="http://url-to-plugin-js-folder/flip.js></script>';

Problems with this Approach

There are a number of problems with this approach to the code.

  • Inability to control where to include the components thus, stylesheet and JavaScript get included in all pages of the site. For instance, the CSS that will style or design the admin page of a plugin is added to WordPress that way; it means the CSS file will also be present in all pages of the site as a result; the browser will always download/fetch the file even when it isn’t needed.
  • There exist a standard or recommended way of including JavaScript and CSS components in WordPress. Doing it your own way is considered a bad practice.
  • Assuming every plugin that depend on jQuery include their own instance to WordPress and a number of such plugins are installed in a WP site, the consequence of this is existence of multiple instances of the jQuery. This is practice is redundant because, an instance of jQuery would have serve the plugins well.

Doing Things the Right Way

WordPress “ships” with a number of functions for including (enqueuing) JavaScript and CSS the right way. This is how it is done.

Enqueuing JavaScript

The following functions are available for enqueuing JavaScript in WordPress:

  • wp_enqueue_script() – Links a script file to the generated page at the right time according to the script dependencies (information on dependency later).
  • wp_register_script() – Registers a script in WordPress for later use.

The wp_enqueue_script() function require the following parameters.


 <?php wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer ); ?> 

Where:


$handle: What you’ll use to refer to the script wherever you might need to enqueue it.

$src: The URL of the script to be loaded i.e. the path to the source file within your plugin.


$deps: This is an array that contains the handle of any scripts that the script depends on to function. This parameter is optional. Not specifying this parameter means the script has no dependency.

$ver: The version of your script concatenated to the end of the script URL as a query string.

If set to true, the version number will not be appended to the script URL. If you don’t use this parameter, the WordPress version will be used by default.

$in_footer: Normally, scripts are placed in header of WordPress. If this parameter is true, the script will placed before the closing tag.

Here is a basic example for loading a script:


function plugin_javascript() {
	// enqueue the script
	wp_enqueue_script( 'base_js', plugin_dir_url( __FILE__ ) . 'base.js' );
}

add_action( 'wp_enqueue_scripts', 'plugin_javascript' );

Assuming the script depend on jQuery and jquery-ui-datepicker libraries; pass an array of the dependency as the fourth argument to the function.


function plugin_javascript() {
	// enqueue the script
	wp_enqueue_script( 'base_js', plugin_dir_url( __FILE__ ) . 'base.js', array('jquery', 'jquery-ui-datepicker ') );
}

add_action( 'wp_enqueue_scripts', 'plugin_javascript' );

To append a version number to the script URL e.g. 1.0, see the code below.


function plugin_javascript() {
	// enqueue the script
	wp_enqueue_script( 'base_js', plugin_dir_url( __FILE__ ) . 'base.js', array('jquery'), '1.0' );
}

add_action( 'wp_enqueue_scripts', 'plugin_javascript' );

If you want to place the script at footer of WordPress, set the fourth parameter to true.


function plugin_javascript() {
	// enqueue the script
	wp_enqueue_script( 'base_js', plugin_dir_url( __FILE__ ) . 'base.js', array('jquery'), '1.0', true );
}

add_action( 'wp_enqueue_scripts', 'plugin_javascript' );

Note: wp_enqueue_script and wp_register_script are similar in that they have the same function parameters. The only difference is while the former load a script immediately, the latter loads the script for reuse later.

WordPress includes many popular scripts commonly used by web developers besides the ones internally used by WordPress itself.

Instead of including your own version of the registered libraries, simply enqueue any of them and WordPress will remove any redundancy and ensure only an instance of the script is loaded.

For example, if your plugin requires the Jcrop library, do not include your own version of script; instead, enqueue the registered one.


function jcrop_lib() {
	wp_enqueue_script( 'jcrop');
}

add_action( 'wp_enqueue_scripts', 'jcrop_lib' );

Note: When you enqueue a registered script (jcrop) that depend on another script (jQuery), WordPress automatically handles the dependency troubles.

Enqueuing CSS Stylesheet

wp_enqueue_style() and wp_register_style() is to CSS what wp_enqueue_script() and wp_register_script() is to JavaScript.

Function Synopsis


<?php wp_enqueue_style( $handle, $src, $deps, $ver, $media ); ?> 

<?php wp_register_style( $handle, $src, $deps, $ver, $media ); ?> 

Where:

$handle Stylesheet handle name.

$src – URL to the stylesheet.

$deps – Array stylesheet handles that the stylesheet depends on.

$ver – Stylesheet version number.

$media – The media for which this stylesheet has been defined. Examples: ‘all’, ‘screen’, ‘handheld’, ‘print’.

Here’s how to safely add/enqueue a CSS file to WordPress.


function plugin_css() {
	wp_enqueue_style( 'css-handle', plugin_dir_url( __FILE__ ) . 'style.css' );
}

add_action( 'wp_enqueue_scripts', 'plugin_css' );

Here’s how to register a CSS style file for later via wp_register_style().


add_action( 'wp_enqueue_scripts', 'register_plugin_styles' );

function plugin_styles() {
	// Register the css for later use
	wp_register_style( 'my-plugin', plugins_url( 'my-plugin/css/plugin.css' ) );
	
	// use the css now
	wp_enqueue_style( 'my-plugin' );
}

Stop Enqueuing Everywhere

The code examples we’ve seen so far uses the wp_enqueue_scripts action to enqueuing items meant to be loaded on the front end.

To load a set of CSS and/or JavaScript documents to all admin pages, use the admin_enqueue_scripts action as follows:


function load_custom_wp_admin_style() {
	wp_register_style( 'custom_wp_admin_css', plugins_url( 'my-plugin/admin-style.css' ), false, '1.0' );
	wp_enqueue_style( 'custom_wp_admin_css' );
}
add_action( 'admin_enqueue_scripts', 'load_custom_wp_admin_style' );

To enqueue items that are meant to appear on the login page, use login_enqueue_scripts.


function login_style_script() {
	wp_register_style( 'login_css', plugins_url( 'my-plugin/login.css' ), false, '1.0' );
	wp_enqueue_style( 'login_css' );

	wp_enqueue_script( 'scriptaculous' );
}
add_action( 'login_enqueue_scripts', 'load_custom_wp_admin_style' );

Wrap Up

If a standard is available for doing anything, it is recommended you adhere to them because they were created with a lot of thought by people who probably understand it better than you might.

I hope this tutorial will help you better understand how to Enqueue Scripts in WordPress properly.

If there is anything you don’t understand or you have a question, feel free to let us know in the comments.

One Response

  1. Amy S Apr 14, 11:24 pm