Page History

h1. Changes to menus between Builder 1.6 and 2.0

*{excerpt}This document explains the changes made to menus between Builder 1.6 and Builder 2.0...{excerpt}*

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

{code}
* [Home]
* ----
* [Tutorials]
** [Working with menus]
** [Changes between 1.6 and 2.0|Changes to menus between Builder 1.6 and 2.0]
{code}

That notation 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|Changes to menus between Builder 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:

{menubar}
{menuitem}[Home]{menuitem}
{menuseparator}
{menu}[Tutorials]
{menuitem}[Working with menus]{menuitem}
{menuitem}[Changes between 1.6 and 2.0|Changes to menus between Builder 1.6 and 2.0]{menuitem}
{menu}
{menubar}

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

{code}
{menubar}
{wikimenu}
* [Home]
* ----
* [Tutorials]
** [Working with menus]
** [Changes between 1.6 and 2.0|Changes to menus between Builder 1.6 and 2.0]
{wikimenu}
{menubar}
{code}

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.

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:

{code}
{menubar}
 {menuitem}[Home]{menuitem}
 {menuseparator}
 {menu}[Tutorials]
  {menuitem}[Working with menus]{menuitem}
  {menuitem}[Changes between 1.6 and 2.0|Changes to menus between Builder 1.6 and 2.0]{menuitem}
 {menu}
{menubar}
{code}

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 [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).