Skip to end of metadata
Go to start of metadata

This tutorial explains how to create menus in Theme Builder 3.x...

What's New?

Theme Builder 3 introduces a new compound-menulink macro which makes menu notation cleaner and easier as well as making your menus much faster (2/3rds faster compared to the previous syntax).

You can still use the old notation as described in Creating Menus 2.x but we highly recommend porting any existing menus over to use the new compound-menuitem macro as shown in this tutorial.

Overview

Menus are created by using one or more Menu Macros. An example of a very basic menu is shown below:

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menu}[Builder]
  {menuitem}[Builder 2.x]{menuitem}
  {menuitem}[Builder 3.x]{menuitem}
 {menu}  
 {viewmenu}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

[Builder]

Unknown macro: {menuitem}

Builder 2.x

Unknown macro: {menuitem}

Builder 3.x

Unknown macro: {viewmenu}

This notation can be used within theme panels 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).

The Menu Bar

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

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menuitem}[Builder 2.x]{menuitem}
 {menuitem}[Builder 3.x]{menuitem}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menuitem}

Builder 2.x

Unknown macro: {menuitem}

Builder 3.x

You'll notice that we've used the compound-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.

Pop-Up Menus

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

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menu}[Builder]
  {menuitem}[Builder 2.x]{menuitem}
  {menuitem}[Builder 3.x]{menuitem}
 {menu}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

[Builder]

Unknown macro: {menuitem}

Builder 2.x

Unknown macro: {menuitem}

Builder 3.x

In the example above, when you hover the mouse over "Builder" you'll see a pop-up menu containing two items. You can also click the "Builder" link to go to the page 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:

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menu}Builder Versions
  {menuitem}[Builder 2.x]{menuitem}
  {menuitem}[Builder 3.x]{menuitem}
 {menu}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

Builder Versions

Unknown macro: {menuitem}

Builder 2.x

Unknown macro: {menuitem}

Builder 3.x

When you hover over "Builder Versions" the pop-up menu will still be displayed.

submenus

To add submenus to items on a pop-up menu, use the submenu macro. For example, to add a submenu to to the Builder 3.x item, the following notation is used:

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menu}[Builder]
  {menuitem}[Builder 2.x]{menuitem}
  {submenu}[Builder 3.x]
   {menuitem}[Menus Tab]{menuitem}
  {submenu}
 {menu}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

[Builder]

Unknown macro: {menuitem}

Builder 2.x

Unknown macro: {submenu}

Builder 3.x

Unknown macro: {menuitem}

Menus Tab

When you hover over the Builder 3.x item, a submenu will be shown.

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

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menu}[Builder]
  {menuitem}[Builder 2.x]{menuitem}
  {submenu}[Builder 3.x]
   {sub-submenu}[Menus Tab]
    {menuitem}[Creating Menus 3.x]{menuitem}
   {sub-submenu}
  {submenu}
 {menu}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

[Builder]

Unknown macro: {menuitem}

Builder 2.x

Unknown macro: {submenu}

Builder 3.x

Unknown macro: {sub-submenu}

Menus Tab

Unknown macro: {menuitem}

Creating Menus 3.x

Adding links to external sites

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

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

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Adaptavist Website

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.

View and Edit Menus

Theme Builder includes default View and Edit menus that contain links to all common Confluence functionality. These can be inserted using the viewmenu macro and editmenu macro and are an easy way to quickly ensure that your menu provides access to key features of the wiki.

For example, to add the View menu to you menu bar, use the following notation:

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {viewmenu}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {viewmenu}

You can fully customise the View and Edit menus by editing their wiki notation on the Menus Tab.

You do not need to use these macros if you don't want to - you could chose to add the various links to any part of your menu.

Menu Separators

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

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menuseparator}
 {menu}[Builder]
  {menuitem}[Builder 2.x]{menuitem}
  {menuseparator}
  {menuitem}[Builder 3.x]{menuitem}
 {menu}  
 {menuseparator}
 {viewmenu}
{menubar}

Which results in:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menuseparator}

Unknown macro: {menu}

[Builder]

Unknown macro: {menuitem}

Builder 2.x

Unknown macro: {menuitem}

Builder 3.x

Unknown macro: {menu}
Unknown macro: {menuseparator}
Unknown macro: {viewmenu}

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

On-screen text and Tool Tips

You can use different on-screen text and tool tips for menu items using the following notation:

{menubar}
 {compound-menuitem:home|caption=Home Page|tooltip=Go Home}
 {menuitem}[Theme Builder 2|Builder 2.x|Find out about verison 2]{menuitem}
 {menuitem}[Builder 3.x]{menuitem}
{menubar}

Which results in:

{menubar}
 {menuitem}{menulink:home|tooltip=Go Home}Home Page{menulink}{menuitem}
 {menuitem}[Theme Builder 2|Builder 2.x|Find out about verison 2]{menuitem}
 {menuitem}[Builder 3.x]{menuitem}
{menubar}

As you can see, only the first two items have a tooltip, we've not added a tooltip to the Builder 3.x link.

Note: Tool tips will only be shown if enabled in the Menu Settings section of Theme Configuration.

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:

{menubar}
 {compound-menuitem:home|caption=Home Page}
 {menuseparator}
 {menuitem}[Foo]{menuitem}
{menubar}

When the menu is rendered you'll see this:

Unknown macro: {menubar}
Unknown macro: {menuitem}
Unknown macro: {menulink}

Home Page

Unknown macro: {menuseparator}
Unknown macro: {menuitem}

Foo

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, submenu or sub-submenu is empty (due to invalid items being removed), those levels of the menu will also be removed as applicable.

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.

See Also

The following menu macros are available:

There are also several other tutorials in this section:

And you should also check out the Menus Tab in the Layout Manager.

  • No labels

5 Comments

  1. Unknown User (nana)

    Good morning,
    I would like to link create a menuitem to link to the officeconnector " Edit in word". what is the menu item for it. thanks. In the future how do i find out what confluence menu item names are

    Nana

  2. Unknown User (btnguest4@burton.com.au)

    Is it possible to restrict the visibility of menu items? Say, management can view an additional 'management' tab, while regular users cannot??

    Thanks.

    1. Use one of these builder-show macro to wrap the content you only want to display to users of a particular group

  3. Unknown User (mkubik)

    Hello there!

    Quick question: Any way to copy a section of a page, as in the page and all of it´s child pages as well?

    Thanks much!