Well, I have to admit to being fairly hesitant about releasing this update, because I really don’t want to tick people off and drive them away from the plugin. However, the time has come to bite the bullet and just go for it. If the new version of the plugin no longer does what you need it to, then I can only apologise, but I’m afraid some changes were necessary in order to advance.
I have outlined the main differences below … but first, a quick note : The whole point of the plugin is to make maintenance easier by utilising an existing custom menu instead of having to create partial duplicates. If applying (or trying to apply) the Custom Menu Wizard plugin to your menu turns out to be overly complicated, then it defeats the object of the exercise and you might want to consider using a different plugin, or maybe creating a new custom menu to better fit your particular requirements.
Important : None of your existing CMW widgets/shortcodes will break if you upgrade!
Although it has been completely rewritten, I have given version 3 the capability of handling the version 2 widgets and shortcodes, but obviously the new features in version 3 will not be available.
No more “Children Of”
Previously, by specifying the parent item, you selected a (possibly empty) set of child items that you wanted to build the output from. Now, you select a single menu item as the Branch, and use that as the base for determining what the final output should be. Note that the ability to select Current Root Item, or Current Parent Item, has been removed from this option : that functionality is now provided by the Starting At option in the Secondary Filters (see below).
“Starting Level” becomes “Starting At”
What used to be Starting Level is now Starting At, and it has changed from a simple list of available to levels to a more comprehensive selector, which adds the ability to specify a level relative to the selected Branch item. So where you might have previously started out by setting Children of Current Item, you would now set Branch = Current Item, Starting at +1 (children).
There are also a couple of extra switches available for the new Starting At option :
- Selecting the “Level” radio option will force what would have been a single item (eg. a Branch’s parent) to be considered as a level, ie. include not just the item but also all its siblings, and thereby all their relevant descendants.
- As a check on the above, selection of eligible siblings is normally restricted to descendants of the selected Branch’s root item (so you’re not allowed to outside of the main root branch). Enabling the Allow all Root Items option will waive that restriction, if the single item in question happens to be the Branch root item.
“Items” with descendants
Items, as a Primary Filter, can be specified as being inclusive of all their descendants, which saves having to specify each individual descendant item.
Inclusions have changed
Inclusions have been moved from the Output section to the Filters section. In terms of processing order, they come after the Secondary Filters and before the Exclusions.
The Include Parent (optionally with Siblings) checkboxes have been replaced with a single checkbox for including Branch Siblings (of the current Branch item). This is because the change of focus from the children to (what used to be) the parent has made the Include Parent option redundant, and the equivalent of Include Parent Siblings is now Include Branch Siblings.
Not only has Include Ancestors changed from a checkbox to a select, but it has also gained an optional “with Siblings” ability. Both these options now offer the opportunity to pick either an absolute level to go back up to, or a relative number of levels to go back from the Branch item by. Basically this means that you can now specify how many levels of ancestors you want, and how many of those ancestors you also want the siblings of.
There is a new Include All Root Items, which is not restricted to a Branch filter. Self explanatory : it simply adds all the root-level menu items into the mix.
As a result of these changes, the corresponding shortcode attributes have also had to be modified. The previous attribute was “include”, which could be set with a comma/space/hyphen-separated list of values – “parent” and/or “siblings”, plus “ancestors” – where “siblings” implied “parent”. For the new version, the “include” attribute is no longer valid, and :
- include=”parent” has no equivalent
- the equivalent of include=”siblings” is siblings=1 (an on-off switch)
- the direct equivalent of include=”ancestors” is ancestors=1, but ancestors accepts a positive or negative integer depending on how far back you want you ancestors to go
- the new facility to also include Siblings of ancestors is specified with ancestor_siblings=N, when N is a positive or negative integer (note that for the siblings of an ancestor to be included, the ancestor itself must also be included!)
- the new facility to include All Root Items is specified with include_root=1 (an on/off switch)
New Exclusions option
The ability the specify Exclusions – either by Id or by level – has been added. And, like Items, Exclusions by Id can be specified as inclusive of all descendants.
“Must Contain Current Item” has moved and expanded
This has been moved from the Output section : it’s now “Current Item is in”, in the Filters Section under Qualifier. It has also been enhanced so that the required presence of the current menu item can be checked at different stages through the filter process, whereas previously it was only possible to require that the current item be in the final output.
For example, you can now specify that the current item is only required to be present in the Primary Filter, and therefore need not be present in the final output. It’s useful for, say, when you don’t want the Branch’s root item to be in the final output but you still want there to be some output when the root item is the current menu item.
The Fallbacks have changed
This is the one area that might throw up some edge cases that are no longer possible, for which I can only apologise.
The “No Ancestor” fallback has gone : This was a what-if condition based on looking for the distinct root or parent item of the current menu item, but the current menu item was actually at root-level so its root or parent item was deemed not to exist. Now, a current menu item that is at root-level is deemed to be its own root and parent item (ie. current item == root item == parent item), so the fallback becomes superfluous.
The “No Children” fallback has changed slightly, but it should still do what the previous versions did (hopefully!).
More “Title from” options
The 2 original “Title from” options have each been extended with an additional option to set the title from the associated root item.
The shortcode for version 3 has changed! It is now [cmwizard] instead of [custom_menu_wizard]. The reason I had to do this was to able to differentiate between the processing and allowed options for version 3, versus those for previous versions. If you continue to use [custom_menu_wizard] it will be processed as version 2, regardless of what options you attach to it! I would suggest that you use a widget instance to build your shortcode, since that will always produce the correct output for the plugin version.
Shortcode’s “title_tag” attribute
The shortcode has an option that is not applicable to the widget : the “title_tag” attribute provides the ability to change the HTML tag used for the title, from the default H2 to some other tag (an H3, for example). This could previously only be done with a coded filter (it still can, but this is easier!).
Automatic upgrade of widgets and shortcodes
Well, I started out with this intention, but to be perfectly honest I got myself into such a mess of code that I gave up! There are so many combinations of options that I eventually came to the conclusion that it just wasn’t practical … especially once it became apparent that comprehensive conversion required analysis of the menu structure.
The very last thing I want to do is break anyone’s site, so I have made the decision to leave the upgrade as a manual process. I am aware that this means that some people may never get round to it, but at least the backward compatibility ensures that everything still works (and is still modifiable). If you want to take advantage of version 3’s features you will need to create new widgets, and replace existing shortcodes, but you can run the old and new assists side-by-side for comparison, to check that the new instance behaves like the old one. With widgets, I would highly recommend that you use the Inactive Widgets area, and move your old widget instance there until you are sure that you have configured its replacement exactly how you want it.
Given the decision not to automatically upgrade widget instances or shortcodes, I then realised that finding, or remembering, exactly where I had used a CMW shortcode was proving to be a bit of a pain … so I have added a search facility into the new “assist”.
At the bottom right of the “assist” window there is a button with square brackets on it : click it, and it will display a list of links to all posts that contain a CMW shortcode, either in content or in a custom field. The links open the post in a new tab, from where you can then go into edit them if you wish. The list also indicates which type of shortcode has been found in each post, ie. either the new [cmwizard] version, or the old [custom_menu_wizard] version. To remove the list, simply click the button again.
Please note that if you have placed a CMW shortcode into places like text widgets, or textareas provided by your theme or other external plugin, then they will not be listed. I’m afraid you will have to find those yourself.
Here’s a (very) short list of some of the configuration differences between version 2 and version 3 setups (where an option is not mentioned then assume that it is left at its default):
All descendants of X
Children of X => Branch X, Starting at +1 (children)
Just immediate descendants of X
Children of X, For Depth 1 => Branch X, Starting at +1 (children), For Depth 1
X and all descendants of X
Children of X, Include Parent => Branch X
X and all descendants of X, plus all siblings of X
Children of X, Include Parent (with Siblings) => Branch X, Include Branch Siblings
X and all descendants of X, plus all siblings and ancestors of X
Children of X, Include Parent (with Siblings) and Ancestors => Branch X, Include Branch Ancestors to level 1 (root) and Branch Siblings
Current Item and its siblings, plus all their descendants
Children of Current Parent Item => Branch Current Item, Starting at the Branch Level (where Level is the new radio button)
The entire root branch containing Current Item
Children of Current Root Item, Include Parent, and a Fallback of Switch to Current Item => Branch Current Item, Starting at 1 (root)
The root branch containing Current Item, but excluding the root item
Children of Current Root Item, and a Fallback of Switch to Current Item => Branch Current Item, Starting at 1 (root), Exclude By Level 1
The root branch containing Current Item, plus all other root items (without their descendants)
Children of Current Root Item, Include Parent (with Siblings), and a Fallback of Switch to Current Item => Branch Current Item, Starting at 1 (root), Include All Root Items
All descendants of X, taking title from X
Children of X, Title from Parent => Branch X, Starting at +1 (children), Title from Branch