Manual Integration

Knowledgebase Docs » UberMenu 3
USEFUL? 12
UberMenu 3

Overview

To manually integrate UberMenu into your theme, you simply copy the generated PHP from the UberMenu Control Panel and paste it into the appropriate template in your theme. This outputs an UberMenu.

There are two common use cases for needing manual integration: adding a new menu, or replacing an existing theme menu to eliminate interference from the theme.

Adding a new menu

If you want to add a menu to your site, where there previously was none, this code can be used to add an UberMenu by placing it in your theme template files. Skip to Generating the UberMenu integration code

Replacing an existing menu to avoid residual styling and other interference from your theme

Some themes are not coded modularly, and their CSS interferes with the menu functionality because of their imprecision. Manual integration allows us to replace the theme’s navigation system (the entire block of HTML and PHP in the theme that is responsible for the menu), thereby eliminating the interference from the theme, which allows the menu to look and function properly.

In this case, we use manual integration to conditionally replace the theme’s menu system, rather than just deleting the offending CSS or classes from the template, in order to preserve the theme’s menu system and make updates and changes easier in the future.

For more information on why this happens and why manual integration is the best solution, see residual styling and Theme Interference

Note: You should always make changes to your theme in a Child Theme in order to preserve them. The exact location and strategy will depend on your theme

Locating the theme template

Since every theme is different, the trickiest part of manual integration is figuring out where to paste the integration code. We provide two tools to assist with locating where in all the theme files the theme’s existing menu code lives:

The Residual Styling Detection / Manual Integration Tool, which helps you identify the source of the interference, and then searches the theme files for possible integration locations

And the Locate Theme Template Backtrace, which shows you the stack trace (function calls and file names with line numbers) of where the menu is generated.

The Theme Template Backtrace is the fastest way to locate the exact code you need, but you need to have already determined which theme markup needs to be replaced to eliminate the residual styling.

Video Tutorial

This video tutorial walks you through identifying residual styling, finding the source of the issue, manually locating the theme’s menu, creating a child theme, and conditionally displaying UberMenu via manual integration. The video covers everything in detail for those less familiar with editing code – most people will find it faster to just follow the text instructions below.

Generating the UberMenu code

The PHP code that will output UberMenu can be generated via the Control Panel.

Navigate to Appearance > UberMenu > Main UberMenu Configuration (or your desired configuration, if you have multiple). Click on the Integration tab on the left and scroll to the Manual Integration Section

Ideally, you will also wrap your code in an if( function_exists( 'ubermenu' ) ) statement – this way, if you disable the UberMenu plugin, you won’t get an error.

Integrate by Menu

Common use case: adding a new menu to an undefined theme location

If you have an existing menu that you want to add to the theme, scroll to the Integrate Specific Menu section of the Manual Integration Code. In the select box, choose from your existing menus (created in Appearance > Menus) the menu you want to insert. The Manual Integration Code will update accordingly.

Add the code to your theme – in this case

<?php ubermenu( 'main' , array( 'menu' => 2 ) ); ?>

Integrate by Theme Location

Common use case: replacing an existing theme menu that was created with a theme_location parameter

Using Theme Locations for your menu is more flexible than using a specific Menu, and is generally recommend when one is available. If you have an unused Theme Location (for example, one that you are replacing), you should use it. Otherwise, you can register a custom theme location for your use, or use the Menu Swapper plugin to create more Theme Locations through its Control Panel.

Scroll to the Integrate Specific Theme Location section of the Manual Integration Code. In the select box, choose the Theme Location you want to insert. The Manual Integration Code will update accordingly.

Add the code to your theme (see “Replacing an existing menu” below if you are replacing an existing menu) – in this case:

<?php ubermenu( 'main' , array( 'theme_location' => 'primary' ) ); ?>

Replacing an existing menu

If you are replacing an existing menu in your theme, you will also want to remove (or comment out) or conditionally disable the existing theme menu code. Place the UberMenu Manual Integration Code where the theme code used to be.

Not sure where your theme’s menu is located? Check the header.php first. Every theme is different, so if you can’t find it, the Residual Styling Detection / Manual Integration Tool to determine the source of the residual styling and the Locate Theme Template Backtrace will help you locate the exact location in your theme files

One good strategy for this is to test for UberMenu’s existence, and fall back to the theme menu otherwise. For example, if the theme’s menu looks like this:

<nav id="navigation">
  <?php wp_nav_menu( array( 'theme_location' => 'primary' ) ); ?>
</nav>

a good strategy would be to integrate UberMenu like this:

<?php if( function_exists( 'ubermenu' ) ): ?>
  <?php ubermenu( 'main' , array( 'theme_location' => 'primary' ) ); ?>
<?php else: ?>
  <nav id="navigation">
    <?php wp_nav_menu( array( 'theme_location' => 'primary' ) ); ?>
  </nav>
<?php endif; ?>

(Note that the theme location parameters match; you would still activate UberMenu on the Primary theme location in this case)

Here’s what each line is doing:

Or in general:

<?php if( function_exists( 'ubermenu' ) ): ?>

	<!-- UberMenu integration code goes here -->

<?php else: ?>

	<!-- Existing Theme Menu code goes here -->

<?php endif; ?>

The pattern is to place this code before the existing menu:

<?php if( function_exists( 'ubermenu' ) ): ?>
  <?php ubermenu( 'main' , array( 'theme_location' => 'primary' ) ); ?>
<?php else: ?>

and this code after it:

<?php endif; ?>

You don’t need to actually edit the theme’s menu, just locate it and then place that condition and integration code around it.

Result:

<?php if( function_exists( 'ubermenu' ) ): ?>
  <?php ubermenu( 'main' , array( 'theme_location' => 'primary' ) ); ?>
<?php else: ?>
  <!-- The theme's menu code goes here -->
<?php endif; ?>

Adding a new menu

If you are adding a new menu, you can insert the UberMenu Integration Code wherever you like in the theme’s templates.

Where do I add the code?

It will depend on your theme, but in the majority of themes, the wp_nav_menu function call can be found in the header.php template, so that’s where you’ll want to start looking.

The Residual Styling Detection / Manual Integration Tool will help you determine the code to be replaced and locate the exact location in your theme files if you are having trouble finding it.

The Locate Theme Template Backtrace setting can help you find the proper location if you already know what code needs to be replaced.