Archives for May 2007

This post was written as part of the How to Write a WordPress Plugin series.

A lot of plugins nowadays are more reliant on JavaScript and Cascading Style Sheets. It is important to separate your JavaScript and CSS into separate files so that the plugin is easier to maintain. This portion of the series will cover how to load JavaScript and CSS files for your plugin.

Add your JavaScript

Your plugin might need to load the Prototype library or perhaps a custom script. This section will show you a few WordPress functions that will allow you to load scripts and avoid script conflicts.

The wp_register_script function

The wp_register_script function allows you to register your script for calling and can allow you to set pre-requisites. For example, if your script requires Prototype to have been loaded, you can specify this.

Here are the parameters for wp_register_script: wp_register_script( $handle, $src, $deps = array(), $ver = false )

• The handle is a unique name that you will use to reference your script later. This variable is required.
• The src is the absolute source to your JavaScript file. This variable is required.
• The deps variable is an array of dependencies. For example, if your script requires prototype, you would list it here. This variable is optional.
• The ver variable is a string version of the script. This variable is optional.

Say for example you had a script that was located at: http://yourdomain.com/wp-content/plugins/your-plugin-directory/js/script.js

Let’s make a few assumptions:

• You want to name the handle ‘my_script_handle’.
• Your script depends on the Prototype library.
• Your version is 1.0

You would likely call the function in your plugin code initialization or after a wp_head action:

[php]
wp_register_script(‘my_script_handle’, ‘http://yourdomain.com/wp-content/plugins/your-plugin-directory/js/script.js’, array(‘prototype’), ‘1.0’);
[/php]

The wp_enqueue_script Function

The wp_enqueue_script function does the same thing as wp_register_script except that the src variable is optional. If an src is provided, the enqueue function automatically registers the script for you, thus making the wp_register_script function somewhat unnecessary. However, the wp_register_script allows you to register your scripts manually so you can load all of your JavaScripts using one wp_enqueue_script function.

If we were to call the same custom script as before, it would be called like this:

[php]
wp_enqueue_script(‘my_script_handle’, ‘http://yourdomain.com/wp-content/plugins/your-plugin-directory/js/script.js’, array(‘prototype’), ‘1.0’);
[/php]

A JavaScript Example

For the Devlounge Plugin Series plugin, we’re going to add in a dummy JavaScript file that will be used in a later post. The purpose of this file is to demonstrate how to use the wp_enqueue_script function.

• This file is located at the following location: http://yourdomain.com/wp-content/plugins/devlounge-plugin-series/js/devlounge-plugin-series.js
• The file is dependent upon prototype.
• The version is 0.1

You might recall that in a previous post in this series, we added an action for wp_head. The function that was run as a result of that action was called addHeaderCode. Let’s modify this function to add in our new JavaScript:

[php]
function addHeaderCode() {
if (function_exists(‘wp_enqueue_script’)) {
wp_enqueue_script(‘devlounge_plugin_series’, get_bloginfo(‘wpurl’) . ‘/wp-content/plugins/devlounge-plugin-series/js/devlounge-plugin-series.js’, array(‘prototype’), ‘0.1’);
}
$devOptions = $this->getAdminOptions();
if ($devOptions[‘show_header’] == “false”) { return; }
?>

When you go to a post and view-source, the devlounge-plugin-series.js will have loaded as well as the Prototype library, which is conveniently included along with WordPress (versions 2.1.x and up I believe).

Loading in the Cascading Style Sheets

I’ve added a new style sheet to my styles directory. Here are my assumptions:

• This file is located at the following location: http://yourdomain.com/wp-content/plugins/devlounge-plugin-series/css/devlounge-plugin-series.css
• I specified an ID called #devlounge-link in the CSS file.
• You have added in the following code at the end of a post: <a href="#" id="devlounge-link">Get the Number of Blog Comments</a>

In the style sheet file, I have added in the following ID:

[css]
#devlounge-link {
background-color:#006;
color: #FFF;
}
[/css]

Adding in the style sheet for the plugin is as simple as adding a line to the addHeaderCode function:

[php]
function addHeaderCode() {
echo ‘‘ . “\n”;
if (function_exists(‘wp_enqueue_script’)) {
wp_enqueue_script(‘devlounge_plugin_series’, get_bloginfo(‘wpurl’) . ‘/wp-content/plugins/devlounge-plugin-series/js/devlounge-plugin-series.js’, array(‘prototype’), ‘0.1’);
}
$devOptions = $this->getAdminOptions();
if ($devOptions[‘show_header’] == “false”) { return; }
?>

Conclusion

Within this post you learned how to allow your plugin to have external JavaScript and CSS files. As always, you can download the current version of the code and try it out yourself: Using JavaScript and CSS with your WordPress Plugin

Download the Code Used In This Post

For further reading, please check out these links:

• Prototype library
• get_bloginfo Template Tag
• Avoid Repetitive JavaScript Calls