Enqueuing Scripts only when Widget or Shortcode is present

Enqueue Conditionally in Shortcodes
The WP Crowd
Published: October 26, 2016

WordPress developers really value loading scripts responsibly. But when you’re building a widget or a shortcode you don’t know where on the site it will be used. This article walks you through exactly how to enqueue your scripts and styles only if your widget or shortcode is present on the page.

Why Do This?

Let’s say you are building a custom theme for a client. They want a certain styled content box to be used on different pages throughout the site. This is a great use for a shortcode

The TLDR; Version

Basically, all you need to do is use wp_register_script or wp_register_style anywhere in your plugin or theme. Then use wp_enqueue_scripts inside the function of your widget or shortcode output.

The Longform Version

First thing you need to understand is the difference between wp_register_script versus wp_enqueue_scripts. Here’s a quick list of functions/actions that are relevant to this discussion but are different enough that we really need to understand in order to do this right.

  • wp_enqueue_scripts — this is an ACTION. You use this to call a function that will trigger the next two items here.
  • wp_enqueue_script — this is a FUNCTION which does the actual work of enqueueing your script. Should be called by wp_enqueue_scripts.
  • wp_enqueue_style — this is a FUNCTION which does the actual work of enqueueing your stylesheet. Should be called by wp_enqueue_scripts.
  • wp_register_script — this is a FUNCTION which tells WordPress your script exists but doesn’t do anything with it. Should be called by wp_enqueue_scripts.
  • wp_register_style — this is a FUNCTION which tells WordPress your stylesheet exists but doesn’t do anything with it. Should be called by wp_enqueue_scripts.

In order for WordPress to serve up a script or style, it needs to know it exists. In order for WordPress to know your style or script exists at all, it needs to be registered. This can be done with wp_register_script/style just to get your script in the system.

But loading a script/style onto a page is called “enqueueing”. In order to enqueue, WordPress needs to know the script/style exists, but fortunately, wp_enqueue_script/style does the job of both registering and enqueueing, while wp_register_script/style only registers.

For example, if you want to just load up a stylesheet all over your whole site, you can use the full definition of wp_enqueue_style like this:

Notice the following arguments that are passed there:

  1. $handle — the name you designate for this stylesheet
  2. $src — where to find this stylesheet
  3. $deps — name of any other stylesheets that you want to be enqueued before this one
  4. $ver — version number for this stylesheet (helpful for plugin authors who want to cachebust based on plugin version number)
  5. $media — which media this stylesheet should be applied to, like “screen”, “print”, or “all”.

All of these attributes can — and should — be defined in one form or another. That effectively makes the stylesheet get loaded on every frontend page of your website. Many plugins do this, and sometimes for very good and purposeful reasons. But most really don’t need to do this.

What we want to do instead is enqueue the style only if a specific shortcode is present on the page. For example, here’s a sample shortcode that enqueues a stylesheet globally:

This works just fine. The problem is though that the stylesheet will be enqueued EVERYWHERE regardless of whether the shortcode is being used on the page or not.

To fix this, we should instead register the stylesheet so WordPress knows it’s there, then enqueue it from within the shortcode function. The ensures that it is only output into the header of the page(s) it is used on. Like so:

Notice that because we registered the stylesheet with the full arguments, the wp_enqueue_style only needs to call the stylesheet by the handle — we don’t need the source or any other arguments beacause the enqueue function pulls those from your register function. In contrast, wp_register_style can never be called without at least both the handle, and the source.

The same technique can be done with widgets. Simply register the stylesheet or script, then in your function that outputs the frontend widget markup, enqueue the script/style.

Here’s your Homework

Now, go through your personal website and look for some styles or scripts that are enqueued everywhere. Find the plugin, fork it, apply this technique, then either submit an issue to the plugin author’s Github repo, or a support ticket to their Support Forum on how they can do this. The more the merrier!

Get the latest from The WP Crowd

5
Leave a Reply

avatar
4 Comment threads
1 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
4 Comment authors
tony blackRaulRon PasillasSwift Media Recent comment authors

This site uses Akismet to reduce spam. Learn how your comment data is processed.

newest oldest
Swift Media
Guest

nice tips

Ron Pasillas
Guest

Anybody having issues with doing this for their plugin on WP Engine? I did exactly this by modifying McFarlin’s widget boilerplate and it works beautifully on my local environment, but for some reason not on WP Engine.

Ron Pasillas
Guest

Update: WP Engine support had to fidget with the caching as the problem was on their end.

Raul
Guest

I like that I was able to find this. Don’t know if wordpress has change since the writing of this but by doing what you suggest the style sheet gets added to the footer and not the header,

tony black
Guest

thank you this is amazing it work for me perfectly