Page History

The menubar macro turns a bullet list (also known as a "hierarchical list") in to an interactive menu. It's {excerpt}an extremely powerful and flexible macro that allows you to create superb on-screen navigation tools{excerpt} and you'll find almost all Builder themed sites have a menu bar somewhere on the screen.

h2. Requirements

This macro requires [Theme Builder 2.0|Builder 2.x] or above and will only work in a space that's themed with Theme Builder.

h2. Usage

The most simple usage of the menubar macro is shown below:
{code}
{menubar:id=demo1}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menubar}
{code}
Which results in:

{menubar:id=demo1}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menubar}
The "id" parameter is absolutely essential for the menu to work, and it must be unique on the entire web page. If you ever get a menu that doesn't work, try changing the value of the "id" parameter to something else ;)

h2. Parameters

|| Property || Required || Default || Notes ||
|| id | (/) | | This parameter must be specified, and it's value must be unique for the entire web page ||
|| electric | (x) | _true_ | The following values are permitted:
* _true_ \- Pop-up menus will automatically open when the mouse hovers over their parent item, or their parent item gets keyboard focus
* _false_ \- Pop-up menus will only be displayed when the parent item is clicked or when the the parent item is selected and the left arrow key (or spacebar) is pressed ||
|| timeout | (x) | 250 | Defines the number of milliseconds to wait before menus are automatically shown when the "electric" parameter is set to _true_ ||
|| vertical | (x) | _false_ | The following values are permitted:
* _false_ \- Items on the top level of the menu bar are shown horizontally
* _true_ \- Items on the top level of the menu bar are shown vertically (ideal for putting menus in sidebars) ||
|| context | (x) | _false_ | menu is a context menu ||
|| class | (x) | | CSS class to use ||
|| tooltips | (x) | _true_ | The following values are permitted:
* _true_ \- Tooltips, if specified in linked menu items, are shown when the mouse hovers over a menu item
* _false_ \- Tooltips are not shown, useful when your target audience is using a slow internet connection or slow computer ||
|| shadows | (x) | 4,6 | This defines the horizontal and vertical offset of the shadows that appear behind pop-up menus and defaults to 4 pixels horizontal offset and 6 pixels vertical offset. To disable menu shadows, use a value of _null_ ||
|| smooth | (x) | _true_ | The following values are permitted:
* _true_ \- Shadows will look smoother in most browsers (requires an additional image to be loaded)
* _false_ \- Basic shadows will be used (slightly faster loading of pages) ||
|| blink | (x) | _false_ | The following values are permitted:
* _false_ \- Menu items do _not_ blink when clicked
* _true_ \- Menu items blink a few times when clicked to give more visual feedback to the end-user ||
|| lazy | (x) | _false_ | The following values are permitted:
* _false_ \- After the web page loads, the entire menu is "built" immediately
* _true_ \- After the web page loads, only the top level of the menu is "built" and subsequent levels (i.e. pop-up menus) are only built when they are first displayed ||
|| toolbar | (x) | _false_ | The following values are permitted:
* _false_ \- The top level of the menu displays normally
* _true_ \- Additional styling is applied which makes items on the top level of the menu take up less space, ideal for toolbars. Note that some menu styles (e.g. the Longhorn style) don't currently support this feature ||
|| clone | (x) | _false_ | clone source DOM objects ||
|| scrolling | (x) | _true_ | The following values are permitted:
* _true_ \- If a menu is too big to fit in the browser window, scroll buttons will appear at either end to allow the user to "scroll" the menu. It's a really nice feature\!
* _false_ \- Menus will be shown in their entirety, even if that means that part of them can't be seen within the browser window ||
||flag|(x)| |Content is shown if one or more of the specified flags are set. See [Working with Flags] for more details.|3.3.6|
||notflag|(x)| |Content is shown if _none_ of the specified flags are set. See [Working with Flags] for more details.|3.3.6|

h2. Examples


h3. Horizontal vs. Vertical Menus

{quote}
Horizontal menus, like the one shown earlier in this page, are ideal for use in the following locations:
* Header panel
* Menu panel
* Navigation panel
* Title panel
* Footnotes panel
* Footer panel
* Inside content such as pages and news items

However, if you're thinking of putting a menu in to a sidebar, you should use a vertical menu, for example:
{code}
{menubar:id=demo2|vertical=true}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menubar}
{code}
Which results in:

{menubar:id=demo2|vertical=true}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menubar}
{quote}

h3. Fun with Shadows

{quote}
By default, shadows are shown on pop-up menus, as shown below:

{menubar:id=demo3}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}Pop Up
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}
You can turn off the menu shadow by setting the value to _null_ as shown below:
{code}
{menubar:id=demo4|shadows=null}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}Pop Up
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}
{code}
Which results in:

{menubar:id=demo4|shadows=null}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}Pop Up
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}
And you can also play around with the position of the shadows by altering their x,y offset, for example:
{code}
{menubar:id=demo5|shadows=-4,-6}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}Pop Up
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}
{code}
Which results in:

{menubar:id=demo5|shadows=-4,-6}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}Pop Up
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}

There is also a "smooth" setting, however we've never really noticed any difference between normal shadows and smooth shadows so you can probably set that to _false_ in most cases :-)
{quote}

h3. Electric Menus

{quote}
No, this won't electrocute anyone who uses the menu. It's an (oddly named) setting that determines whether pop-up menus are automatically shown or not. For example, move your mouse over the "Hover here" button below:

{menubar:id=demo6|electric=true}
{menu}Hover here
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}
By setting "electric" to _true_, sub menus are automatically displayed when the mouse hovers over them or when they receive keyboard focus.

You can disable this effect by setting "electric" to _false_ as shown below:
{code}
{menubar:id=demo7|electric=false}
{menu}Click here
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}
{code}
Which results in:

{menubar:id=demo7|electric=false}
{menu}Click here
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}
As you can see, you have to click the button to show the menu.
{quote}

h3. Use as a context menu
The menu can be used as a right-click context menu
{code}
{div:id=redbox|style=background-color:#DD2222;text-align:center;}right-click on me{div}
{div:id=bluebox|style=background-color:#2222DD;text-align:center;}right-click on me{div}

{menubar:id=demo8|context=true}
 {menu:class=context-for-redbox}
  {compound-menuitem:home|caption=link one}
  {compound-menuitem:home|caption=link two}
  {compound-menuitem:home|caption=link three}
 {menu}
 {menu:class=context-for-bluebox}
  {compound-menuitem:home|caption=other link one}
  {compound-menuitem:home|caption=other link two}
  {compound-menuitem:home|caption=other link three}
 {menu}
{menubar}
{code}

Results in:
{div:id=redbox|style=background-color:#DD2222;text-align:center;}right-click on me{div}
{div:id=bluebox|style=background-color:#2222DD;text-align:center;}right-click on me{div}

{menubar:id=demo8|context=true}
 {menu:class=context-for-redbox}
  {compound-menuitem:home|caption=link one}
  {compound-menuitem:home|caption=link two}
  {compound-menuitem:home|caption=link three}
 {menu}
 {menu:class=context-for-bluebox}
  {compound-menuitem:home|caption=other link one}
  {compound-menuitem:home|caption=other link two}
  {compound-menuitem:home|caption=other link three}
 {menu}
{menubar}

h2. CSS Customisation

See [Customising Menu Styles]

h2. Hints and Tips

If your menu doesn't seem to be working, the first thing to check is that you have specified an "id" for it. If you have, try changing that "id" to something else - the id has to be unique for the entire web page.

If your menu still isn't appearing, then it's possible that none of the items in it are hyperlinked - by default, un-linked items are filtered out of the menu. For example, if you've linked to a page that doesn't yet exist, it's likely that the item will be removed from the menu.

h2. Frequently Asked Questions

??I'm using Opera and the menus seem to appear in odd locations...??

Some versions of Opera don't work too well with scrolling menus (scroll=true). Either upgrade to a more recent version of Opera or turn off scrolling menus.