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.

WIDGET OPTIONS

NB. Version 2 documentation is here.

There are quite a few options, which makes the widget settings box very long. I have therefore grouped most of the options into collapsible logical sections (with remembered state once saved).

Note that certain options may be enabled/disabled depending on your choice of primary, and possibly secondary, filters.

Always Visible

  • Title textbox

    Set the title for your widget.

  • Hide checkbox

    Prevents the entered Title being displayed in the front-end widget output.

    In the Widgets admin page, I find it useful to still be able to see the Title in the sidebar when the widget is closed, but I don't necessarily want that Title to actually be output when the widget is displayed at the front-end. Hence this checkbox.

  • Select Menu select

    Choose the appropriate menu from the dropdown list of Custom Menus currently defined in your WordPress application. The first one available (alphabetically) is already selected for you by default.

Filters Section

Filters are applied in the order they are presented.

Primary Filter

  • Level radio (default On) & select

    Filters by level within the selected menu, starting at the level selected here. This is the default setting for a new widget instance, which, if left alone and with all other options at their default, will show the entire selected menu.

    Example : If you wanted to show all the options that were at level 3 or below, you could check this radio and set the select to "3".

  • Branch radio & select

    Filters by branch, with the head item of the branch being selected from the dropdown. The dropdown presents all the items from the selected menu, plus a "Current Item" option (the default). Selecting "Current Item" means that the head item of the branch is the current menu item (as indicated by WordPress), provided, of course, that the current menu item actually corresponds to a menu item from the currently selected menu!

  • Items radio & textbox

    Filters by the menu items that you specifically pick (by menu item id, as a comma-separated list). The simplest way to get your list of ids is to use the "assist", and [un]check the green tick box at the right hand side of each depicted menu item that you want. Alternatively, just type your list of ids into the box.

    If the id is appended with a '+', eg. '23+', then all the item's descendants will also be included.

    Example : If you only wanted to show, say, 5 of your many available menu items, and those 5 items are not in one handy branch of the menu, then you might want to use this option.

    Example : If your menu has 6 root branches - "A" thru to "F" - and you were only interested in branches "B" (id of, say, 11) and "E" (id of, say, 19), you could set Items to be "11+,19+", which would include "B" with all its descendants, and "E" with all its descendants.

Secondary Filter (not applicable to an Items filter)

  • Starting at select

    This is only applicable to a Branch filter and it allows you to shift the starting point of your output within the confines of the selected branch. By default it is set to the selected branch item itself, but it can be changed to a relative of the branch item (eg. parent, grandparent, children, etc) or to an absolute, fixed level within the branch containing the selected branch item (eg. the root level item for the branch, or one level below the branch's root item, etc).

    Example : If you wanted the entire "current" branch then, with Branch set to "Current Item", you might set Starting at to "1 (root)". Alternatively, if you wanted the children of the current menu item then Starting at could be set to "+1 (children)".

  • Item, if possible radio (default On)

    This is the default filter mechanism whereby, if Starting at can only result in a single item (ie. it is the branch item itself, or an ancestor thereof) then only that item and its descendants are considered for filtering.

  • Level radio

    Changes the default filter mechanism such that if Starting at results in the selection of the branch item or one of its ancestors, then all siblings of that resultant item are also included in the secondary filtering process.

    Example : If Joe and Fred are siblings (ie. they have a common parent) and Joe is the selected branch item - with Starting at set to Joe - then the secondary filter would normally only consider Joe and its descendants. However, if Level was enabled instead of Item, then both Joe and Fred, and all their descendants, would be considered for filtering.

    Note that there is one exception, and that is that if Starting at results in a root-level item, then Allow all Root Items must be enabled in order to allow the other sibling root items to be added into the filter process.

  • Allow all Root Items checkbox

    In the right conditions - see Level above - this allows sibling root items to be considered for secondary filtering.

  • For Depth select

    This the number of levels of the menu structure that will be considered for inclusion in the final output (in complete ignorance of any subsequent Inclusions or Exclusions).

    The first level of output is the starting level, regardless of how that starting level is determined (see Starting at and Relative to Current Item options). So if you ask for a Depth of 1 level, you get just the starting level; if you ask for a Depth of 2, you get the starting level and the one below it.

  • Relative to Current Item checkbox

    By default, For Depth (above) is relative to the first item found, but this may be overridden to be relative to the current menu item if For Depth is not unlimited and the current menu item can found within the selected menu. If the current menu item is not within the selected menu then it falls back to being relative to the first item found.

    Please note that the current item must also be within the constraints set by the Starting at option. In other words, if current item is above the Starting at level in the menu structure then it will not be used to alter the determination of Depth.

Inclusions

These allow certain other items to be added to the output from the secondary filters.

The first 3 are only applicable to a Branch filter. Please note that they only come into effect when the Branch filter item is at or below the Starting at level, and do not include any items that would break the depth limit set in the Secondary Filter options.

  • Branch Ancestors select

    Include any ancestors (parent, grandparent, etc) of the items selected as the Branch filter. Ancestors can be set to go up to an absolute level, or to go up a certain number of levels relative to the Branch filter item.

  • ... with Siblings select

    In conjunction with Branch Ancestors, also include all siblings of those ancestors. As with Ancestors, their siblings can be set to go up to an absolute level, or to go up a certain number of levels relative to the Branch filter item. Note that while it is possibe to set a larger range for siblings than ancestors, the final output is limited by Branch Ancestors setting.

  • Branch Siblings checkbox

    Include any siblings of the item selected as the Branch filter (ie. any items at the same level and within the same branch as the Branch item).

  • All Root Items checkbox

    This is not restricted by other previous filter settings, and simply adds all the top level menu items into the mix.

Exclusions

  • Item Ids textbox

    This is a comma-separated list of the ids of menu items that you do not want to appear in the final output. The simplest way to get your list of ids is to use the "assist", and [un]check the red cross box at the left hand side of each depicted menu item. Alternatively, just type your list of ids into the box.

    If the id is appended with a '+', eg. '23+', then all the item's descendants will also be excluded.

    Example : If you wanted to show the entire "A" branch, with the sole exception of one grandchild of "A", say "ABC", then you could set Branch to "A", and Exclusions to the id of the "ABC" item.

    Example : If you have a menu with 4 root items - "A", "B", "C" & "D" - and you wanted to show all items, with descendants, for all bar the "C" branch, then you could set Level to "1 (root)" and Exclusions to, say, "12+", where "12" is the menu item id for "C" and the "+" indicates that all the descendants of "C" should also be excluded.

  • By Level select

    This allows an entire level of items to be excluded, optionally also excluding all levels either above or below it.

Qualifier

  • Current Item is in select

    This allows you to specify that there only be any output shown when/if the current menu item is one of the menu items selected for output at a particular stage in the filter proccessing.

    • "Menu" : the current menu item has to be somewhere within the selected menu.
    • "Primary Filter" : the current menu item has to be within the scope of the selected primary filter. So if you selected, say, a child of "A" as the Branch item, then if "A" was the current menu item there would be no output with this qualifier.
    • "Secondary Filter" : the current menu item has to be within the items as restricted by the secondary filters. So if you selected Branch as "A", with Starting at set to "+1 (children)", then if "A" was the current menu item there would be no output with this qualifier.
    • "Inclusions" : the current menu item has to be in within the items as set by the primary and secondary filters, and the inclusions.
    • "Final Output" : the current menu item has to be in the final output.

Fallbacks Section

Fallbacks get applied at the Secondary Filter stage, and their eligibility and application are therefore determined and governed by the other Secondary Filter settings.

There is one fallback, and it only comes into play (possibly) when a Branch filter is set as "Current Item", and the Starting at and For Depth settings are such that the output should start at or below the current item, and would normally include some of the current item's descendants (eg. Starting at "the Branch", For Depth "1 level" does not invoke the fallback). The fallback allows for the occasion when the current menu item does not have any immediate children, and provides the ability to then switch the following options:

  • Starting at select

    Enable the fallback, and change the Starting at from "+1 (children)" to either

    • "-1 (parent)" : the immediate parent of the current menu item.
    • "the Current Item" : the current menu item itself.
  • ...and Include its Siblings checkbox

    This will add in the siblings of the item selected above.

    Note : This only adds the siblings, not the siblings' descendants! However, if the Level radio (in Secondary Filter stage above) is set, then all the item's siblings and their descendants will automatically be included, and [un]setting this option will have no effect. Also note that if the fallback results in a root-level item being selected as the new Starting at item, then the inclusion of siblings outside the current branch depends on the setting of the Allow all Root Items checkbox.

  • For Depth select

    Override the current For Depth setting. Note that any depth value set here will be relative to the current item, regardless of the current setting of ...Relative to!

    As an example, this option may be useful in the following scenario : item A has 2 children, B and C; B is the current menu item but has no children, whereas C has loads of children/grandchildren. If you fallback to B's parent - A - with Unlimited depth set, then you will get A, B, C, and all C's dependents! You may well want to override depth to limit the output to, say, just A, B and C, by setting this fallback option to "1"? Or maybe A, B, C, and C's immediate children, by setting "2"?

Output Section

  • Hierarchical radio (default On)

    Output in the standard nested list format. The alternative is Flat.

  • Flat radio

    Output in a single list format, ignoring any parent-child relationship other than to maintain the same physical order as would be presented in a Hierarchical output (which is the alternative and default).

  • Set Title from checkboxes

    These allow you to set the Title option from a menu item, and, if brought into play, the Hide flag is ignored. Note that the item providing the Title only has to be within the selected menu; it does not have to be present in the final output! Note also that priority is the order presented (first found, first used).

    • Current Item : sets Title from the current menu item (if current menu item is in the selected menu).
    • ...or its Root : sets Title from the root menu item of the branch containing the current menu item (if current menu item is in the selected menu).
    • Branch : only applicable to a Branch filter, and sets Title from the Branch item.
    • ...or its Root : only applicable to a Branch filter, and sets Title from the branch's root menu item.
  • Change UL to OL checkboxes

    The standard for menus is to use UL (unordered list) elements to display the output. These settings give you the option to swap the ULs out for OLs (ordered lists).

    • Top Level : swap the outermost UL for an OL.
    • Sub-Levels : swap any nested (ie. not the outermost) ULs for an OLs.
  • Hide Widget if Empty checkbox

    If checked, the widget will not output any HTML unless it finds at least one menu item that matches the Filter settings.

    Please note that as of WordPress v3.6, this option becomes superfluous and will not be presented (the wp_nav_menu() function has been modified to automatically suppress all HTML output if there are no items to be displayed). The widget will retain the setting used on earlier WP versions (in case reversion from WP v3.6 might be required) but will not present the option for WP v3.6+.

Container Section

  • Element textbox (default "div")

    The menu list is usually wrapped in a "container" element, and this is the tag for that element. You may change it for another tag, or you may clear it out and the container will be completely removed. Please note that WordPress is set by default to only accept "div" or "nav", but that could be changed or extended by any theme or plugin.

  • Unique ID textbox

    This allows you to specify your own id (which should be unique) for the container.

  • Class textbox

    This allows you to add your own class to the container element.

Classes Section

  • Menu Class textbox (default "menu-widget")

    This is the class that will be applied to the list element that holds the entire menu.

  • Widget Class textbox

    This allows you to add your own class to the outermost element of the widget, the one that wraps the entire widget output.

  • Before the Link textbox

    Text or HTML that will be placed immediately before each menu item's link.

  • After the Link textbox

    Text or HTML that will be placed immediately after each menu item's link.

  • Before the Link Text textbox

    Text or HTML that will be placed immediately before each menu item's link text.

  • After the Link Text textbox

    Text or HTML that will be placed immediately after each menu item's link text.

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 above). 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 above).

allow_all_root

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

depth

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

depth_rel_current

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

include_root

switch, off by default, 1 to enable : Sets the widget's Include All Root Items option. See widget's All Root Items option, under Inclusions, Filters Section above.

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 above. (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 above. (only relevant to a Branch filter)

siblings

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

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 exlude 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 above, for an explanation of the respective settings.

fallback

string : There are 2 main options for fallback (ref. Fallbacks Section above)...

  • "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.

flat_output

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

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 above)...

  • "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 above.

ol_sub

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

container

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

container_id

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

container_class

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

menu_class

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

widget_class

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

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.

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/]

Requires: 3.6 or higher
Compatible up to: 3.9.2
Last Updated: 2014-7-30
Downloads: 65,619

Ratings

4 stars
4.7 out of 5 stars

Support

10 of 11 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