[All Adaptavist Apps]
This tutorial explains how to create menus in Theme Builder 2.x...
Menus are created by using one or more [Builder Menu Macros]. An example of a very basic menu is shown below:
{menubar} {menuitem}{menulink:home}Home Page{menulink}{menuitem} {menu}[Biulder] {menuitem}[Builder 1.x]{menuitem} {menuitem}[Builder 2.x]{menuitem} {menu} {viewmenu} {menubar}
Which results in:
Home Page
[Biulder]
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).
To define the top-level links on the menu bar, the following notation should be used:
Home Page
Which results in:
Home Page
You'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.
To add pop-up menus to the menu bar links, use the menu macro:
Home Page
[Builder]
Which results in: {menubar} {menuitem}{menulink:home}Home Page{menulink}{menuitem} {menu}[Builder] {menuitem}[Builder 1.x]{menuitem} {menuitem}[Builder 2.x]{menuitem} {menu} {menubar} 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: {noforamt} {menubar} {menuitem}{menulink:home}Home Page{menulink}{menuitem} {menu}Builder Versions {menuitem}[Builder 1.x]{menuitem} {menuitem}[Builder 2.x]{menuitem} {menu} {menubar}
Which results in:
Home Page
Builder Versions
When you hover over "Builder Versions" the pop-up menu will still be displayed.
To add sub-menus to items on a pop-up menu, use the [sub-menu macro]. For example, to add a sub-menu to to the Builder 2.x item, the following notation is used:
{menubar} {menuitem}{menulink:home}Home Page{menulink}{menuitem} {menu}[Builder] {menuitem}[Builder 1.x]{menuitem} {sub-menu}[Builder 2.x] {menuitem}[Menus 2.x]{menuitem} {sub-menu} {menu} {menubar}
Which results in:
Home Page
[Builder]
When you 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:
{menubar} {menuitem}{menulink:home}Home Page{menulink}{menuitem} {menu}[Builder] {menuitem}[Builder 1.x]{menuitem} {sub-menu}[Builder 2.x] {sub-submenu}[Menus 2.x] {menuitem}[Creating Menus 2.x]{menuitem} {sub-submenu} {sub-menu} {menu} {menubar}
Which results in:
Home Page
[Builder]
When adding links to external sites, you should use the menulink macro as shown below:
{menubar} {menuitem}{menulink:custom|link=http://adaptavist.com}Adaptavist Website{menulink}{menuitem} {menubar}
Which results in:
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.
You can add separator bars to your menus using the menuseparator macro:
{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}
Which results in:
Home Page
[Biulder]
You can add spacers in both the menu bar, pop-up menus and sub-menus.
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} {menuitem}{menulink:home}Home Page{menulink}{menuitem} {menuseparator} {menuitem}[Foo]{menuitem} {menubar}
When the menu is rendered you'll see this:
Home Page
[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, sub-menu or sub-submenu is empty (due to invalid items being removed), those levels of the menu will also be removed as applicable.
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.
The following menu macros are available:
There are also several other tutorials in this section: