Introduction to UberMenu Conditionals

Plugin: UberMenu Conditionals
Plugin by: Chris Mavricos, SevenSpark
Website: sevenspark.com
Created: September 10, 2012
Guide Last Updated: September 10, 2012

Welcome to UberMenu Conditionals! Thank you for purchasing this plugin, I appreciate it!

This guide should answer all your questions about how to use this plugin. You can browse the document using the navigation sidebar on the left, or search the entire document by using CTRL+F in your browser.

The latest version of this support guide can always be found here: UberMenu Conditionals Support Guide.

Getting Support

First, please take a moment to search this file, as the answer to your question is likely already in here. You can press CTRL+F in your browser and then search this entire page for keywords. Or, browse the topics in the navigation on the left. It's the fastest way to get the answer you need!

Please be polite when requesting support, and I'll be sure to respond as soon as possible. I'll do my best to answer your questions, but unfortunately I generally can't offer customizations beyond a few lines of code - there just aren't enought hours in the day! Of course, I will always provide fixes for any bugs that crop up as soon as can be :)

When requesting support, please indicate which product you are referring to, explain what you've already tried and provide a link to your site so I may see the issue firsthand. It's really the only way to efficiently diagnose a problem. Thanks!
I can't find my answer in this guide. Get Support →

Requirements

  1. WordPress 3.4+
  2. UberMenu 2.1+

Installation

Install the Plugin

WordPress Plugin Uploader

You can install UberMenu Conditionals via the WordPress plugin uploader without unzipping the file.

  1. Log into your WordPress admin panel
  2. Navigate to Plugins > Add New
  3. Click Upload
  4. Click Choose File and select the UberMenu Conditionals download zip.
  5. Click Install Now.

FTP

You can also install UberMenu Conditionals via FTP

  1. Extract the .zip file you downloaded from CodeCanyon.
  2. Find the ubermenu-conditionals folder (this directory is created when you unzip the file).
  3. Upload the ubermenu-conditionals folder to your wp-content/plugins directory.
  4. Navigate to your Control Panel: Plugins
  5. Under UberMenu Conditionals, click Activate

What did this do?

Installing the plugin doesn't automatically change any navigation menus - so it immediately affect anything on your site, either. Once you install the plugin, you'll get:

  • New conditional options for Menu Items in the Appearance > Menus Control Panel
IMPORTANT NOTE

If you deactivate the UberMenu Conditional Plugins and then save your menu, you will lose all of your previously set conditions. In other words, if you save your menu while the plugin is disabled, you will reset all of your conditions to the default.

Usage

Activating UberMenu Conditionals will add two new options to each of your menu items in Appearance > Menus, Conditional Display: Show item and Conditional Parameters.

new options

Conditional Display: Show item

Setting the option here will enforce that the menu item is displayed ONLY when the chosen condition is met. For example, if "On front page" is selected, the item will be displayed on the front page, and not on any others.

Condition Function Explanation
(blank) none This setting will not affect the menu item at all
Always N/A The menu item will always be displayed. The difference compared to the blank setting is that this will override any filters with lesser importance.
If user is logged in is_user_logged_in() Item will be displayed only if the curreunt user is logged in to your site.
If user is not logged in !is_user_logged_in() Item will be displayed only if the curreunt user is NOT logged in to your site.
If user can [capability] current_user_can( $capability ) Item will be displayed only if the current user has the capability which is set in the Conditional Parameters (required). For mapping Roles (Admin/Editor/Author, etc) to Capabilities (edit_posts, manage_options, etc), please see Roles vs. Capabilities table
If user cannot [capability] !current_user_can( $capability ) Item will be displayed only if the current user DOES NOT HAVE the capability which is set in the Conditional Parameters (required)
Use is [role] check_user_role( $role ) Item will be displayed only if the current user is in the role set in the Conditional Parameters (required). Roles include administrator, editor, author, contributor, and subscriber
Use is not [role] !check_user_role( $role ) Item will be displayed only if the current user IS NOT in the role set in the Conditional Parameters (required). Roles include administrator, editor, author, contributor, and subscriber
On front page is_front_page() Item will be displayed only when the main blog page is being displayed and the Settings > Reading > Front page displays is set to "Your latest posts", or when is set to "A static page" and the "Front Page" value is the current Page being displayed. In other words, displayed only on the main URL of your site
Not on front page !is_front_page() Displayed on all pages but the front page (main URL) of your site
On home page (main blog) is_home() Item will be displayed when the main blog page is being displayed. This is the page which shows the time based blog content of your site, so if you've set a static Page for the Front Page (see below), then this will only be true on the Page which you set as the "Posts page" in Administration > Settings > Reading.
Not on home page (main blog) !is_home() Item will be displayed when any page EXCEPT the main blog page is being displayed.
On a page is_page() Item will be displayed when on a Page
Not on a page !is_page() Item will be displayed when NOT on a Page
On a single post is_single() Item will be displayed when a single Post is being displayed.
Not on a single post !is_single() Item will be displayed when a single Post is NOT being displayed.
On a page template is_page_template() Item will be displayed when on a page template.
On a page template is_page_template() Item will be displayed when NOT on a page template.
On a Category Archive is_category() Item will be displayed on Category Archive pages
On a Tag Archive is_tag() Item will be displayed on Tag Archive pages
On a Taxonomy Archive is_tax() Item will be displayed on Taxonomy Archive pages
On an Author Archive Page is_author() Item will be displayed on Author Archive pages
On any archive page is_archive Item will be displayed on any archive page
On Search Results Page is_search Item will be displayed on search results page
On 404 Page is_404 Item will be displayed on 404 page
On a single Page, Post, or Attachment is_singular Item will be displayed when a single Page, Post, or Attachment is being displayed.
On a Post Type [type] get_post_type() Item will be displayed when the current page is a particular post type. The Conditional Parameter must be set to the post type slug. e.g. post, portfolio-item, etc. Added in version 1.1

Conditional Parameters

Some of the conditional functions used can take a parameter. UberMenu Conditionals uses the Conditional Parameters setting to pass additional information to the functions.

Single String or Integer Parameters

For example, to display an item only on a particular page, set the Conditional Display to On a page and set the Conditional Parameter to the ID of that page.

conditional parameter

In the example above, the menu item will only be displayed on the page with the ID 255

Multiple String or Integer Parameters

Some of the conditional functions allow you to pass an array of strings or integers as a parameter. To do so, use a comma-delimited list in the parameters setting. UberMenu Conditionals will automatically convert any value with a comma into an array to pass to the conditional function.

For example, to display an item only on a specific group of pages, set the Conditional Parameters to a comma-delimited string of the page IDs: 255, 119

multiple conditional parameters

In the example above, the menu item will be displayed only on two pages: page 255 and page 119.

Tip: The content Conditional Parameters input box will always be passed as the first parameter of the conditional function. If the value contains commas, it will be passed as an array. To pass a second parameter to the few conditional functions that support it, you'd need to write a custom conditional filter.

Examples

Display Item only for admins

Conditional Display: Show ItemUser is [role]
Conditional Parameteradministrator

Display Item only for users who can manage options

Conditional Display: Show ItemIf user can [capability]
Conditional Parametermanage_options

Dynamic URLs

Logout

Adding a logout button to your menu requires a dynamic URL, as a nonce is required. UberMenu Conditionals allows you do do this by creating a Custom Menu Item and setting the URL to #umcdu-logout.

Logout URL

Please note that the dynamic URL will only be processed for UberMenu items where a condition has been set

Custom Conditional Filters

If you need a conditional statement more advanced than the provided parameters, UberMenu Conditionals allows you to write a custom conditional filter.

The best place to put custom conditional filters would be in your child theme's functions.php, or in a separate plugin. This is totally up to you and depends on how you manage your site.

Here's an example of a custom conditional filter that makes sure a particular menu item will not display on the front page for logged in users.

function my_custom_conditional_filter( $display_on , $walker , $element , $max_depth, $depth, $args ){

	//The ID of the menu item currently being filtered
	$id = $element->ID;

	//Check for that specific menu item
	if( $id == 268 ){

		//If we're currently logged in AND on the front page
		if( is_user_logged_in() && is_front_page() ){

			//Disable the menu item
			$display_on = false;

		}

	}

	//Return the filtered display boolean
	return $display_on;
}
add_filter( 'uberMenu_display_item', 'my_custom_conditional_filter', 20, 6 );
Important notes:
  1. 268 is the ID of the menu item we are filtering - it will be specific to your menu item. It can be determined by looking at the ID of the menu item within your menu.
  2. It is very important to return $display_on; when your conditions are not met
  3. To display the menu item, return true; To hide the menu item, return false; to not change the current value of the menu item's display visibility, return the incoming $display_on value.
  4. The second parameter of the add_filter() function call and your function name (my_custom_conditional_filter) must match.
  5. You should keep the function definition as in the example; the only things that should change are the function name if you wish, and the contents of the function.

Frequently Asked Questions

Can conditions be combined?

To create a more complex condition, you can create a custom condition. It is not possible to select more than one condition in the menu item settings.