Page History

h1. Anatomy ofCreating Menus

*{excerpt}This tutorial explains thehow basicto structurecreate of menus andin howTheme to create themBuilder 2.x...{excerpt}*

h2. Custom MenusOverview

TheMenus customare menuscreated are constructedby using simpleone aor numbermore of[Builder utilityMenu macrosMacros]. whichAn assistexample inof thea creationvery of dynamic menus. Itbasic menu is also possible to create menus using unordered lists.

h3. Buttons on the Menu Bar

The structure of a menus is defined using a \{menuitem} macro containing a link

Here's a quick example:

{noformat}
{menuitem}Home{menuitem}
{menuitem}Builder{menuitem}
{noformat}

If you put that notation in to a page, it would look like this:

{menuitem}Home{menuitem}
{menuitem}Builder{menuitem}

You will notice that nothing is displayed, this is because if a menuitem does not contain a link, it is ignored and removed from the menu. You can make these buttons appear by turning them in to links:

{noformat}
{menuitem}[Home]{menuitem}
{menuitem}[Builder]{menuitemshown below:

{noformat}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Biulder]
  {menuitem}[Builder 1.x]{menuitem}
  {menuitem}[Builder 2.x]{menuitem}
 {menu}  
 {viewmenu}
{menubar}
{noformat}

Which results in:

{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Biulder]
  {menuitem}[Builder 1.x]{menuitem}
  {menuitem}[Builder 2.x]{menuitem}
 {menu}  
 {viewmenu}
{menubar}

This notation can be used within [theme panels|Panel Classes and IDs] and also within wiki pages.

Note: Menus will only work in spaces or areas of the site that have been themed with the Theme Builder plugin (as it includes the necessary JavaScript and CSS files that are required by the menus).

h2. The Menu Bar

To define the top-level links on the menu bar, the following notation should be used:

{noforamt}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuitem}[Builder 1.x]{menuitem}
 {menuitem}[Builder 2.x]{menuitem}
{menubar}
{noformat}

Which results in:

{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuitem}[HomeBuilder 1.x]{menuitem}
 {menuitem}[Builder 2.x]{menuitem}
{menubar}

It should be noted that you can use any type of [link|Links] and also have a different on-screen caption and tooltip if desired, for example:

{noformat}
{menuitem}[Start|Home|Our homepage]{menuitem}
{menuitem}[Adaptavist|http://adaptavist.com|Our website]{menuitemYou'll notice that we've used the [menulink macro] to create the link to the home page. This macro allows you to reliably link to all key locations and features within Confluence and a range of third party add-ons. By linking to the home page as shown above, the link will always work regardless of what the home page is called or even if it's renamed at a later date.

h2. Pop-Up Menus

To add pop-up menus to the menu bar links, use the [menu macro]:

{noforamt}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Builder]
  {menuitem}[Builder 1.x]{menuitem}
  {menuitem}[Builder 2.x]{menuitem}
 {menu}
{menubar}
{noformat}

Which wouldresults givein:

{menubar}
 {menuitem}[Start|Home|Our homepage]{menuitem}
{menuitem}[Adaptavist|http://adaptavist.com|Our website}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Builder]
  {menuitem}[Builder 1.x]{menuitem}

When a linked button on{menuitem}[Builder 2.x]{menuitem}
 {menu}
{menubar}

In the menuexample bar is clicked,above, when you will be taken tohover the locationmouse defined by the link.

h3. Pop-Up Menus

As over "Builder" you'll see froma thepop-up menu barcontaining buttonstwo atitems. theYou topcan ofalso thisclick page, most of them display a pop-up menu whenthe "Builder" link to go to the mousepage moves over them. To do this, simply encase the menu items that you want to move from the menu bar to the pop-up menu in a menu macro:

{noformat}
{menuitem}[Home]{menuitem}
{menu}[Builder]called "Builder".

The item that displays the pop-up menu ("Builder" in the example above) does not necessarily need to be an active link, for example you could use:

{noforamt}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}Builder Versions
  {menuitem}[CSS Custom StylesBuilder 1.x]{menuitem}
  {menuitem}[InstallingBuilder Builder2.x]{menuitem}
  {menuitem}[Menus]{menuitem}menu}
{menumenubar}
{noformat}

If you put that notation in to a page, it would look like this:

{menuitem}[Home]Which results in:

{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Builder] Versions
  {menuitem}[CSS Custom StylesBuilder 1.x]{menuitem}
  {menuitem}[InstallingBuilder Builder2.x]{menuitem}
  {menuitemmenu}[Menus]
{menuitemmenubar}
{menu}
When you hover over "Builder Versions" the pop-up menu will still be displayed.

h3. Sub-Menus

JustTo asadd yousub-menus increaseto theitems indentationon toa move items frompop-up menu, use the [sub-menu bar macro]. For example, to theadd a popsub-up menu, you can increase it still further to create sub-menusmenu to to the Builder 2.x item, the following notation is used:

{noformat}
{menubar}
 {menuitem}{menulink:home}[Home] Page{menulink}{menuitem}
 {menu}[Builder]
  {submenumenuitem}[CSS Custom StylesBuilder 1.x]{menuitem}
  {sub-menu}[Builder 2.x]
    {menuitem}[HeadingsMenus CSS2.x]{menuitem}
  {sub-menu}
 {menu}
{menubar}
{noformat}

Which results in:

{menubar}
 {menuitem}[Text Styles CSS]}{menulink:home}Home Page{menulink}{menuitem}
  {submenumenu}[Builder]
  {menuitem}[InstallingBuilder Builder1.x]{menuitem}
  {sub-menu}[Builder 2.x]
   {menuitem}[Menus 2.x]{menuitem}
  {sub-menu}
 {noformatmenu}
{menubar}

IfWhen you put that notation in to a page, it would look like this:

{menuitem}[Home hover over the Builder 2.x item, a sub-menu will be shown.

You can add sub-menus to your sub-menus using the sub-submenu macro, for example:

{noformat}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Builder]
  {menuitem}[Builder 1.x]{menuitem}
  {sub-menu}[Builder 2.x]
   {sub-submenu}[CSS Custom StylesMenus 2.x]
    {menuitem}[Headings CSSCreating Menus 2.x]{menuitem}
   {sub-submenu}
  {sub-menu}
 {menu}
{menubar}
{noformat}

Which results in:

{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Text Styles CSSBuilder]
  {menuitem}[Builder 1.x]{menuitem}
  {sub-menu}[Builder 2.x]
   {sub-submenu}[Menus 2.x]
    {menuitem}[Installing BuilderCreating Menus 2.x]{menuitem}
  {menuitem}[Menus]{menuitem}
{menu}

The ??Headings CSS?? and ??Text Styles CSS?? items will now appear on a sub-menu that gets displayed when the mouse is over the ??CSS Custom Styles?? menu item.

You can increase the indentation still further to add sub-menus to sub-menus and so on.

If you don't like typing all the [Wiki Markup Editor], you might consider using [Automated Menu Creation] and let macros do all the work for you!

h3. Menu Spacers

You will have noticed that the menus at the top of this page have spacer bars in them - to create a spacer bar, just use the [Wiki Markup Editor] for a horizontal rule:

{noformat}
{menuitem}[Home]{menuitem}
{menuseparator}
{menuitem}[Builder]{menuitem}
{noformat}

You can add spacers in both the menu bar, pop-up menus and sub-menus. {sub-submenu}
  {sub-menu}
 {menu}
{menubar}

h2. Adding links to external sites

When adding links to external sites, you should use the [menulink macro] as shown below:

{noformat}
{menubar}
 {menuitem}{menulink:custom|link=http://adaptavist.com}Adaptavist Website{menulink}{menuitem}
{menubar}
{noformat}

Which results in:

{menubar}
 {menuitem}{menulink:custom|link=http://adaptavist.com}Adaptavist Website{menulink}{menuitem}
{menubar}

This format ensures that the link is output in a format the menu understands - if you were to use normal Confluence wiki notation for an external link, it sometimes won't work depending on which version of Confluence you are using.

h2. Menu Separators

You can add separator bars to your menus using the [menuseparator macro]:

{noformat}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuseparator}
 {menu}[Biulder]
  {menuitem}[Builder 1.x]{menuitem}
  {menuseparator}
  {menuitem}[Builder 2.x]{menuitem}
 {menu}  
 {menuseparator}
 {viewmenu}
{menubar}
{noformat}

Which results in:

{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuseparator}
 {menu}[Biulder]
  {menuitem}[Builder 1.x]{menuitem}
  {menuseparator}
  {menuitem}[Builder 2.x]{menuitem}
 {menu}  
 {menuseparator}
 {viewmenu}
{menubar}

You can add spacers in both the menu bar, pop-up menus and sub-menus.

h2. Menu Housekeeping

Another benefit of the menu macros is that they will automatically adapt to user permissions (eg. can the user view the page being linked to) and automatically remove items that are not applicable.

For example, the page "Foo" does not exist in this space:

{noformat}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuseparator}
 {menuitem}[Foo]{menuitem}
{menubar}
{noformat}

When the menu is rendered you'll see this:

{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuseparator}
 {menuitem}[Foo]{menuitem}
{menubar}

As you can see, the "Foo" menu item has been removed and this also resulted in the now useless separator being removed.

In cases where a pop-up menu, sub-menu or sub-submenu is empty (due to invalid items being removed), those levels of the menu will also be removed as applicable.

h2. Hints and Tips

You can generate menus automatically using any macro which outputs an unordered bullet list. For more information and examples, see our tutorial on [Automated Menu Creation].

h2. See Also

The following menu macros are available:

{children:page=Builder Menu Macros|excerpt=true}

There are also several other tutorials in this section:

{children:page=Menus 2.x|excerpt=true}