162 CSS Inclusion with Plugins

Part of the “How to Write a WordPress Plugin” Series

Objectives

In this lesson we will discuss and demonstrate the use of Cascading Style Sheets (CSS) with your WordPress plugin. The use of these functions will also avoid problems that will arise when your themes or plugins both use the same Cascading Style Sheets. This information is equally appropriate to theme design.

All WordPress Themes and Plugins are reliant upon Cascading Style Sheets (CSS) these days. To make your plugins and themes easier to maintain, I recommend always placing the files associated with these items in separate folders.

As always there are many ways to accomplish a task and in this lesson we will show just a few methods specific to WordPress that will allow you to load scripts and avoid conflicts with other themes and plugins.

Contents

 

—– Insert The Video —–

 

The Wp_Register_Style and Wp_Enqueue_Style Functions

The functions, wp_register_style and wp_enqueue_style, are used to add CSS to the HTML head of a page.

Registering Your Styles – Wp_Register_Style

The wp_register_style can be thought of as a safe way of registering CSS in WordPress (without adding it to the generated page) for later use with wp_enqueue_style.. Used by itself, it has no effect on your HTML whatsoever.

Usage

wp_register_style(
   $handle, /* (string) (required) Name of the stylesheet, which should be unique */
   $src, /* (string|boolean) (optional) URL to the stylesheet. */
   $deps, /* (array) (optional) Array of handles of any stylesheet that this stylesheet depends on. /
   $ver, /* (string) (optional) String specifying the stylesheet version number. /
   $media /* (boolean) (optional) String specifying the media for which this stylesheet has been defined. */
);

Notes:

• Valid CSS-media-types, $media, are: All, Braille, Embossed, Handheld, Print, Projection, Screen, Speech, TTY, TV. Note: media type names are case-insensitive.
• This $ver parameter is used to ensure that the correct version is sent to the client regardless of caching, and so should be included if a version number is available and makes sense for the stylesheet.
• You should never hardcode URLs to local scripts, use Function Reference/plugins_url (for Plugins) and Function Reference/get_template_directory_uri (for Themes) to get a proper URL.

 

Enqueueing Your Scripts – Wp_Enqueue_Style

The wp_enqueue_style is a safe way of adding CSS to a WordPress generated page. The wp_enqueue_style function outputs your CSS to the HTML head of a page. If the stylesheet was first registered with wp_register_style it can now be added using its handle.

The wp_enqueue_style function does the same thing as wp_register_style and more. If $src is provided, the enqueue function automatically registers the script for you, thus making the wp_register_style function somewhat unnecessary. However, the wp_register_style does allow you to register your scripts manually so you can load all of your stylesheets using one wp_enqueue_style call.

Usage

wp_enqueue_style(
   $handle, /* (string) (required) Name of the stylesheet, which should be unique */
   $src, /* (string | boolean) (optional) URL to the stylesheet. */
   $deps, /* (array) (optional) Array of handles of any stylesheet that this stylesheet depends on. /
   $ver, /* (string) (optional) String specifying the stylesheet version number. /
   $media /* (boolean) (optional) String specifying the media for which this stylesheet has been defined. */
);

Load Stylesheet Using a Hook

/*
 * Using a Hook 
 * Example from WordPress - See codex
 */
 
/* Register with hook 'wp_enqueue_scripts' which can be used for front end CSS and JavaScript */
add_action ('wp_enqueue_scripts', 'add_my_stylesheet');
 
/* Enqueue style-file, if it exists. */

function add_my_stylesheet() {
   /* Respects SSL, Style.css is relative to the current file */
   $myStyleUrl = plugins_url ('style.css', __FILE__);
   $myStyleFile = WP_PLUGIN_DIR . '/myPlugin/style.css';
   if ( file_exists ($myStyleFile) ) {
      wp_register_style ('myStyleSheets', $myStyleUrl);
      wp_enqueue_style ( 'myStyleSheets');
   }
}

 

Load Stylesheet Only On a Plugin’s Options Page

/*
 * Load stylesheet only on a plugin's options page 
 * Example from WordPress - See codex
 */
add_action ( 'admin_init', 'my_plugin_admin_init' );
add_action ( 'admin_menu', 'my_plugin_admin_menu' );

function my_plugin_admin_init () {
   /* Register our stylesheet. */
   wp_register_style ( 'myPluginStylesheet', plugins_url('stylesheet.css', __FILE__) );
}

function my_plugin_admin_menu () {
/* Register our plugin page */
   $page = add_submenu_page ( 'edit.php', 
      __( 'My Plugin', 'myPlugin' ),
      __( 'My Plugin', 'myPlugin' ),
      'administrator',
      __FILE__,
      'my_plugin_manage_menu' );

   /* Using registered $page handle to hook stylesheet loading */
   add_action( 'admin_print_styles-' . $page, 'my_plugin_admin_styles' );
}

function my_plugin_admin_styles () {
   /* It will be called only on your plugin admin page, enqueue our stylesheet here */
   wp_enqueue_style ( 'myPluginStylesheet' );
}

function my_plugin_manage_menu () {
   /* Output admin page */
}

See Also

wp_deregister_style(), wp_dequeue_style()

Conclusion – Summary

Using this way to add CSS to your code is recommended for all plugins. Not only it is elegant and efficient but it is usually faster than manually printing your scripts and parameters.

Well, that’s all for this tutorial on How to Write a WordPress Plugin, see you in the next lesson.

Links Used in this Lesson

http://codex.WordPress.org/Function_Reference/wp_register_style

http://codex.WordPress.org/Function_Reference/wp_deregister_style

http://codex.WordPress.org/Function_Reference/wp_enqueue_style

http://codex.WordPress.org/Function_Reference/wp_dequeue_style