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}*

h2. Builder 1.6 Notation

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}
{menuitemwikimenu}
* [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}
{menuwikimenu}
{menubar}

Now, inh2. 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:

{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}

h3. 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.

h3. 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:

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

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.

h3. 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:

{code}
 {menuitem}[Home]{menuitem}
{code}

You can use the menulink macro as follows:

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

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].