This plugin was developed of necessity. We wanted a way to provide a pictorial menu experience for users who had had limited education opportunities.
An example of the plugin shortcode:
The plugin provides
-
- a way of specifying which menu to traverse
- three ways of selecting which menu items to include
- five ways to format the results
- a way to control how deep into the tree it searches
Selecting which menu items to include
selection=ancestors
Only the items between the root of the menu and the current page are selected. This allows you to provide the user with a way out of the maze.
selection=offspring
Only child menu items of the current page (and their children and their children’s children etc.) are selected. This provides a way to produce a kind of site map of where to go next
selection=siblings
Only menu items that are child items of he same parent as the current item are selected. The current item itself is not included.
selection=root
The entire menu tree is selected. Useful for things like full site maps.
selection=notinmenu
Only pages that are not mentioned in the named menu are listed. This does not mean they are complete orphans however, as they may appear in a different menu or be hyperlinked from within a page.
Control how deep into the tree
level=0
Whatever the selection selected is kept intact
level=1
Only the immediate children of the selection are included. So for example,
selection=root format=links level=1
Would just give you a list of the top level pages. This option is most useful when you use format=buttons because the buttons are laid out across the page and adding extra layers just creates a mess.
ways to format the results
format=buttons
This option takes each item in the selection and creates a small graphical button from a supplied image. The url of the button is placed in the description field of the menu item. Typically the image should be 200px x 200px and is usually saved in the media library. The easiest way is to have two tabs open in your browser, one on the media library and one on the menu editor. Other sizes are OK but the image must have a 1:1 aspect ratio.
In the media library, select the image you want to use. Click the Copy URL button.
Then switch to the other tab and paste the URL into menu item’s the description field. (You may need to open ‘Screen Options’ and ensure the “Description’ option is checked in order to see the description field.
format=json properties=”source:item source:item …”
This option has an extra option ‘properties’. If you do not specify it all of the properties of every menu item are listed. However, you can specify which properties to include as a space separated list (remember to put the whole list in quotes!) source is either ‘page’ or ‘menu’ (menu is default) and item is the property name in that object.
The output is in JSON format. This can be useful if you want to use the menu elsewhere, or simply want to examine what is going on if something is not working as you expected.
fomat=full_monty
This option retrieves and displays the content of all of the pages of the selected items. Use this with selection=root to get a proof reading copy of the site.
format=links properties=”source:item source:item …”
This option produces an indented list of titles of every page in the menu that can be clicked to go to that page. properties is optional – see below.
Using
selection=root format=links
is a convenient way to produce a site map, or you can use
selection=offspring format=links
to produce a sitemap just of the offspring of the current page.
You can also add selected property values. These are not shown unless selected using the properties parameter. You specify which properties to include as a space separated list (remember to put the whole list in quotes!) source is either ‘page’ or ‘menu’ (menu is default) and item is the property name in that object.
format=non_links
This produces the same output as format=links but the titles are not clickable. This is useful if you want a printed copy of the site map for example, where the URLs would simply clutter the page.
format=crumbs
Formats the selected list as a set of breadcrumbs. It is intended to be used with selection=ancestors. It doesn’t make sense with offspring, so that combination is not allowed.
format=text_crumbs
Formats the selected list as a set of breadcrumbs. It is intended to be used with selection=ancestors. It doesn’t make sense with offspring, so that combination is not allowed. Text only with no decoration.
format=text
Formats the items as a simple string of clickable text titles. The parameter delimiter can be used to specify text to go between items.
delimiter=<delimiter>
default is semicolon (;)
format=selector options=”name:title name:title …”
This format is similar to ‘links’ except thhat in addition it provides one or more radio buttons which are specified in the ‘options’ parameter. There is also a save button. The selection is saved in the current users space in the database. This can only be used with a logged in user. The selection is stored as <name> whilst <title> is what appears next to the radio button. This format also requires the default and prefix parameters
default=name
This specifies which radio button is selected prior to the user saving the page for the first time
prefix=app_name
The prefix is used to differentiate this set of values from some other set also using the format=selector option.
Other parameters
id=<id|slug>
By default, the current page is the reference point for all selections. However you can specify a different page by giving its id or its slug in the id= parameter
showname=true|false
If true, the name of the combination of selection;format;level from ‘validation.txt’ will preced the menu item result. This can be useful if the shortcode is used in a widget.