This version of the Custom Menu Wizard Plugin introduces a completely new capability : the Alternative.
What Is The “Alternative”?
Basically it provides a mechanism for enabling one widget instance to produce output in 2 different scenarios, those scenarios being differentiated by the absence/presence of either a current item or some resultant output.
Let’s take an example : say you have a requirement that a menu shows the top 2 levels of items … unless a current menu item is found, in which case you want that item and all its dependents to be displayed. This was not previously possible because having set Level 1 as the Primary Filter you could not then conditionally change the Primary Filter based, say, on the presence of a current item. Now you can.
How Do I Use It?
Well, it’s relatively straightforward (I hope). You simply need to define the Condition on which the Alternative kicks in – using the 2 selects – and (optionally) provide a shortcode equivalent of the alternative settings you wish to use.
The widget form has a new section at the bottom, labelled Alternative :
- Determine what your 2 contrasting scenarios are : they are quite likely to be differentiated by the need for a different Primary Filter in each. As an example, if your need is for something like “show just the root level items unless the menu contains the current item, in which case show the current item and its dependents” then you have 2 scenarios : scenario A is the root level items; scenario B is Current Item branch.
- Pick the simplest scenario (my advice) and configure the widget for it. For this example it could be either, so I will pick scenario A : Level=1 (the default) and Depth=1. Leave the Alternative section alone (for now).
- Now copy the shortcode equivalent and paste it into the textarea in the Alternative section.
- Reconfigure the widget for the other scenario. For this example, that would mean resetting Depth to unlimited and setting Branch to Current Item, as required for scenario B.
- In the Alternative section, configure the Condition for switching from scenario B (currently configured) to scenario A (as represented by the shortcode in the textarea). For this example it would be the absence of a current item anywhere in the menu, ie. Current Item is NOT in menu.
- Save and you’re done!
The choice of which scenario to configure as the Alternative is up to you. Personally I would pick the simplest, which, in terms of Primary Filters, often means Level over Branch, and Branch over Items … but it’s your choice.
I would also suggest that – even though it’s not strictly necessary – you always put the entire shortcode (square brackets and all) into the widget’s textarea : (a) it’s simpler and you’re less likely to miss something out, and (b) it’s more informative for when you look back at the widget settings in 6 months time.
Please note that I have stated that the provision of a shortcode is optional. If you set up the Condition, but you don’t provide a shortcode, then the widget will switch to the defaults for any new widget – which is to show the entire menu (Level = 1, for Depth unlimited).
How Do I Give A Shortcode An Alternative?
Basically you need to provide the Condition – in the form of an extra parameter, alternative – and the new settings, placed as content between the shortcode’s opening and closing tags.
As always, the simplest way to construct any CMW shortcode is to use a widget instance (active or not), and the Assist will help you test it.
This takes 2 values, separated by a comma or space, which together constitute the Condition that has to be met for the Alternative to switch in:
- What to test for : one of
- “current” = Current Item is in…
- “no-current” = Current Item is NOT in…
- “no-output” = No Output from…
- When to test : one of
- “menu” = before the filters
- “primary” = having run Primary Filter
- “secondary” = having run Secondary Filters
- “inclusions” = having run Inclusions
- “output” = having run everything
alternative="current,primary" means the Condition that must be met is that the Current Item is present in the items selected as a result of running the Primary Filter.
Similarly, alternative="no-current,inclusions" means that the Condition is that the items selected having run the Inclusions processing do NOT contain a Current Item.
Generally, the earlier (in the processing) a switch condition can be detected, the better, but how you set the Condition is very much dependent on the other options you might set for the widget.
The New Settings
The “normal” CMW shortcode uses a self-terminating tag, eg. [cmwizard menu=N/] .
When providing an Alternative for a shortcode, use a closing tag and place the alternative settings between the opening and closing tags, eg.
[cmwizard menu=N branch="current" alternative="no-current,menu"]depth=1[/cmwizard]
Important : The content placed between the tags must not include the square brackets that would normally enclose a shortcode! In fact, you can also omit the cmwizard tag and the menu=N parameter, as I have done above, although it doesn’t matter if you do put them in. However, putting the square brackets in will definitely cause problems (this is a WordPress parsing restriction).
One point to note is that this [cmwizard menu=N branch="current" alternative="no-current,menu"/] is also valid : it simply means that the Alternative settings are the default widget configuration, ie. Level 1, for unlimited Depth.
You can’t switch menus. For instance, you can’t set the widget up to use Main Menu, then switch to My Other Menu if the current item is not in Main Menu.
You can’t nest Alternatives. Any instance of CMW will only ever switch to one Alternative; it will not allow that Alternative to then switch to another Alternative!
Certain settings in an Alternative configuration will have no effect – such as any Container or Links option, the Menu Class, and the Top Level UL/OL option. This is because the switch-to-alternative decision is made within the custom Walker called by WordPress’s wp_nav_menu() function, by which time some settings are already cast in stone.
Does The Assist Work With Alternatives?
Yes. When the Assist comes across a situation where it should switch to a configured Alternative it will attempt to do so, and it will put up a message (in green) saying that the Alternative settings are being used. If, for some reason, the Alternative settings cannot be used – because they can’t be parsed, for example – then that message will be in red and the Assist will not switch over.
Please note that the message is quite important : If you find that all of sudden you can’t use the tick/cross buttons, it may be because you have switched to the Alternative settings. When the Assist switches to Alternative settings, all the visuals – including the ticks and crosses – now reflect the new settings. However, since you cannot use the Assist to directly modify the Alternative option’s value in the textarea, the ticks and crosses are disabled (and slightly opaqued) when Alternative settings are being used. This avoids any confusion over what might or might not be being changed. If you need to change the Alternative configuration, either do it manually in the widget’s textarea box, or bring up another widget instance, play with it there, then copy-paste the resultant shortcode back into the current widget’s textarea.
How Can I Tell When The Alternative Is Active?
Well, aside from the fact the output will probably be slightly different – although that’s not guaranteed, depending on the page you’re on and how you have configured CMW – there will be an extra class, cmw-invoked-alternative, added to the main list element (UL or OL) that is used to display the actual menu. Otherwise, the switch should be entirely transparent.