A tale of WordPress conflicts

Unrelated Themes and Plugins can sometimes conflict with each other, having a debugging workflow in place is always a good idea.

Yesterday I discovered a broken element on my Events Calendar and jumped into the browser console to investigate.

console error
At first glance I assumed the error is was within my Modern Tribe Events Calendar plugin.

JavaScript like PHP is tricky to debug, an error could read g.tribe_has_attr is not a function but be caused by something else on the page.

After creating a full site backup I duplicated it in a staging environment to safely hack away.

My WordPress debugging workflow

  1. Check if this error appears on other pages, in this case it didn’t.
  2. Disable current theme and activate a default theme like TwentySixteen.
  3. Reload page to see if error persists.

The error disappeared which led me to suspect the actual flaw was in my theme’s code and not Modern Tribe’s Events Calendar.

My next step to uncover the cause took me to functions.php as it contains all the enqueued JavaScript for my custom theme. I commented out all the enqueues and almost magically the error disappeared from the page. Activating them one at a time I uncovered where the error originated.

functions.php enqueue screenshot with jQuery commented out
After commenting out my theme’s jQuery requirement the error disappeared.

My theme is based on a responsive framework and includes a jQuery dependency for many of the interactive elements. A minified jQuery library for Foundation 6 was the culprit. Without it slideshow carousels, galleries, accordions and other features would not work.

A minified jQuery library for Foundation 6 was the culprit.

It’s probable that I made a mistake in how this jQuery was implemented in the theme. Ideally I’d audit the code but that wasn’t really an option. The next best solution is to remove this jQuery from the pages where it became a problem. At first I was going to dequeue it in my child theme where Events Calendar is used. However, creating a simple plugin that I could activate and deactivate seemed like a more elegant solution.

Remove Foundation jQuery plugin
Dequeuing jQuery where it became a problem isn’t ideal but it’s a good fix.

Theme jQuery vs. Plugin jQuery?

I didn’t take the time to audit the precise conflict and determine whether it’s caused by my theme’s jQuery library butting heads with The Events Calendar’s version but having multiple enqueued versions sounds like a path towards disaster.

My to-do list minimize script conflicts in the future

  • Read and understand how jQuery is and should be properly enqueued for Themes and Plugins
  • Create a Plugin for each of the Theme’s interactive elements so they are self-contained blocks

I’m not certain independent plugins would lead to a better workflow. Photo galleries, content accordions, image carousels could all be maintained separately and activated as needed. But this could lead to a longer set up process for creating a new site. Then again, on child themes that don’t need all these features it would lead to a leaner code base.

Please leave a comment below if you have any suggestions on dealing with Theme and Plugin conflicts.