Overview
The WordPress ecosystem is incredibly broad and diverse. The WordPress platform allows for many different code bases (themes and plugins) from a variety of developers to be installed together on the same site. This makes it very powerful, but also raises the potential for conflicts.
Modular component design is very important in modern web development. Essentially, this means that each piece of the user interface is self-contained; and the code from one module does not affect or interfere with another.
Conflicts arise when developers don’t write their code modularly, and code from one theme/plugin starts interfering with another. This means that the CSS, Javascript or PHP from one theme/plugin is applying to a separate theme/plugin when it should not be.
Unfortunately, not all themes and plugins are coded modularly, and those that aren’t can interfere with and break other themes or plugins installed on your site. When this happens, we have a variety of ways of identifying and resolving the conflict.
Types of conflicts
CSS Styling
By far the most common type of interference, if not written modularly, CSS styling from themes can apply to the menu. We refer to this as Residual Styling. This interference breaks the look and layout of the menu, which often negatively impacts functionality as well.
Javascript
Javascript interference is less common, but when it occurs, tends to go hand in hand with Residual Styling. It is generally resolved in the same way. It breaks the functionality of the menu.
PHP filters
WordPress is built with a powerful hooks system, which allows code from any theme or plugin to hook into different processes and filter the output. For example, a theme might use a filter to change the classes on menu items or the code that processes a menu. When done properly and applied only to their own menus, this is fine, but if applied imprecisely and without care, can break other menus on the site such as UberMenu.
Please see Theme Interference for more information on common ways themes filter the menu output and how to address them.
How do I know if there is interference?
Generally, it’s fairly obvious just looking at the menu. However, if you’re not sure, there are two ways to compare to a “clean” version:
1. Use the Sandbox
The Sandbox allows you to preview the menu in the admin panel and in 99% of cases will display the menu without CSS or Javascript interference.
You can visually compare what you see on the front end to what you see in the Sandbox to tell if you have interference.
2. Use the Direct Injection Testing setting
You can enable the Direct Injection option in the UberMenu Control Panel which will insert the menu into your site but just inside the body tag. This generally eliminates all residual styling (though PHP filters would still affect it in most cases).
You can use this as well to visually compare to your automatically integrated menu.
Be sure to disable this setting when you are done.
Finally, using the methods to identify residual styling as described below can also help determine if you have interference.
How to resolve CSS & Javascript interference
In general, the most robust solution for resolving front-end interference from a theme involves modifying the markup produced to eliminate the source of the interference.
For example, if the theme wraps the menu in a div with the ID “menu”, such that the following output is produced:
<header>
<div id="menu">
<nav class="ubermenu">...</nav>
</div>
</header>
and has styling such as
#menu a{
color:red;
}
which is overriding UberMenu’s styling and forcing the links to all appear red, then we would alter the theme output to remove the surrounding div#menu such that those styles no longer apply.
<header>
<nav class="ubermenu">...</nav>
</header>
The strategy for modifying the theme’s markup depends on how the theme is coded (though should almost always be done in a child theme). Common ways of changing the theme’s menu markup would be:
- Changing the markup directly in a WordPress theme template file
- Replacing the markup via a filter or action hook
- Overriding the markup via a pluggable function
Identifying, assessing, and integrating
Every theme is different, so how do you figure out how to modify your specific theme?
1. Check the guides
First, be sure to check out the Theme Integration Guides. We have a variety of guides for the most popular themes which will take you step by step through the integration for those themes.
2. Are you using a page builder?
If you’re controlling your header with a page builder, then if you have interference it’s likely because you’re trying to automatically integrate with the theme or page builder’s built-in menu block. Instead, replace that block with UberMenu.
Please see the Page Builders doc for more details.
3. Manual integration
If you’re using a traditional theme where the header and menu are controlled with PHP template files, then replacing the menu by altering the code directly will be necessary to eliminate styling interference from the theme. This is called Manual Integration. If there isn’t already a guide for your specific theme, then these instructions provide a general strategy for identifying, locating, and replacing any theme’s menu.
Manual Integration Process
This is how to find and replace the theme’s interfering menu code with UberMenu within the theme template files of a standard theme. If you’re using a page builder, then you’ll likely integrate via the builder itself.
Note that this assumes you’ve been able to use Automatic Integration to replace the theme’s menu, so you can see UberMenu, but there is interference to be resolved.
Here’s an overview of the 3 steps to eliminating residual styling via manual integration.
1. Identify the source of the interference
In the simple example we used above, this means determining that the source of the problem is the #menu div that is wrapping UberMenu, and that eliminating that element from the markup will eliminate the interference.
If you’re familiar with using your browser’s Developer Tools, the fastest way to do this is generally to open the Inspector and inspect the menu. Look for the containers surrounding the menu. Starting with the parent element, remove classes and IDs and watch as the menu display changes. It’s usually very obvious once the class/ID is removed (you can also enable Direct Injection to compare to a menu that is likely without interference). Once you find the source of the interference, note it as this is the element that you’ll be looking to replace. We have a detailed guide and video tutorial of this process in the Manual Integration doc.
If you’re not comfortable with the Developer Tools, then you can use the built-in Residual Styling Detection/Manual Integration Tool to walk you through the process of identifying the source of the interference.
2. Locate the relevant code within the theme files
Once you’ve identified the source of the interference, you need to locate the code within the theme that generates that markup. In addition to manually searching the theme files, we provide two tools to assist:
Locate Theme Template Backtrace Tool
Enable this option and UberMenu will print the backtrace of files called to print the menu. You can check each of these files (it is almost always the first listed) for the markup identified in step 1.
Residual Styling Detection/Manual Integration Tool
You can use this tool to search the theme files for likely sources of the theme. For most themes this will work well, though some themes repeat the same markup over and over again in various files, in which case using the Locate Theme Template Backtrace setting will help pinpoint the source.
3. Replace the relevant code with UberMenu’s PHP function
Keep in mind that this should almost always be done in a child theme, so you’re either overriding a template or a hook or pluggable function via a child theme. Don’t edit the parent theme directly, as that edit will be overwritten if/when you update the theme.
To replace the theme’s code, we use a conditional statement to only do so when the UberMenu plugin is active. This way the site will just revert to the theme’s menu if UberMenu is inactive.
First, generate the UberMenu PHP Manual Integration code via the UberMenu Control Panel
Then replace the element that is the source of the interference, e.g.
Before:
<div id="menu">
<?php wp_nav_menu(); ?>
</div>
After:
<?php if( function_exists( 'ubermenu' ) ): ?>
<?php ubermenu( 'main', array( 'theme_location' => 'primary') ); ?>
<?php else: ?>
<div id="menu">
<?php wp_nav_menu(); ?>
</div>
<?php endif;?>
In this example, the UberMenu markup is no longer wrapped in the #menu div, so the interfering styles no longer apply.
Having trouble?
Most of the time, manual integration is a pretty painless process. But every theme is different, and some can be very complex.
If you’re having trouble integrating on your own, please Submit a Ticket and we’ll help you assess your theme and get things set up!