Theme Builder Plugin

[All Adaptavist Apps]

Page tree

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.

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

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}

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 (wink)

Property

Required

Default

Notes

id

(tick)

 

This parameter must be specified, and it's value must be unique for the entire web page

electric

(error)

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

(error)

250

Defines the number of milliseconds to wait before menus are automatically shown when the "electric" parameter is set to true

vertical

(error)

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

(error)

false

menu is a context menu

class

(error)

 

CSS class to use

tooltips

(error)

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

(error)

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

(error)

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

(error)

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

(error)

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

(error)

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

(error)

false

clone source DOM objects

scrolling

(error)

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

(error)

 

Content is shown if one or more of the specified flags are set. See Working with Flags for more details.

3.3.6

notflag

(error)

 

Content is shown if none of the specified flags are set. See Working with Flags for more details.

3.3.6

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}

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

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}

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}

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 (smile)

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

As you can see, you have to click the button to show the 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}

See Customising Menu Styles

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.

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.

  • No labels

21 Comments

  1. Unknown User (sebastian)

    Hi,

    i have just added the scrolling function to my menu. Is it possible to define individually when the srolling function appears?
    I would like it to appear as soon as there are 15 menuitems within the menu.

    Cheers,

    Sebastian

    1. Unknown User (gfraser)

      I don't think it's possible to do that, however you could experiment with using CSS to fix the height of div.dynarch-popup-menu elements...

      1. Unknown User (amoran)

        The menubar macro is based on the dynarch menu: http://www.dynarch.com/products/dhtml-menu/

        if there are any features of the menu that you would like access to from the menubar macro then please create an issue here https://tracker.adaptavist.com/browse/bsup

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

        Hi Guy

        Could you please explain how to do this (fix the height of div.dynarch-popup-menu elements...)?

        1. Unknown User (gfraser)

          Something like this:

          div.dynarch-popup-menu {
 height: 300px;
}

          I've not had chance to test it but it might work.

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

    Just found this- "For more information on using menus in sidebars, including changing the way they look within the sidebar, pelase see our tutorial on Adding a menu to a sidebar."

    But you haven't provided a link. Could you please send me the URL to this page?

    1. Unknown User (gfraser)

      I don't think we ever added that page - we've taken on more staff recently who are helping with documentation and support so I'll ask one of them to write a tutorial or do a screencast for this.

  3. Unknown User (dudester)

    How can I customize the style of my menubar? I would like to be able to create my own menu skin that reflects our company's preferred look and feel. In addition, is there a way to write an inline stylesheet for menu items? the "class" parameter in the menubar does not seem to work.

    Thanks,

  4. Unknown User (nikunj.jariwala_ra@yahoo.com)

    Hi there,
    Is it possible to put 

    {create-page}Click here to create a page{create-page}

    in the menu bar.
    How to do that??
    -Nikunj

    1. Unknown User (agehl)

      hi,

      I have the same question. Is there a way or a workaround to do that?

      Thanks.

      1. Unknown User (amoran)

        The 'newpage' menulink would seem the obvious choice, eg:

        {compound-menuitem:newpage|icon=document_add|caption=Click here to create a page}

        1. Unknown User (agehl)

          Is it possible to specify a template or live-template like create_page macro? and it seems there is no popup for the page title.

          Thanks.

  5. Unknown User (rkrause)

    Is it possible to right-justify a menu item?

    s an example, I would like the "view" and "edit" menu items to appear on the right hand side of the menu bar.

  6. Unknown User (boesch)

    When I add the following code, which I took straight out of this page, I do not get the expected result.

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

    I get the following instead, which on my computer shows up as a vertical bulleted list of list with Home Page and Dashboard links. Based on what is displayed above, it is supposed to be horizontal with no bullets.

    For some reason the markup below is translated and is showing up when I preview it, but does not show anything when I post it.

    Unknown macro: {menubar}
    Unknown macro: {menuitem}
    Unknown macro: {menulink}

    Home Page

    Unknown macro: {menuitem}
    Unknown macro: {menulink}

    Dashboard

    I have cut and pasted from my screen what shows up, except that the bullets are links in my case.

    • Home Page
    • Dashboard

    1. Unknown User (boesch)

      Maybe I should have read the requirements. It is working now.

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

  7. Unknown User (dgifford33)

    Hi,
    When trying to use tooltips within a menubar, couldn't get them to work unless I set tooltips=true. I thought the default was true. What am I doing wrong? Need to have
    "tooltips=true" for tool tips to work.

    Unknown macro: {menubar}

    Thanks for your help!

    Regards,
    Doreen

  8. Unknown User (robert.ortner@prjnet.com)

    Hi!

    Is it possible to get a dynamic menu with spaces containing a specific space label or team label?

    I did not find anything like this?

    Regards,
    Robert

    1. Unknown User (amoran)

      Hmm ... I'm not sure how we can make these pages more visible.

      list-spaces macro
      wikimenu macro
      Automated Menu Creation

      1. Unknown User (robert.ortner@prjnet.com)

        Thx - ok I got it. I did´t get to connect listspaces (which I found before)with menuitem.

        Robert

        p.s.: perhaps you have to remove the the expnad macro over the only hint "show me how" (wink)

        1. Unknown User (amoran)

          Yes, I never did like the hidden stuff .. we are slowly removing it however it's a mammoth task, which is compounded by the fact that builder is a moving target :s

          Recently I've been contemplating asking whether the community would like to help refactor the documentation into a more useful form.

  9. Unknown User (sonukapoor@gmail.com)

    Is there a way to display the entire menu in one shot instead of having the sub-menus appear as popup menus?