Enqueueing Javascript & CSS Files

 

Your plugin may require Javascript libraries and/or CSS. These are included using the wp_enqueue_script() and wp_enqueue_style().

But before you go en-queuing things, you should understand how to exercise some restraint. If your plugin simply en-queues a script or style, it will be included on EVERY page, including administrative and regular pages. Often you don’t want that one every page. The more places it appears, the more likely it will cause a conflict with some other script or css from other plugins or from the theme. As a best practice, limit scripts to just those pages you need it. WP does not make this easy, but there are some simple tricks.

Generally, to en-queue something, in your XXX_Plugin.php file, find your addActionsAndFilters() function and add them there. There are some commented-out examples in the file you download. This example shows how to en-queue a script known to WP (jquery) and a style and script that you create for your plugin and place in your plugin’s css/ and js/ sub-directories respectively.

Note: in an earlier version of this code, wp_enqueue_script() and wp_enqueue_style() functions were called directly in addActionsAndFilters(). But recent versions of WP (since 3.6?) give warnings about these calls when WP_DEBUG=true. Recent WP versions require that these functions be called on the wp_enqueue_scripts or admin_enqueue_scripts hooks. Now, we place the calls to those functions in a wrapper function, and in addActionsAndFilters() register the wrapper function to a hook using add_action as shown below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public function addActionsAndFilters() {
    // enqueue scripts and styles for regular pages
    add_action('wp_enqueue_scripts', array(&$this, 'enqueueStylesAndScripts'));
 
    // enqueue scripts and styles for admin pages
    add_action('admin_enqueue_scripts', array(&$this, 'enqueueAdminPageStylesAndScripts'));
}
 
public function enqueueStylesAndScripts() {
    wp_enqueue_script('jquery');
    wp_enqueue_style('my-style', plugins_url('/css/my-style.css', __FILE__));
    wp_enqueue_script('my-script', plugins_url('/js/my-script.js', __FILE__));
}
 
public function enqueueAdminPageStylesAndScripts() {
    wp_enqueue_script('jquery');
    wp_enqueue_style('my-style', plugins_url('/css/my-style.css', __FILE__));
    wp_enqueue_script('my-script', plugins_url('/js/my-script.js', __FILE__));
}

The wp_enqueue_scripts adds these scripts & styles to regular pages while the admin_enqueue_scripts hooks adds them to all admin pages. There are a couple obvious examples of when you don’t want that to happen:

  1. A special administration page that you create that has its own special script or style.
  2. A short code that needs script or style. You only want that added to pages where the short code appears

Regarding (1), The technique is to check the URL being requested to see if it is a page that requires the script or style. If you create your own administration page, when you register it you give it a “slug”. A slug is part of the URL that identifies it. Create conditional code like this:

1
2
3
4
5
6
7
8
public function enqueueAdminPageStylesAndScripts() {
    // Apply scripts & styles to the plugin's admin setting page only
    if (strpos($_SERVER['REQUEST_URI'], $this->getSettingsSlug()) !== false) {
        wp_enqueue_script('jquery');
        wp_enqueue_style('my-style', plugins_url('/css/my-style.css', __FILE__));
        wp_enqueue_script('my-script', plugins_url('/js/my-script.js', __FILE__));
    }
}

See more on the “Adding Administration Pages“.

Regarding (2), there is a discussion of a technique supported by this template code for en-queuing only when the short code appears on the page. See the page on short codes for more information.

 

  One Response to “Enqueueing Javascript & CSS Files”

  1. If I understand right, this WordPress.org Plugin API page is recommending calling wp_enqueue_scripts using add_action and a relevant hook. E.g.
    function load_custom_wp_admin_style() {
    wp_register_style( 'custom_wp_admin_css', get_bloginfo( 'stylesheet_directory' ) . '/admin-style.css', false, '1.0.0' );
    wp_enqueue_style( 'custom_wp_admin_css' );
    }
    add_action( 'admin_enqueue_scripts', 'load_custom_wp_admin_style' );

    There also appears to be an alternative way to load a css style for a specific admin page that does not require $_SERVER[‘REQUEST_URI’].

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>