Menu Changes Between Builder 1.x and 2.x

This document explains the changes made to menus and their notation between Builder 1.x and Builder 2.x...

Builder 1.6 Notation

In Builder 1.6 and earlier, menus were defined as simple unordered lists like the one shown below:

* [Home]
* ----
* [Tutorials]
** [Working with menus]
** [Changes between 1.6 and 2.0|Menu changes between Builder 1.x and 2.x]

As you can see, some of the links are broken. The notation above would produce a menu something like the following if placed on a normal page within your space:

• [Home]

• ---

• [Tutorials]
  • [Working with menus]
  • [Changes between 1.6 and 2.0]

And if placed in the "Custom pre-menu" or "Custom post-menu" sections of the Builder theme version 1.5-1.6 it would create a menubar at the top of the screen like this:

Builder 2.0+ Notation

In Builder 2.0 and above you can still use the simple unordered list notation, however it must be wrapped in the menubar macro and wikimenu macro as shown below:

{menubar}
{wikimenu}
* [Home]
* ----
* [Tutorials]
** [Working with menus]
** [Changes between 1.6 and 2.0|Menu changes between Builder 1.x and 2.x]
{wikimenu}
{menubar}

menubar and wikimenu

The menubar macro turns an unordered (bullet) list of links in to a functional menu. The wikimenu macro processes a normal Confluence wiki notation unordered list to ensure it's in the correct format for processing by the menubar macro.

The neat thing about this is that you can now put the menu anywhere - for example, you put it in a sidebar, the footer or even on a page in your space (as we have done in our example above), etc.

menuitem, menuseparator, menu, submenu, sub-submenu

While the wiki notation is often really easy to work with, there are some downsides - most notably when a user does not have access to the item you are linking to which results in a "dead" (non-clickable) menu item. As such, we highly recommend using the menu macro and menuitem macro to encapsulate your links like this:

{menubar}
 {menuitem}[Home]{menuitem}
 {menuseparator}
 {menu}[Tutorials]
  {menuitem}[Working with menus]{menuitem}
  {menuitem}[Changes between 1.6 and 2.0|Menu changes between Builder 1.x and 2.x]{menuitem}
 {menu}
{menubar}

Note: We've indented the items above to make it easier to see the hierarchical structure of the menu - this has no effect on the actual menu, so it's optional, but we highly recommend it as it makes your menu notation easier to work with.

The result:

The menuitem macro replaces the *'s in the wiki notation and to indent the list (create a submenu) the menu macro is used (and for subsequent indentation levels the submenu macro and sub-submenu macro are used).

The menuitem macro has a very useful feature - it will hide any dead links in your menus!

The menuseparator macro replaces the ---- used to create a divider in the menu. Should two menu separators be found next to each other (eg. because the menuitem macro has hidden inactive links between them) the surplus separator(s) will automatically be removed!

Likewise, if an entire menu or sub-menu is found to be empty, it will be removed.

menulink

The menulink macro is hugely powerful because it provides an easy way to link to all common places within Confluence.

For example, instead of using wiki notation to define the link to the home page like this:

 {menuitem}[Home]{menuitem}

You can use the menulink macro as follows:

 {menuitem}{menulink:home}Home Page{menulink}{menuitem}

The key benefit in this scenario is that it doesn't matter what the home page is called, or even if it's renamed at a later date, the menulink macro will still find it and link to it.

Another key benefit of the menulink macro is that it strictly adheres to Confluence permissions and user privileges. It provides a very reliable way of linking to Confluence features.

For more information, see menulink macro.

viewmenu and editmenu

Builder 2.x also introduced the viewmenu macro and editmenu macro - these allow you to quickly insert the default View and Edit menus anywhere within your menu structure.

Furthermore, you can now also edit the View and Edit menus to completely customise them or separate items out in to different menus, etc.