WordPress.org

Ready to get started?Download WordPress

Plugin Directory

Custom Menu Wizard Widget

Show branches or levels of your menu in a widget, or in content using a shortcode, with full customisation.

  1. EITHER Upload the zip package via 'Plugins > Add New > Upload' in your WP Admin

    OR Extract the zip package and upload custom-menu-wizard folder to the /wp-content/plugins/ directory

  2. Activate the plugin through the 'Plugins' menu in your WP Admin

The widget will now be available in the 'Widgets' admin page. As long as you already have at least one Custom Menu defined, you can add the new widget to a sidebar and configure it however you want. Alternatively, you can use the shortcode in your content.

Current documentation for the Widget Options can be found under Other Notes.

SHORTCODE PARAMETERS

NB. Version 2 documentation is here.

The shortcode is [cmwizard] (prior to v3, shortcode was [custom_menu_wizard], and it is still supported but with a slightly different parameter set). Most of the attributes reflect the options available to the widget, but some have been simplified for easier use in the shortcode format. Please note that the Hide Widget if Empty option is not available to the shortcode : it is set to enabled, and if there are no menu items found then there will be no output from the shortcode.

The simplest way to build a shortcode is to use a widget : as you set options, the equivalent shortcode is displayed at the base of the widget (v3+) and the base of the "assist". The widget itself need not be assigned to a widget area, so you can construct your shortcode using a widget in the Inactive Widgets area if you have no need for an active one. Please remember that any options you play with while constructing your shortcode do not have to be Saved to the widget itself! Just copy-paste the shortcode when you are happy with it.

title

string : The output's Title, which may be overridden by title_from. Note that there is no shortcode equivalent of the widget's Hide option for the title.

menu

string or integer : Accepts a menu name or id. If not provided, the shortcode will attempt to find the first menu (alphabetically) that has menu items attached to it, and use that.

level

integer : Sets the Level filter to the specified (greater than zero) value. Defaults to 1, and is ignored if either branch or items is specified.

branch

string or integer : If not empty then Branch is set as the primary filter, with the branch item being set from the assigned value:

  • If numeric, it is taken as being the id of a menu item.
  • If set to either "current" or "current-item" then the Branch item is set to "Current Item".
  • If any other string, it is taken to be the title of a menu item (within the selected menu). The widget will look for the first caseless title match, so specifying branch="my menu item" will match against a menu item with the title "My Menu Item".

items

string : Comma-separated list of meu item ids, where an id can optionally be followed by a '+' to include all its descendants (eg. "23+"). Takes priority over branch.

start_at

string : This is only relevant to a Branch filter, and consists of a signed or unsigned integer that indicates either a relative (to the selected branch item) or absolute level to start your output at (ref. the widget's Starting at option under Secondary Filter, Filters Section). By default the starting level for output is the branch item's level. A relative level is indicated by a signed (ie. preceded by a "+" or "-") integer, eg. start_at="+1", while an absolute level is unsigned, eg. start_at="1". Some examples :

  • start_at="+1" : (relative) start at the branch item's level + 1 (also accepts start_at="children")
  • start_at="-1" : (relative) start at the branch item's level - 1 (also accepts start_at="parent")
  • start_at="-2" : (relative) would be the "grandparent" level
  • start_at="1" : (absolute) start at the root item of the selected branch (also accepts start_at="root")
  • start_at="2" : (absolute) start at one level below root (still within the selected branch)

start_mode

string : This has only one accepted value - "level" - and is only applicable for a Branch filter whose start_at setting returns in an item is at or above the selected branch item (relatively or absolutely). Setting start_mode="level" forces the widget to use not only the resultant starting item and its relevant descendants, but also all that item's siblings and their descendants (ref. the widget's Level radio option under Secondary Filter, Filters Section).

allow_all_root

switch, off by default, 1 to enable : See widget's Allow all Root Items option, under Secondary Filter, Filters Section.

depth

integer, default 0 (unlimited) : See widget's For Depth option, under Secondary Filter, Filters Section.

depth_rel_current

switch, off by default, 1 to enable : See widget's Relative to Current Item option, under Secondary Filter, Filters Section.

ancestors

integer, default 0 (off) : Sets an absolute level (positive integer), or a relative number of levels (negative integer), for which the ancestors of the Branch filter item should be included. See widget's Branch Ancestors option, under Inclusions, Filters Section. (only relevant to a Branch filter)

ancestor_siblings

integer, default 0 (off) : Sets an absolute level (positive integer), or a relative number of levels (negative integer), for which the siblings of ancestors of the Branch filter item should be included. See widget's ... with Siblings option, under Inclusions, Filters Section. (only relevant to a Branch filter)

siblings

switch, off by default, 1 to enable : See widget's Branch Siblings option, under Inclusions, Filters Section. (only relevant to a Branch filter)

include_level

string : A level (1, 2, 3, etc), optionally followed by a "+" or "-" to include all subsequent (lower) or prior (higher) levels respectively. For example, "2" will include all items at level 2, whereas "2-" would include all level 1 and level 2 items, and "2+" would include all items at level 2 or greater.

Note that prior to v3.0.4, this was include_root (a switch), which only included the root level : include_root is still accepted, even though now deprecated, and is equivalent to setting include_level to "1". However, if include_level is specified then it takes precedence.

exclude

string : Comma-separated list of meu item ids, where an id can optionally be followed by a '+' to include all its descendants (eg. "23+").

exclude_level

string : A level (1, 2, 3, etc), optionally followed by a "+" or "-" to include all subsequent (lower) or prior (higher) levels respectively. For example, "2" will exclude all items at level 2, whereas "2-" would exclude all level 1 and level 2 items, and "2+" would exclude all items at level 2 or greater.

contains_current

string : Accepted values : "menu", "primary", "secondary", "inclusions", or "output". See widget's Qualifier options, under Filters Section, for an explanation of the respective settings.

fallback

string : There are 2 main options for the "If Current Item has no children" fallback (ref. Fallbacks Section)...

  • "parent" : Sets the widget's Starting at Fallback option to "-1 (parent)"
  • "current" : Sets the widget's Starting at Fallback option to "the Current Item"

Either of these 2 values can be further qualified by appending a comma and a digit, eg. fallback="current,1" or fallback="parent,2", which will also set the widget's For Depth fallback option to the value of the digit(s).

Optionally, "+siblings" can also be used (comma-separated, with or without a depth digit) to indicate that siblings of the "parent" or "current" fallback item should also be included. The order of the comma-separated values is not important, so "current,+siblings,1" is the same as "current,1,+siblings", and "2,parent" is the same as "parent,2", etc.

fallback_ci_parent

switch, off by default, 1 to enable : See widget's "If no Current Item can be found" fallback in the Fallbacks Section.

flat_output

switch, off by default, 1 to enable : See widget's Flat option, under Output Section.

title_from

string : Supply one or more (by separating them with a comma, eg. title_from="branch,current") of the following (ref. the widget's Set Title from options, under Output Section)...

  • "current" : enables the widget's Current Item Set Title from option
  • "current-root" : enables the widget's ...or its Root option that relates to the Current Item Set Title from option
  • "branch" : enables the widget's Branch Set Title from option
  • "branch-root" : enables the widget's ...or its Root option that relates to the Branch Set Title from option

ol_root

switch, off by default, 1 to enable : See widget's Top Level option, under Change UL to OL in the Output Section.

ol_sub

switch, off by default, 1 to enable : See widget's Sub-Levels option, under Change UL to OL in the Output Section.

container

string : See widget's Element option, under Container Section.

container_id

string : See widget's Unique ID option, under Container Section.

container_class

string : See widget's Class option, under Container Section.

menu_class

string : See widget's Menu Class option, under Classes Section.

widget_class

string : See widget's Widget Class option, under Classes Section.

wrap_link

string : This is an optional tag name (eg. "div", "p", "span") that, if provided, will be made into HTML start/end tags and sent through to the widget as its Before the Link and After the Link options (ref. Links Section). Please note that the shortcode usage - a simple tag name - is much more restrictive than the widget's options, which allow HTML.

wrap_link_text

string : This is an optional tag name (eg. "span", "em", "strong") that, if provided, will be made into HTML start/end tags and sent through to the widget as its Before the Link Text and After the Link Text options (ref. Links Section). Please note that the shortcode usage - a simple tag name - is much more restrictive than the widget's options, which allow HTML.

alternative

string : This is 2 settings separated by a comma, reflecting the On condition options under the Alternative Section. Possible values are:

  • One of "current", "no-current" or "no-output" : the condition to test for
  • One of "menu", "primary", "secondary", "inclusions", or "output" : the stage at which to test the condition

Eg. alternative="no-current,inclusions" would test for the absence of a Current Item in the filtered menu items, having completed the Inclusions stage, and attempt to switch to the Alternative settings.

The actual Alternative settings - a cut-down shortcode - are placed as content between the shortcodes start and end tags, and this is the only time that the use of a self-terminating shortcode is not sufficient. When specifiying the Alternative settings, do not include the square brackets, otherwise WordPress will interpret it as a nested shortcode!

For example, to set a primary configuration of "show Current Branch plus any kids", with an Alternative of "show top 2 levels" if no current item can be found anywhere in the menu...

[cmwizard menu=NN branch=current alternative="no-current,menu"]depth=2[/cmwizard]

Alternatively, you could switch it around and say the primary configuration is "show top 2 levels", with an Alternative of "show Current Branch plus kids" if a current item can be found within the menu...

[cmwizard menu=NN depth=2 alternative="current,menu"]branch=current[/cmwizard]

Note that Alternative (eg. "branch=current") does not require a menu option, because you can't change the menu so the primary configuration's setting is always used.

As ever, the best way to construct a full shortcode, including an alternative, is to use the Assist : Use one instance of the CMW widget to build your Alternative settings, copy the equivalent shortcode into the Alternative option of a second instance of the CMW widget, and then continue configuring that second instance to be your primary configuration; your final shortcode can simply be lifted from the second instance!

A bit more information about the Alternative option is available in this article.

title_tag

string : An optional tag name (eg. "h1", "h3", etc) to replace the default "h2" used to enclose the widget title. Please note that this option has no equivalent in the widget options, because it only applies when a widget is instantiated via a shortcode.

findme

switch, off by default, 1 to enable : This is a utility intended for editors only, and output is restricted to those with edit_pages capability. If enabled it will return a list of posts that contain a CMW shortcode. If findme is set, the only other option that is taken any notice of is title, which will be output (if supplied) as an H3 in front of the list. The information provided by this utility is also available from any widget's "assist".

Example : [cmwizard findme=1 title="Posts containing a CMW shortcode..."/]

SHORTCODE EXAMPLES

  • Show the entire "main" menu

    [cmwizard menu=main/]

  • Show the children of the current menu item within the "main" menu, for unlimited depth, setting the widget title from the current menu item

    [cmwizard menu=main branch=current start_at=children title_from=current/]

  • From the "animals" menu, show all the items immediately below "Small Dogs", plus "Small Dogs" and its sibling items, as ordered lists

    [cmwizard menu="animals" branch="small dogs" depth=2 include="siblings" ol_root=1 ol_sub=1/]

  • From the "animals" menu, show the entire "Small Animals" branch, with the sole exception of the "Small Animals" item itself, whenever "Small Animals" or one of its descendants is the current menu item

    [cmwizard menu="animals" branch="small animals" start_at=children contains_current=primary/]

  • Show the entire "main" menu entitled "Main Menu" unless there's a current menu item, in which case show the current menu item, its siblings and its immediate children, and entitle it "Nearest and Dearest!"

    [cmwizard menu=main title="Main Menu"]title="Nearest and Dearest!" branch=current depth=2 siblings=1[/cmwizard]

Requires: 3.6 or higher
Compatible up to: 4.1.1
Last Updated: 2014-12-17
Active Installs: 10,000+

Ratings

4.8 out of 5 stars

Support

3 of 6 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

0 people say it works.
0 people say it's broken.

0,1,0
0,1,0 50,2,1 100,2,2 100,1,1
100,1,1
100,2,2
100,1,1
100,2,2
100,1,1 100,1,1