{menubar} Macro

Description

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

Requirements

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

Usage

The most simple usage of the menubar macro is shown below:

{menubar:id=demo1}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menubar}

Which results in:

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

Parameters

Examples

Horizontal vs. Vertical Menus

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:

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

Which results in:

Unknown macro: {menubar}

Unknown macro: {menuitem}

Unknown macro: {menulink}

Home Page

Unknown macro: {menuitem}

Unknown macro: {menulink}

Dashboard

For more information on using menus in sidebars, including changing the way they look within the sidebar, pelase see our tutorial on [USERGUIDE:Adding a menu to a sidebar].

Fun with Shadows

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

Unknown macro: {menubar}

Unknown macro: {menuitem}

Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

Pop Up

Unknown macro: {menuitem}

Unknown macro: {menulink}

Dashboard

You can turn off the menu shadow by setting the value to null as shown below:

{menubar:id=demo4|shadows=null}
{menuitem}{menulink:home}Home Page{menulink}{menuitem}
{menu}Pop Up
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}

Which results in:

Unknown macro: {menubar}

Unknown macro: {menuitem}

Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

Pop Up

Unknown macro: {menuitem}

Unknown macro: {menulink}

Dashboard

And you can also play around with the position of the shadows by altering their x,y offset, for example:

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

Which results in:

Unknown macro: {menubar}

Unknown macro: {menuitem}

Unknown macro: {menulink}

Home Page

Unknown macro: {menu}

Pop Up

Unknown macro: {menuitem}

Unknown macro: {menulink}

Dashboard

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

Electric Menus

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:

Unknown macro: {menubar}

Unknown macro: {menu}

Hover here

Unknown macro: {menuitem}

Unknown macro: {menulink}

Dashboard

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:

{menubar:id=demo7|electric=false}
{menu}Click here
{menuitem}{menulink:dashboard}Dashboard{menulink}{menuitem}
{menu}
{menubar}

Which results in:

Unknown macro: {menubar}

Unknown macro: {menu}

Click here

Unknown macro: {menuitem}

Unknown macro: {menulink}

Dashboard

As you can see, you have to click the button to show the menu.

Use as a context menu

The menu can be used as a right-click context menu

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

Results in:

CSS Customisation

See Customising Menu Styles

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.

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.