Theme Builder Plugin

[All Adaptavist Apps]

Page tree

Versions Compared

Old Version 2

changes.mady.by.user Unknown User (gfraser)

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User (gwilson)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Wiki Markup
h1. Menu Basics

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

h2. Overview

Menus are created by using one or more [Menu Sections

The menus in {builder} are split in to three sections:

* *Custom Pre-Menu* - these menu items appear _before_ the ??View?? and ??Edit?? menus.
* *View and Edit menus* - these are in-built menus that contain all of the standard {confluence} navigational elements.
* *Custom Post-Menu* - these menu items appear _after_ the ??View?? and ??Edit?? menus.

The standard ??View?? and ??Edit?? menus can be [partially customised|Customising the View and Edit Menus], however you can't make major alterations to them. This is because they contain additional logic that enables and disables items based on the location within a [space|Spaces] (eg. you can't add comments to the site map) and the privileges of the logged in user.

The custom pre- and -post menus, however are completely customisable and we'll cover the basics of defining menus in the remainder of this tutorial...

h2. Custom Menus

The custom menus are constructed using simple [Wiki Notation], more specifically [lists|indents and Lists] and [links].

h3. Buttons on the Menu Bar

The structure of a menus is defined using an ??unordered?? bullet list and the hyperlinks in a menu are defined using, somewhat obviously, links. :)

Here's a quick example:

{noformat}
* Home
* Builder
{noformat}

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

* Home
* Builder

You can link these buttons to pages by turning them in to links:

{noformat}
* [Home]
* [Builder]
{ Macros]. An example of a very basic menu is shown below:

{noformat}
{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {menu}[Builder]
  {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}[Builder]
  {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:

{noformat}
{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}[Builder 1.x]{menuitem}
 {menuitem}[Builder 2.x]{menuitem}
{menubar}

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.

h2. Pop-Up Menus

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

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

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:

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

Which results in:

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

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

h2. Sub-Menus

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:

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

Which results in:

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

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:

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

Which results in:

* [Home]
* [Builder]

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

h2. Adding links to external sites

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

{noformat}
* [Start|Home|Our homepage]
* [Adaptavist|{menubar}
 {menuitem}{menulink:custom|link=http://adaptavist.com|Our website]}Adaptavist Website{menulink}{menuitem}
{menubar}
{noformat}

Which wouldresults givein:

* [Start|Home|Our homepage]
* [Adaptavist|{menubar}
 {menuitem}{menulink:custom|link=http://adaptavist.com|Our website]

When a linked button on}Adaptavist Website{menulink}{menuitem}
{menubar}

This format ensures that the link is output in a format the menu barunderstands is- clicked,if you were willto beuse takennormal toConfluence thewiki locationnotation definedfor byan theexternal link, it sometimes won't work depending on which version of Confluence you are using.

h3h2. Pop-Up View and Edit Menus

AsTheme you'llBuilder seeincludes fromdefault theView menuand barEdit buttonsmenus atthat thecontain toplinks ofto thisall page,common mostConfluence offunctionality. themThese displaycan abe pop-up menu wheninserted using the mouse[viewmenu movesmacro] overand them. To do this, simply increase the indentation of items that you want to move from the menu bar to the pop-up menu[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 a menu, use the following notation:

{noformat}
{menubar}
* [Home]
* [Builder]
** [CSS Custom Styles]
** [Installing Builder]
** [Menus]
{noformat}

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

* [Home]
* [Builder]
** [CSS Custom Styles]
** [Installing Builder]
** [Menus]

h3. Sub-Menus

Just as you increase the indentation to move items from the menu bar to the pop-up menu, you can increase it still further to create sub-menus:

{noformat}
* [Home]
* [Builder]
** [CSS Custom Styles]
*** [Headings CSS]
*** [Text Styles CSS]
** [Installing Builder]
** [Menus]
{noformat}

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

* [Home]
* [Builder]
** [CSS Custom Styles]
*** [Headings CSS]
*** [Text Styles CSS]
** [Installing Builder]
** [Menus]

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.

You can increase the indentation still further to add sub-menus to sub-menus and so on. {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {viewmenu}
{menubar}
{noformat}

Which results in:

{menubar}
 {menuitem}{menulink:home}Home Page{menulink}{menuitem}
 {viewmenu}
{menubar}

You can fully customise the View and Edit menus by editing their wiki notation in [Theme Configuration|Theme Configuration 2.x].

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.

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}[Builder]
  {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}[Builder]
  {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. On-screen text and Tool Tips

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

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

Which results in:

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

Note: Tool tips will only be shown if enabled in the Menu Settings section of [Theme Configuration|Theme Configuration 2.x].

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

There are also several other tutorials in this section:

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