Using JavaScript and CSS with your WordPress Plugin
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:
-
wp_register_script('my_script_handle', 'http://yourdomain.com/wp-content/plugins/your-plugin-directory/js/script.js', array('prototype'), '1.0');
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:
-
wp_enqueue_script('my_script_handle', 'http://yourdomain.com/wp-content/plugins/your-plugin-directory/js/script.js', array('prototype'), '1.0');
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:
-
function addHeaderCode() {
-
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; }
-
?>
-
<!-- Devlounge Was Here -->
-
<?
-
-
}
The above code does the following:
- The wp_enqueue_script function is checked for existence.
- The wp_enqueue_script is called with the src, dependencies, and version.
- We use the get_bloginfo('wpurl') to get the location of the WordPress installation and hard-code the rest.
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:
-
#devlounge-link {
-
background-color:#006;
-
color: #FFF;
-
}
Adding in the style sheet for the plugin is as simple as adding a line to the addHeaderCode function:
-
function addHeaderCode() {
-
echo '<link type="text/css" rel="stylesheet" href="' . get_bloginfo('wpurl') . '/wp-content/plugins/devlounge-plugin-series/css/devlounge-plugin-series.css" />' . "\n";
-
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; }
-
?>
-
<!-- Devlounge Was Here -->
-
<?
-
-
}
On line 2, I simply echo out a reference to the new style sheet.
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:
"));
Want an avatar? Get a gravatar! • You can link to this comment
If we need the javascript in the admin panel? What code do we need?
Want an avatar? Get a gravatar! • You can link to this comment
So am I understanding correctly? wp_enque_script will do the same thing as if we manually put script type=”text/javascript” src=”etc.js” so when we use its function in the page it will work?
Want an avatar? Get a gravatar! • You can link to this comment
wp_enqueue_script is the correct way to add any JavaScript to a plugin or theme. JavaScript files ideally should not be put in manually, but wp_enqueue_script only works for WP 2.1 and up I believe.
The actions that should be called for admin scripts are: admin_print_scripts
The actions that should be called for non-admin scripts are: wp_print_scripts
Want an avatar? Get a gravatar! • You can link to this comment
Thanks for your reply! In that case, should we see the link to the js in the head of the page or just trust that the js is being loaded?
There’s something else in my plugin causing a fatal error, so I’m not really sure which parts are working and which aren’t. The js call doesn’t seem to be causing errors when I remove the rest of my plugin it doesn’t have errors, but I can’t find evidence of it working either.
Want an avatar? Get a gravatar! • You can link to this comment
Oh! wonderful article.Please visit a too minutes and enjoyed.
Want an avatar? Get a gravatar! • You can link to this comment
Kristarella,
You should still see the js in the header when you view the html output.
Here’s an example of how my plugin does it:
add_action(’init’, ‘wp_invoice_init’);
function wp_invoice_init() {
wp_enqueue_script( ‘jquery.calculation’,get_bloginfo(’wpurl’). ‘/wp-content/plugins/wp-invoice/js/jquery.calculation.min.js’, array(’jquery’));
wp_enqueue_script( ‘jquery.tablesorter’,get_bloginfo(’wpurl’). ‘/wp-content/plugins/wp-invoice/js/jquery.tablesorter.min.js’, array(’jquery’));
}