Menu Item

Intro

To allow users to edit and manually adjust their menus, WordPress provides the Menu feature. It allows users to:

1. Create one or more separate menus
2. Add items (or "Menu items") to those menus.
3. Assign menus to varios theme locations, which the developer of a theme has defined.

The Menu Item location in Ultimate Fields allows you to add additional fields to any menu item. All fields, which exist in Ultimate Fields are also supported in menu items, meaning that you can really take your menus to the next level.

Usage through the interface

To add fields to a menu item with the the Administration Interface, please follow these steps:

1. If you are not on the "Add Container" screen already, locate the "Ultimate Fields" section in the administration area and click the "Add New" button on the top (next to the "Containers" title).
2. Locate the "Locations" box.
3. Click "Menu Item" from the bottom row.
4. Adjust all needed options. All of them are described further down this page.

Usage through PHP

The menu item location in Ultimate Fields is handled by the Ultimate_Fields\Location\Menu_Item class. In order to use it, you can either create the new location object manually or let the container do it for you.

The constructor of the class looks like this:

public function __construct( $args = array() ) {

$args is an array, which allows you to set arguments without having to explicitly call the particular setter. For example, you can pass 'theme_locations' => 'main-menu' instead of calling ->set_theme_locations( 'main-menu' )

Manual Creation

Create a new location by using the new keyword and assign it to the container through the add_location() method.

use Ultimate_Fields\Container;
use Ultimate_Fields\Location\Menu_Item;

$container = Container::create( 'menu-item-data' );

// Create a new location and add definitions to it
$location = new Menu_Item();
$location->set_levels( 1 );

// Once the location has been fully set up, add it to the container
$container->add_location( $location );

Automatic creation

You can also let the container create the location for you by providing the "menu_item" string as the first parameter to add_location(). The rest of the parameters are the same as for the constructor of the location class.

use Ultimate_Fields\Container;

Container::create( 'menu-item-data' )
	->add_location( 'menu_item', array(
		'levels' => 1
	));

This method allows you to use method chaining and shortens the syntax, in order to make the code more readable.

Data retrival

To retrieve the values of fields, associated with the Menu Item location, you can skip the $type parameter for *_value functions. You simply need to provide a number (int), containing the menu item ID (ex. get_value( 'icon', 10 )).

The reason that you do not have to specifiy a particular type is that WordPress stores menu items as posts and Ultimate Fields uses the same datastore for both posts and menu items.

Example:

$icon = get_value( 'icon', $menu_item->ID );

Options

All options below are an MVIE Rule

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

Theme locations

Theme Menu Locations in WordPress allow theme developers to define specific areas in their themes, where a menu can be added. This is done through the register_nav_menu function, like this:

register_nav_menu( 'main-menu', __( 'Main Menu', 'showcase' ) );

If you want to, you can limit the display menu item containers to menus, which are associated with a specific location. This way you could allow users to enter additional data for the main menu, where it will be displayed, but not for other menus.

In the UI,

just check the checkboxes next to the locations, which you want to hide/show the fields on.

In PHP, you can use the theme_locations argument or the set_theme_locations method:

use Ultimate_Fields\Container;

Container::create( 'main-menu-item' )
	->add_location( 'menu_item', array(
		'theme_locations' => 'main-menu'
	));

Particular menus

In some situatuins you might want to only show custom fields on a particular menu, based on its ID.

In the UI

this option is not available.

In PHP

you can use the menus argument or the set_menus method:

use Ultimate_Fields\Container;

Container::create( 'specific-menu-item' )
	->add_location( 'menu_item', array(
		'menus' => 5
	));

Levels

In some situations you might only want to show menu item fields when an item is on a specific level.

For example, if you are creating some sort of a mega menu, where submenus are full-width and contain a sidebar, you will only want to add options to top-level menu items. In the same time, you might want to show some completely separate options for sub-menu items.

For this, you can use the "Levels" option.

In the UI,

you can enter numeric levels, separated with commas. Use 1 for the first level, 2 for the second one and etc. You can enter both values for which levels to show fields on and which levels to hide them on.

In PHP,

you can use the levels argument or the set_levels method:

use Ultimate_Fields\Container;

Container::create( 'mega-menu' )
	->add_location( 'menu_item', array(
		'levels' => 1
	));

Popup mode

The boxes, which WordPress provides when editing menu items are quite small, providing only 390 horizontal pixels for additional fields. This width might be insufficient for some fields or you may just decide that fields are occupying too much vertical space.

In those situations, you can use the "Popup Mode" of menu item locations. In popup mode, instead of displaying fields directly in the menu item, Ultimate Fields will only display a button. Once th button has been clicked, Ultimate Fields will show the fields in a new popup.

In the UI,

check the checkbox in the "Popup mode" setting field.

In PHP,

you can use the popup_mode argument or the show_in_popup method:

use Ultimate_Fields\Container;

Container::create( 'mega-menu' )
	->add_location( 'menu_item', array(
		'popup_mode' => true
	));