Using jQuery in safe mode

From time to time, we receive a support request from one of our customers asking for help with something missing from a new Event Espresso installation. Sometimes, the element in question is the Calendar, or parts on the registration page are not working.

Event Espresso uses jQuery to power both the calendar and the interactive elements of the registration page, and these features depend on jQuery being run in safe (or no-conflict mode). Any theme that has passed the review process for the WordPress.org theme repository will load jQuery in no-conflict mode, but what about the thousands of other themes out there?

Not all theme authors see the importance of running jQuery in safe mode, and will include their own copy of jQuery and load it instead of the copy that is bundled with WordPress.

Use the WordPress bundled jQuery

When working with a few of our customers, I’ve noticed something like this in the theme’s functions.php:

function super_cool_theme_js() {
  if (is_admin()) return;
  wp_deregister_script( 'jquery' );
  wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js');
  wp_enqueue_script( 'jquery' );
}

While the intentions here may be good (loading up jQuery from Google’s CDN can make the site load faster), this can create problems down the road if the theme does not get updated. jQuery is a very active project, and updates are released at a fairly rapid pace.

Since WordPress will continue to update the version of jQuery that it bundles, by running this version you’ll get the benefit of the latest features and bug fixes of the current version. This also avoids compatibility issues, as most plugin authors are developing and testing with the version of jQuery that is bundled with WordPress.

One possible way to fix the above example would be to remove the lines of code that swap out the bundled version of jQuery, leaving:

wp_enqueue_script( 'jquery' );

Note that there are many different ways to include jQuery, so the way to fix this might be a little different with your specific theme.

Use the $ with a no-conflict wrapper

Another thing I’ve seen is where a theme will have ports of existing jQuery scripts (often called plugins) into the theme. Many times these are copied into the theme without adding a jQuery no-conflict wrapper. Since the $ alias cannot be used when jQuery loads in safe mode, something on the page will break and you’ll see an error in the source of the page like this one:

If the script is being loaded into the header, as it is in the above example, this can usually be fixed by combining the document ready function with a jQuery noconflict() wrapper:

jQuery(document).ready(function($){

If the script is being loaded into the footer, the function can be wrapped like so:

(function($){
// use the $
}(jQuery));

If you’re having JavaScript issues with the theme, it’s usually best to check in with the theme author for help. They wrote the theme and should be familiar with how jQuery was included into the theme’s functions. They might even update the theme and adopt a few of these standards! The WordPress codex article for wp_enqueue_script has more details and links to additional resources on this topic.

Share a Reply or Comment

Your email address will not be published. Required fields are marked *

Need help with Event Espresso? Create a support post in our support forums

Event Espresso