-
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
-
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 ATTRIBUTES
The shortcode is
[cmwizard]
.
Most of the attributes reflect the options available to the widget, but some have been simplified for easier use in the shortcode format.
If there are no menu items as a result of the filtering, 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.
Note that as long as you are
not
using the
widget=N
attribute, then you don’t need to save the widget itself :
just copy-paste the shortcode when you are happy with it.
widget
integer
:
!NEW!
from v3.1.5
, the shortcode will accept a
widget=N
attribute which will load an
existing widget instance.
The shortcode – resembling
[cmwizard widget=N/]
, where
N
is an integer – is provided at the base
of each widget, below the widget’s “equivalent” shortcode.
It will look for the instance in all active sidebars,
and
the Inactive Widgets area.
You can prevent inspection of the Inactive Widgets area by adding an
inactive=0
attribute.
It will
not
look in any other
Inactive Sidebar…
area unless you specifically tell it to do so by
adding an
orphaned=1
attribute.
Using this attribute reduces the shortcode length, and may cut down on maintenance where
you have the same shortcode in a number of places … as long as you are prepared to keep the widget instance (even if it’s in the
Inactive Widgets area). You can override the widget instance’s settings by supplying any of the other standard shortcode attributes.
Note that you can’t use this attribute as part of an Alternative setting (it is simply ignored).
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 that 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 :
-
include_level="2"
: include all items at level 2
-
include_level="2-"
: include all level 1
and
level 2 items
-
include_level="2+"
: 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=1
is still accepted, even
though now deprecated, and is equivalent to setting
include_level="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 exclude all subsequent (lower) or prior (higher)
levels respectively. See the examples for
include_level
above.
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
: This enables the widget’s
If Current Item has no children
fallback (ref.
Fallbacks Section
)…
-
“parent”
: Sets the widget’s Fallback option to “Start at : -1 (parent)”
-
“current”
: Sets the widget’s Fallback option to “Start at : the Current Item”
-
“quit”
: Sets the widget’s Fallback option to “No output!”
The first two 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
fallback="current,+siblings,1"
is the same as
fallback="current,1,+siblings"
,
and
fallback="2,parent"
is the same as
fallback="parent,2"
, etc.
fallback_ci_parent
switch, off by default, 1 to enable
: See widget’s
If no Current Item can be found
entry in the
Fallbacks Section
.
fallback_ci_lifo
switch, off by default, 1 to enable
: See widget’s
If more than 1 possible Current Item
entry 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 a “current” and/or a “branch” item (comma-separated), corresponding to the 2 selects in the widget’s
Set Title from
options,
under
Output Section
.
-
“current”
: take the title from the Current Item
-
“currentN”
: take the title from an ancestor of the Current Item, where
N
is the literal level of the ancestor, eg. “current2” would be the Current Item’s ancestor that sits at level 2
-
“current-N”
: take the title from an ancestor of the Current Item, where
N
is the number of levels above the current item, eg. “current-2” would be the Current Item’s grand-parent
-
“current-root”
: equivalent to
“current1”
; takes the title from the Current Item’s root-level ancestor
-
“current-parent”
: equivalent to
“current-1”
; takes the title from the Current Item’s parent
All the above are also available for the Branch Item, eg.
“branch”
,
“branch1”
,
“branch-2”
, etc.
As an example,
title_from="current-1,branch"
will take the title from either the Current Item’s parent – if
there is a Current Item found in the menu – or the Primary Filter’s Branch setting if there isn’t a Current
Item available.
title_linked
switch, off by default, 1 to enable
: Makes the title into a link if the title comes from one of the
title_from
options.
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 attribute 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 attribute that is taken any
notice of is
title
, which will be output (if supplied) as an H3 in front of the list. Example :
[cmwizard findme=1 title="Posts containing a CMW shortcode..."/]
Note that the information provided by this utility is also available from any widget’s “assist”.
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" alternative="current,menu"]title="Nearest and Dearest!" branch=current depth=2 siblings=1[/cmwizard]
|
