Enhancing Plugins with CSS and JavaScript

As you have discovered by now, there are many ways to add functionality to a plugin. In this section, we look at two methods, CSS styling and JavaScript. You may never develop a plugin that uses either, but it's still useful to understand how these can be included. Chances are you may need this at some point, so it's a good reference for any budding plugin developer to have.

Calling stylesheets within a plugin

Controlling how your plugin's output looks onscreen (whether in the WordPress Dashboard or on the front end of the Web site or blog) is best controlled through a stylesheet. If you've been around Web design and HTML, you're probably familiar with CSS (Cascading Style Sheets). Nearly every styling aspect for a Web site is controlled by a stylesheet, and WordPress is no exception. If you want to read the authoritative guide to stylesheets, visit the W3C.org Web site at http://www.w3.org/Style/CSS. (For more on CSS, see Book VI.)

You can use a single stylesheet to control how your Plugin Options page looks in the Dashboard, how your plugin widget looks in the Dashboard, or how your plugin displays information on the front-end Web site.

The best practice for adding stylesheets within your plugin is to create a /styles directory, for example, /my-plugin/styles. Place your stylesheets for the back end and front end inside this directory, as shown in Figure 7-2.

Figure 7-2: The file structure for a plugin showing stylesheets.

To call a stylesheet from your plugin, you should use the built-in WordPress wp_enqueue_style function because it creates a queuing system in WordPress for loading stylesheets only when they are needed, instead of on every page. Additionally, it has support for dependencies so you can specify whether your stylesheet depends on another that should be called first. This queuing system is used for scripts, too. Moreover, the wp_enqueue_scripts function does the same for scripts, which we discuss a little later in this section.

Let's look at some practical examples using wp_enqueue_style.

Say you're creating a gallery plugin to display images on your Web site. You want your gallery to look nice, so you want to create a stylesheet that controls how the images display. Here's how to call that stylesheet in your plugin using a simple function and action hook (these lines of code get added to your primary plugin PHP file at the end, just before the closing ?> tag):

1. Create a function in your primary plugin PHP file to register your stylesheet and invoke wp_enqueue_style.

   function add_my_plugin_stylesheet() {
      wp_register_style('mypluginstylesheet', '/wp-content/plugins/
        my-plugin/styles/site-style.css'),
      wp_enqueue_style('mypluginstylesheet'),
   }

2. Use the wp_print_styles action hook and call your function.

   add_action( 'wp_print_styles', 'add_my_plugin_stylesheet' );

Here's a breakdown of the hooks in the function:

• The wp_register_style function registers your stylesheet for later use by wp_enqueue_style.

  wp_register_style( $handle, $src, $deps, $ver, $media )

  The function has a number of parameters; the first is $handle, which is the name of your stylesheet.

  $handle must be unique. You cannot have more than one stylesheet with the same name in the same directory.

  The second parameter is $src, the path to your stylesheet from the root of WordPress. In this case, it's the full path to the file within the plugin's styles directory.

  The remaining parameters are optional. To find out more about them, read the WordPress documentation on this function at http://codex.wordpress.org/Function_Reference/wp_register_style.

• The wp_enqueue_style function queues the stylesheet.

  wp_enqueue_style( $handle, $src, $deps, $ver, $media )

  The $handle parameter is the name of your stylesheet as registered with wp_register_style. The $src parameter is the path, but you don't need this parameter because you registered the stylesheet path already. The remaining parameters are optional and explained in the WordPress documentation on this function at http://codex.wordpress.org/Function_Reference/wp_enqueue_style.

• The action hook that calls the function uses wp_print_styles to output the stylesheet to the browser.

Figure 7-3 shows the plugin stylesheet being called in the <HEAD> section of the site source code.

Figure 7-3: Source code of a Web site showing the plugin stylesheet being called.

Another example uses a stylesheet for the plugin's admin interface, which controls how your plugin option page within the Dashboard will appear. These lines of code also get added to your plugin's primary PHP file (just prior to the closing ?> tag):

add_action('admin_init', 'myplugin_admin_init'),

function myplugin_admin_init() {
   wp_register_style('mypluginadminstylesheet', '/wp-content/plugins/my-plugin/
     admin-styles.css'),
    add_action('admin_print_styles' 'myplugin_admin_style'),
    function myplugin_admin_style() {
      wp_enqueue_style('mypluginadminstylesheet'),
   }
}

This example uses some hooks that are specific to the WordPress Dashboard:

• The action hook calls admin_init. This makes sure that the function
  is called when the Dashboard is accessed. The callback function is myplugin_admin_init.
• The function registers the stylesheet, using wp_register_style.
• An action hook calls the myplugin_admin_style function. The admin_print_styles hook is used because it's specific to the WordPress Dashboard display.
• Our function then queues the stylesheet, using wp_enqueue_style.

Figure 7-4 shows the plugin stylesheet being called in the source code of the Plugin Options page in the Dashboard.

Figure 7-4: The source code of the Plugin Options page in the Dashboard showing the plugin stylesheet being called.

Calling JavaScript within a plugin

After using the wp_register_style and wp_enqueue_style functions to call stylesheets within a plugin, you can see how similar functions can call JavaScript, which has many uses within a plugin.

JavaScript can control functionality within a form or display something with an effect. WordPress comes with some JavaScript in the core that you can call in your plugin or you can write your own. Like stylesheets, it's best to store JavaScript in a separate subdirectory within your plugin; for example, /my-plugin/javascript.

Instead of using wp_register_style and wp_enqueue_style to register and queue JavaScript, you must use wp_register_script and wp_enqueue_script. They work in much the same way and have much the same parameters. Here's an example to be added to your plugins primary PHP file, near the end before the closing ?> tag:

if ( !is_admin() ) {
   wp_register_script('custom_script','/wp-content/plugins/my-plugin/javascript/
    custom-script.js',);
   wp_enqueue_script('custom_script'),
}

Immediately, you notice that the wp_enqueue_script function loads scripts in the front end of your Web site and in the Dashboard. Because this can cause conflicts with other scripts used by WordPress in the Dashboard display, the “if is not” (!is_admin) instruction tells the plugin to load JavaScript only if it's not being loaded in the Dashboard. This code loads custom-script.js only on the front end of the Web site (that is, what your site visitors see). You could add a more specific conditional if instruction to load JavaScript only on a certain page.

If you want to load the JavaScript in wp-admin, the action hook admin_init loads your callback function when wp-admin is accessed and the admin_print_script function outputs the script to the browser, just like the stylesheet example.