Oct 312014

I needed to get a list of all the tags used by posts in a specific category, linking them through to the appropriate archive page, and I just couldn’t find anything that would do it for me. So I ended up writing a little shortcode which I could just stick into a text widget and feed with the category I wanted…

Example usage : [categorytags cat=”a-category-slug”/]

It will take either a slug or an id (I find using slugs a lot easier!).

You can stick the code straight into a theme’s functions.php, or you can turn it into a plugin. And it’s easy enough to change the output to produce, say, a list instead of paragraphs.

The one thing this code does not do is any counting, so if you want a tag cloud effect then you’re going to need to enhance it yourself (or find another ready-made plugin).


 Posted by at 12:02 am
Oct 032014

This version of the Custom Menu Wizard Plugin introduces a completely new capability : the Alternative.

Plugin : Custom Menu Wizard, and its Change Log.

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 :

  1. 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.
  2. 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).
  3. Now copy the shortcode equivalent and paste it into the textarea in the Alternative section.
  4. 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.
  5. 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.
  6. 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.

The Condition

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:

  1. What to test for : one of
    • “current” = Current Item is in…
    • “no-current” = Current Item is NOT in…
    • “no-output” = No Output from…
  2. 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

So,  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.

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.

Restrictions, Limitations

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.

Jun 162014

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.

Plugin : Custom Menu Wizard, and its Change Log.

Backward compatibility

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.

New Shortcode

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.

Upgrade assistance

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


Feb 142014

Have you ever had one of those annoying editors you consistently pastes pre-formatted stuff – like HTML lifted from a web page, or text from Word – straight into the visual editor, without using the paste-as-text button? Well I have, and I got fed up with having to sort out the messed up HTML. I decided that the best way to deal with it was to change the paste-as-text button back to a toggle, so I added the following snippet to my child theme’s functions.php

Basically, all this does is remove the dialogue box that would normally pop up when the button was clicked, and then turns the paste-as-text button into a  “sticky” toggle (ie. you have to click it toggle it on/off), with its initial state being On.


For TinyMCE4 (as of WordPress 3.9) the code has changed…


 Posted by at 3:56 pm
Jul 292013

I’ve been working on a responsive website for a client, and I have come across a situation where I needed to get a WordPress Gallery to resize itself according to the space made available to it by the containing element. If I leave it up to the Media Manager, I can only set a specific number of columns – 1 thru 9 – and what I really wanted was to be able to set zero columns so that all the items just floated left and filled the available space as best they could (no BR elements getting in the way!). Now, I could easily do this by editing the HTML and manually setting the columns attribute, but I am handing this over to the client and I don’t particularly want them to have to edit HTML : they should really be able to do this from the UI interface (Media Manager, when creating/editing the Gallery), but for some unknown reason WP doesn’t make zero columns available as an option!? So I wrote a fix for it…

option for zero columns appended to selectIf you want to use the above code, feel free.

If you have a child theme, simply add the code to your functions.php (you can take out the comments section at the top).

Alternatively, you can install it as plugin (leave the comments section in) :

  1. save the above code to a file called (for example) media-gallery-zero-columns.php
  2. create a folder called (for example) media-gallery-zero-columns and place the new file in it
  3. upload the media-gallery-zero-columns folder to your WP’s wp-content/plugins/ folder
  4. in the admin backend of your WP site : go to Plugins, find the new Media Gallery Zero Columns plugin, and Activate it!

Note that it is only relevant to WP v3.5+ (the Media Manager being introduced at v3.5.0) and will also work for v3.6. It’s set to be nigh-on the last action taken, and it includes a safeguard against adding the zero-columns option if there’s already one there.

A final word of warning : if any other plugin modifies the Javascript wp.media.view.Settings.Gallery function then it is highly likely (read “certain”) to conflict with this code, and one or the other will fail! I don’t know of any other plugin that changes this function, but then the number of plugins I know nothing about is 99.99% of them!

Edit, 20th Feb 2014

It has just come to my attention that, although zero columns is a perfectly valid setting (according to the Gallery Shortcode documentation), some themes seem to forget that it can be set – the Twenty Fourteen theme being an example. Therefore, if you are using zero columns, you may also need to add some css to your stylesheet so as not to break your layout!

WordPress adds a class – gallery-columns-N – to the div.gallery container, where N is the number of columns set; for zero columns, that class will therefore be gallery-columns-0. If your theme is at all responsive, you may well find that there are styles defined for certain numbers of columns that set maximum widths for the contained images and/or gallery-items that wrap them, and if there is no default, or no specific rule for gallery-columns-0, then you might need to add one. This is just an example (it’s very much theme-dependent!) …

 Edit, 9th June 2014

Hmm … it has been brought to my attention that the closing SCRIPT tag within the function had an extraneous single quote and semi-colon following it (before switching back into PHP mode) : I have now corrected the code sample … my apologies for the oversight.

Edit, 2nd November 2104

The script has been corrected so that it now works with WordPress v3.9+ & v4.0. Apologies for the oversight, and thanks to Marton for pointing it out.

 Posted by at 1:27 pm
Jan 162013
  • fixed for jQuery v1.9, which no longer supports $.browser : I used $.browser to set the image loader to native javascript for browsers other than Safari and Opera, but for jQuery v1.9+ it will now use the jQuery loader by default for all browsers. This can still be overridden from the options
  • added a permanentLabels switch option (off by default) which keeps the labels (if enabled) on permanent display
Aug 092012

Very basic example of how it’s possible to manipulate menu items by destroying the Dock (requires v2.0+), changing it, and then re-initialising it. I’ve used a list, but the same principles apply for non-lists. Note that care needs to be taken with styling in order to get seamless transition between docked and undocked!

Jun 252012

Can CSS do what jqDock does?

Short answer : No.

CSS3 provides for some animation techniques that were previously the exclusive domain of Javascript. However, browser support for these new techniques is varied and incomplete, and legacy support in older browser versions is obviously compromised. As an example, let’s take a look at the CSS3 transition style, since that is the one that is most likely to be able to replicate what jqDock provides…

The transition style is currently supported (ie. at the time of writing) by the latest versions of Firefox, Chrome, Safari and Opera; it is not supported by IE9. So, if you want cross-browser standardisation then it’s game over right there.

Of course, there are ways around this, such as using a polyfill to compensate for IE. But then you’ve forsaken pure CSS and you’re merely substituting one piece of Javascript for another.

Let’s assume that IE can now handle the transition style (IE10?), so we’re now on a level playing field as far as latest-version browsers are concerned : How can you guarantee that all your site visitors are going to be using these latest versions? You can’t. So we’re back once again to the question of cross-browser standardisation.

Let’s now assume that you’re happy to have a non-animated fallback for any browser that can’t handle transitions

These examples have no Javascript acting on them at all; it’s pure CSS.

First off, I’m sorry if you can’t see any animation when hovering over the images but I’ve already explained why that might be the case.

With the CSS solution there is no sense of proximity, or mouse position within an element. This means that hovering over an image will only change the size of that specific image; none of its neighbours will be affected. Whether this is the effect you want for your dock is a decision only you can take, however it does have one major advantage : you always know the maximum dimensions of the dock. Also, designating an active item, ie. one that is initially expanded, and returns to expanded when the cursor moves off the dock, is perfectly feasible with the pure CSS solution, whereas with jqDock it is problematic.

One possible limitation with CSS transitions driven by cursor position (ie. using :hover state) is that they are not interruptable. You can’t stop a transition part way through (without using javascript) because the :hover state is either on or off, and in both cases you have definitive targets (the pre-defined expanded or contracted dimensions of the relevant image). Obviously, if you don’t need jqDock’s ability to freeze a dock then it’s not a problem.

Styling in general is much the same between CSS and jqDock : you can put borders and backgrounds on just about anything, and you can always add elements to the CSS solution if need be. If you don’t have specific label structures (like extra SPAN elements) within your anchors, CSS can create labels from anchor titles (for example). If that doesn’t provide enough of a base for your desired label styling then you may have to put dedicated label structures inside the anchors, particularly if you want to center labels that have background or border styling.

If you can put 2 images into your anchor then getting the CSS to swap them in and out on hover is no problem, so that solves any small-versus-large image quality problem.


If you are willing to sacrifice proximity expansion, and you have no need to suspend or interrupt any animation, then pure CSS can provide a very reasonable alternative to jqDock.

But, unless you don’t care about Internet Explorer, and non-current versions of some other browsers, you are going to need javascript of some sort to make it work consistently across browsers!