2

I hesitated to ask this question, because it may be too fundamental. However, after digging in to the codex and other topics I became convinced that maybe it is not so fundamental because I could not find an answer to my question.

My question is what purpose does the handle serve in functions like wp_enqueue_script() and wp_enqueue_style()? The codex explains that it is the name of the script or stylesheet, though clearly this does not need to be the name of the file that holds the script or style. I assume that it needs to be unique and I assume that it can be accessed via

global $wp_scripts;

The fact that the handle is explicitly defined suggests that it must have a clear purpose or be re-usable somehow. Otherwise, we would only need to load the script or stylesheet and it would work without the need for a handle. I would appreciate any insights into this.

1
  • 1
    with the handle you can unenque, deregister, reregister, and refer in your ensued dependencies. Commented Feb 5, 2018 at 17:58

3 Answers 3

3

Below is an example of the jquery handle being used in various ways:

// add my js, written in jQuery
// so it requires `jquery.min.js` to be output first
// & say I do this in a early hook like `init`
wp_enqueue_script( 'my-js', 'js.js', array('jquery'));

// later in theme:

// remove Wordpress's default jquery,
// change jquery to a specified version, and put in footer
// & say I do this in a later hook like `wp_loaded`
wp_deregister_script( 'jquery' );
wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js', false, '1.8.1', true );
wp_enqueue_script( 'jquery' );
  • Even though I've enqued my-js first, I'm able to change and modify jquery

  • I'm able to easily change which jquery version and source I'm using, with ease

  • I have a simple straightforward, pseudocode method to remove a script that I don't want

  • I changed jquery's script, in a big way, but other plugins that rely on jquery will still get jQuery (though the versions might be off, but not important right now)

  • My my-js was done early and is default to be in wp_head. later, I changed jquery to be placed to the footer (import for speed preformace (re: Google PageSpeed). Since my-js depends on jquery, it gets moved down to the footer as well

When you're dealing with multiple plugin and theme authors, who want to change and modify things, like jQuery, without knowing the dynamic URLs or what other theme/plugin has touched the jquery script -- doing anything like this without an handle would be an absolute nightmare.

3
  • 4
    Could you please edit your answer and also explain why it's necessary for those unable to run the code at that moment or for those who may not find it as self-explanatory as you do.
    – Howdy_McGee
    Commented Feb 5, 2018 at 18:04
  • Thanks David for your answer and for showing the way that you are able to change your jQuery version. Very neat! From your response, I can now see that using the 'jquery' handle allows the programmer to reference the script to deregister and then can register a different script (version) that presumably will work with other dependent scripts. Like my-js in your example which depends on jQuery. This all makes good sense. If there are any other benefits that anyone knows of, I would appreciate to hear about these too.
    – WPDavid
    Commented Feb 5, 2018 at 23:27
  • 1
    @WPDavid handle can also be referenced in filters eg. script_loader_tag
    – majick
    Commented Feb 6, 2018 at 0:16
1

One of the key reasons for creating a handle for your styles and scripts, using wp_enqueue_style and wp_enqueue_script, is that this provides a unique name for the style or script that can be used to reference it with other functions.

As an example consider using a style in a plugin that should only be initiated on certain pages:

First register the style with a unique handle (my-report-style in this case)

function register_my_report_styles() {
   wp_register_style('my-report-style', plugins_url('css/my-style.css', __FILE__));
}
add_action( 'init', 'register_my_report_styles' );

Having defined the handle, we can reference it directly in other functions. In this case, we want the style to load only on a particular page (e.g. our annual_report page) so we can enqueue the style only for this page using:

function enqueue_report_styles() {
   if ( is_page(array('annual_report')) ) {
      wp_enqueue_style( 'my-report-style' );
   }
}
add_action( 'wp_enqueue_scripts', 'enqueue_report_styles' );

Continuing the example, suppose you now want to add an inline style to the already enqueued stylesheet (e.g. transform all h1 tags on this page to uppercase). You can do this as follows:

function update_report_styles() {
   $css = 'h1 {text-transform: uppercase;}';
   wp_add_inline_style('my-report-style', $css);
}
add_action('wp_enqueue_scripts', 'my_theme_inline_css');

Notice that again, we referred to the already enqueued stylesheet only by the handle that we gave to the stylesheet when we registered it.

0

I was also confused about the function of the handle in wp_enqueue_style() and the previous answer was overcomplex. As far as I understand it, the handle is a name or an identifier you give to the script to be able to recall it or to refer to it.

In the description of wp_enqueue_style() we can read: "Registers the script if $src provided (does NOT overwrite), and enqueues it."

But we could also have registered it before with wp_register_script(), which "registers a script to be enqueued later using the wp_enqueue_script() function.". Also for this reason in wp_enqueue_style() the second argumet 'src' is optional.

If we have a style.css file in our theme folder we must register it through wp_register_script() or wp_enqueue_style() and give it a (unique) name/identifier, to be able to use and access it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.