Friday, June 22, 2012

Using JavaScript and CSS with your WordPress Plugin

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() {
            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; }
            ?>

            }


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: Get the Number of Blog Comments
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 '' . "\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; }
            ?>

            
        }
 
On line 2, I simply echo out a reference to the new style sheet.
Number of Comments Link

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

0 comments:

Post a Comment

I am a student of MS(CS), and also a computer software engineer and web developer.