Skip to end of metadata
Go to start of metadata

The {menu}, {submenu}, {sub-submenu} and {menuitem} macros are all the same macro! The different names are merely to aid legibility of menu definitions by allowing semantically/heirarchically correct structures to be built in the following form:

  • Menu
    • Submenu
      • Sub-Submenu
        • Menuitem

Each of these macroscreates an item in your menu, grouping any sub-items (if found) in to a "pop-up" menu of their own, which can contain further items and pop-up menus.

There are a few other features provided by these macros, such as automatic hiding of items you don't have access to and auto-cleaning of unwanted separators, but we'll discuss those in the examples at the bottom of this page.

This macro requires Theme Builder 2.0 or above.

To recreate the hierarchical structure shown above, use the following notation:

{menu}Menu
 {submenu}Submenu
   {sub-submenu}Sub-Submenu
     {menuitem}Menuitem{menuitem}
   {sub-submenu}
 {submenu}
{menu}

We'll show examples of common structures in the examples at the bottom of this page.

Property

Required

Default

Notes

class

(error)

 

The CSS class name to assign to an item in a menu

subclass

(error)

 

The CSS class name to assign to a pop-up menu that's associated with an item in a menu

id

(error)

 

The HTML ID (must be unique for the entire web page) associated with an item in the menu

subid

(error)

 

The HTML ID (must be unique for entire web page) associated to a pop-up menu that's associated with an item in a menu

autohide

(error)

true

The following values are permitted:

  • true – the item will be removed if it doesn't contain a hyperlink
  • false – the item will always be shown regardless of whether it contains a hyperlink or not
  • disabled – the item will always be shown, but if it doesn't contain a hyperlink it will be "visually" disabled (e.g. grey text and faded icon)

custom

(error)

false

The following values are permitted:

  • false – a normal menu item, which may contain a pop-up menu if there are hierarchically lower items found
  • true – allows you to embed just about anything in a menu item, defaults the "autohide" setting to false and prevents you from having a pop-up menu associated with the item

flat

(error)

false

The following values are permitted:

  • false – a normal menu item designed for use in a hierarchical structure
  • true – a "flat" (non-hierarchical) menu item

hideanon

(error)

false

Hide the contents of the menu from anonymous users

 

flag

(error)

 

The macro is rendered only if one or more of the specified flags are set. See Working with Flags for more details.

3.3.6

notflag

(error)

 

The macro is rendered only if none of the specified flags are set. See Working with Flags for more details.

3.3.6

 

The most basic use of these macros is to output a single menu item:

 {menuitem}[Home Page|Home|Go to the Home Page]{menuitem}

We've used a wiki notation link in the example above to create a link to the Home page within the current space. You can use any valid wiki notation link inside a menu item so you could, for example, link to a news item, different space or even a user profile.

It should be noted that if you link to a page in a menu item, and then rename that page, the menu item will not update itself to use the new name of the page. You can get round this problem by using the wikimenu macro which allows you to create a normal bullet list of links on a page (which will be updated if you rename pages) and then import them in to your menu.

For all common locations within Confluence, we recommend using the menulink macro as it will be more reliable, especially if any of the common locations are changed in a later version of Confluence. For example, to create an ultra-reliable link to a home page, use:

 {menuitem}{menulink:home|tooltip=Go to the Home Page}Home Page{menulink}{menuitem}

This might seem like overkill, but it really is far, far more reliable to link to common Confluence locations this way. Anyway...

You can have several items at the same level, for example:

 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}

As you can see, the items are merely output as an unordered list. To put them in to an actual menu bar, simply wrap them in the menubar macro 1 as shown below:

{menubar:id=demo1}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menubar}
  1. Remember to specify a unique ID for the menubar macro, otherwise it won't work!

As you can see, the items are shown next to each other because they are at the same hierarchical level. To create pop-up sub menus, you need to create a hierarchical structure...

 

 

To create hierarchical structures, you wrap menu items in the other macros as shown earlier, for example:

{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}Level 1
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
 {submenu}Level 2
  {menuitem}{menulink:home}Home Page{menulink}{menuitem}
  {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
  {sub-submenu}Level 3
   {menuitem}{menulink:home}Home Page{menulink}{menuitem}
   {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
  {sub-submenu}
 {submenu}
{menu}

Here's another quick example to show that you can "indent" the menu structure at any point, not just the last item in a level:

{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}Level 1
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}

 

See Customising Menu Styles.

  • No labels

10 Comments

  1. Anonymous

    Is there any further information or a resource on customizing the menus using CSS...I seem to be figuring it out by trial and error, but would love any info that could help speed up the process.

  2. Unknown User (dave.miller.uk@gmail.com)

    I'd like to know how to customise menus using CSS as well. Any chance you could update the section "CSS Customisation... To follow".

    How do I customise a left navigation area, so that it's 200px wide, a grey background colour. How do I change the font size and font colour of text in that area?

  3. Unknown User (gfraser)

    We've started a tutorial on menu customisation in our tutorials section. There's still a few bits to finish but it should help with the majority of tasks.

  4. Unknown User (markyd)

    I am trying to create another menu bar on my page. My titles are quite long and are going off the right side of the screen. I would like to do one of two:

    1. I would like to be able to wrap the text so it can be two lines.

    2. In the Notation guide it states you can use "scrolling true". Where is that placed in script (using your example above)?

    {menuitem}{menulink:home}Home Page{menulink}{menuitem}
    {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
    {menu}Level 1
     {menuitem}{menulink:home}Home Page{menulink}{menuitem}
     {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
     {submenu}Level 2
      {menuitem}{menulink:home}Home Page{menulink}{menuitem}
      {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
      {sub-submenu}Level 3
       {menuitem}{menulink:home}Home Page{menulink}{menuitem}
       {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
      {sub-submenu}
     {submenu}
    {menu}
  5. Unknown User (rupert.shanks@ne.nykline.com)

    In the first example reading up the page from here, how would you turn the 'Level 1' text into a link using the compound menu item? I.e. rather than just being something that when hovered over, opens the submenu, actually is also a link within the menu?

    1. Unknown User (gwilson)

      You can do this by using the following:

      {menu}{menulink:custom|link=http://www.google.com}Level 1{menulink}
       {menuitem}{menulink:home}Home Page{menulink}{menuitem}
       {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
       {submenu}Level 2
        {menuitem}{menulink:home}Home Page{menulink}{menuitem}
        {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
        {sub-submenu}Level 3
         {menuitem}{menulink:home}Home Page{menulink}{menuitem}
         {menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
        {sub-submenu}
       {submenu}
      {menu}
      

      Menu items can be replaced with compound-menuitems too.

  6. Unknown User (exsiss)

    Is there a way to make it so instead of opening in a submenu the menu can be separated into categories? So that all "links" can be viewed at once?

    Like so:

    Menu top

    Category1

    • link1
    • link2

    Category2

    • link1
    • link2
    1. Unknown User (gwilson)

      To achieve that, rather than putting items in to submenus I'd just add menuitems and add different CSS classes to style them differently e.g.

      {menu}Menu top
       {menuitem:class=topitem}{menulink:home}Category 1{menulink}{menuitem}
       {menuitem:class=subitem}{menulink:dashboard}link 1{menulink}{menuitem}
       {menuitem:class=subitem}{menulink:dashboard}link 2{menulink}{menuitem}
       {menuitem:class=topitem}{menulink:home}Category 2{menulink}{menuitem}
       {menuitem:class=subitem}{menulink:dashboard}link 1{menulink}{menuitem}
       {menuitem:class=subitem}{menulink:dashboard}link 2{menulink}{menuitem}
      {menu}
      

      So for .subitem i'd maybe add a margin-left and a background-image of an arrow or something to visually distinguish from the .topitems.

  7. Unknown User (gpnkate)

    I'd like to add more items to the menu bar, such as links to pages. The docs say that each menu item must have a unique identifier, but how do you know what that identifier is for each page? I've tried the name of the page, and that didn't work. Thanks for any insight you can give.

    1. Unknown User (gwilson)

      If you're referring to the menubar id parameter, then it's something that you set yourself - by unique it just means that it can't conflict with other element ids on the page so use something you know that know one else will have used such as your initials prepended e.g. gw_menu.