Developer's manual

um.menus

Styles which apply to each menu.

• Skip code example

//styles which apply to each menu
um.menus = [
	'-7',      // menu to menu x-offset (+-)["n" pixels]
	'-12',     // menu to menu y-offset (+-)["n" pixels]
	'1',       // border size ["n" pixels]
	'#bdb #080 #080 #bdb', // border colors ["color"|"#hex"|"rgb()"]
	'solid',   // border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'10.8em',  // width ["em"|"ex"|"px"]
	'2',       // padding ["n" pixels]
	'green-strip.gif', // background ["color"|"#hex"|"rgb()"|"image.gif"]
	'background-color:#f8fbd0;', // additional menu CSS
	'greenshadow.png', // shadow background ["color"|"#hex"|"rgb()"|"image.gif"|"none"]
	'2px',     // shadow offset (+-)["em"|"ex"|"px"|"%"|"0"]
	'', // additional shadow layer CSS
	];

//styles which apply to each menu
$um['menus'] = array(
	'-7',      // menu to menu x-offset (+-)["n" pixels]
	'-12',     // menu to menu y-offset (+-)["n" pixels]
	'1',       // border size ["n" pixels]
	'#bdb #080 #080 #bdb', // border colors ["color"|"#hex"|"rgb()"]
	'solid',   // border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'10.8em',  // width ["em"|"ex"|"px"]
	'2',       // padding ["n" pixels]
	'green-strip.gif', // background ["color"|"#hex"|"rgb()"|"image.gif"]
	'background-color:#f8fbd0;', // additional menu CSS
	'greenshadow.png', // shadow background ["color"|"#hex"|"rgb()"|"image.gif"|"none"]
	'2px',     // shadow offset (+-)["em"|"ex"|"px"|"%"|"0"]
	'', // additional shadow layer CSS
	);

menu to menu x-offset (+-)["n" pixels]

Specify the horizontal offset between each level of menus, as a positive or negative integer in pixels. You musn't include the "px" unit, just the number. With a value of "0" adjacent menu borders will touch, but not overlap. Whether you use left or right alignment a positive value means "further away", but note that since positive values create a gap between the menus, they're only possible because of the menu timers, so you should avoid very large gaps, or increase the close timer to compensate.

menu to menu y-offset (+-)["n" pixels]

Specify the vertical offset between each level of menus, as a positive (down) or negative (up) integer in pixels. You musn't include the "px" unit, just the number.

border size ["n" pixels]

Specify a single integer in pixels for the border size around each menu. You musn't include the "px" unit, just the number.

border colors ["color"|"#hex"|"rgb()"]

Specify one, two or four menu border colors, as colornames, hex or rgb color values.

border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]

Specify one, two or four menu border styles, using any valid CSS values. If you use the border-style "none" then please be aware that the border size is part of the menu positioning calculations, and if the border-style is "none" there'll be a value but no rendered border, so you'll get a position discrepancy equal to the border size.

width ["em"|"ex"|"px"]

Specify the default menu width using "em", "ex" or pixels. You cannot exclude the unit unless the value is "0". The result varies according to rendering mode, and equates to menu-item-border-box-width in standards mode, or menu-border-box-width in quirks mode; therefore I recommend erring on the side of too much width, or make sure you test in a quirks-mode browser.

Although you can use "ex" units, I wouldn't recommend them, because browsers have very different ideas about how big they are.

I think the best unit to use is "em".

padding ["n" pixels]

Specify the menu padding, as a single pixel integer which applies to all four sides. You musn't include the "px" unit, just the number.

background ["color"|"#hex"|"rgb()"|"image.gif"]

Specify the menu background, as a colorname, a hex or rgb color value, or an image. Images can be GIF, JPEG (JPG), PNG, MNG or BMP. If you want transparency you can use the colorname "transparent".

additional menu CSS

You can use this space to pass any additional CSS to the menus - for example, if you use image backgrounds you should define a redundent background-color for browsers that don't display images. In theory there are no limitations, but in practise you should be very careful, particularly with properties which are already defined elsewhere, such as position, margins or padding.

Ultimately nothing you do here is guaranteed to work - it's up to you to do thorough testing; some rules may need !important to be stable or have sufficient specificity.

For IE5.5 or IE6 you can use visual transitions, however you cannot use static filters - if you do then Internet Explorer will not render any child menus, only the top-level element which has a static filter. However if you want to apply a Microsoft Shadow Filter, you can do so using the dropshadow's additional CSS.

Filters and transition effects are generated with DirectX, which in Internet Explorer is an ActiveX control (at the same security level as plugins like Flash), therefore they won't work for anyone who has Active-X disabled completely. They can be quite annoying, and might also be very slow for people on older machines or with low amounts of RAM.

As an alternative to proprietary filters, you can have cross-browser sliding transition effects using the sliding menus extension.

shadow background ["color"|"#hex"|"rgb()"|"image.gif"|"none"]

Specify the menu dropshadow background, as a colorname, a hex or rgb color value, or an image. The dropshadow is created dynamically as a solid layer underneath the menu. Set this to "none" if you don't want a dropshadow effect.

Dropshadows are not supported in Mac/IE5, Mozilla Gecko browsers earlier than 0.9.2 (Netscape 6.1), Opera 7.0x, any later Opera build when using fixed positioning, or Win/IE5.0 when using relative positioning. In all cases this is due to rendering or positioning bugs I couldn't workaround.

shadow offset (+-)["em"|"ex"|"px"|"%"|"0"]

Specify the shadow offset as a positive or negative value, using any valid CSS unit. You cannot exclude the unit unless the value is "0". If you specify a negative value then the shadow will cast down and to the left, instead of down and to the right - equivalent to an angle of 225° compared with 135°

additional shadow layer CSS

You can use this space to pass any additional CSS to the shadow layer - for example, if you're using a shadow image-background you should define a redundent background-color for browsers that don't display images.

This value also serves a special purpose - if you use a Microsoft Shadow Filter it will be applied instead of the shadow layer offset, in Windows Internet Explorer 5.5 or later - so you can add a Microsoft filter while still providing a dropshadow effect to other browsers. There's an example of this in the MSDN demo.

It works by resetting the shadow-layer offset to 0, then applying the filter to that layer, and is designed to work with shadows which are oriented to 135°.

um.menuItems

Styles which apply to each menu item.

• Skip code example

//styles which apply to each menu item
um.menuItems = [
	'0',             // margin around items ["n" pixels]
	'1',             // border size ["n" pixels]
	'separate',      // border collapse ["collapse"|"separate"]
	'#f8fbd0',       // border colors ["color"|"#hex"|"rgb()"]
	'none solid none none', // border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'#aca',          // hover/focus border colors ["color"|"#hex"|"rgb()"]
	'none solid none none', // hover/focus border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'#f8fbd0',       // visited border colors ["color"|"#hex"|"rgb()"]
	'none solid none none', // visited border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'5',             // left/right padding ["n" pixels]
	'2',             // top/bottom padding ["n" pixels]
	'transparent',   // background ["color"|"#hex"|"rgb()"|"image.gif"]
	'#ecefc6',       // hover/focus background ["color"|"#hex"|"rgb()"|"image.gif"]
	'transparent',   // visited background ["color"|"#hex"|"rgb()"|"image.gif"]
	'70%',           // font size ["em"|"ex"|"%"|"px"|"pt"|"absolute-size"|"relative-size"]
	'tahoma,sans-serif', // font family ["font1,font2,font3"]
	'normal',        // font weight ["normal"|"bold"|"bolder"|"lighter|"100" to "900"]
	'none',          // text decoration ["none"|"underline"|"overline"|"line-through"]
	'left',          // text-align ["left"|"right"|"center"]
	'#060',          // color ["color"|"#hex"|"rgb()"]
	'#000',          // hover/focus color ["color"|"#hex"|"rgb()"]
	'#060',          // visited color ["color"|"#hex"|"rgb()"]
	'normal',        // font-style ["normal"|"italic"|"oblique"]
	'normal',        // hover/focus font-style ["normal"|"italic"|"oblique"]
	'normal',        // visited font-style ["normal"|"italic"|"oblique"]
	'padding-left:29px;border-right-width:2px;', // additional link CSS
	'padding-left:29px;border-right-width:2px;', // additional hover/focus CSS
	'border-right-width:2px;', // additional visited CSS
	'right-green.gif', // submenu indicator character/image ["text"|"image.gif"|"none"] 
	'right-black.gif', // submenu indicator rollover image ["image.gif"|"none"]
	'3',             // clipping width of indicator image ["n" pixels]
	'..',            // alt text of indicator image ["text"]
	];

//styles which apply to each menu item
$um['menuItems'] = array(
	'0',             // margin around items ["n" pixels]
	'1',             // border size ["n" pixels]
	'separate',      // border collapse ["collapse"|"separate"]
	'#f8fbd0',       // border colors ["color"|"#hex"|"rgb()"]
	'none solid none none', // border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'#aca',          // hover/focus border colors ["color"|"#hex"|"rgb()"]
	'none solid none none', // hover/focus border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'#f8fbd0',       // visited border colors ["color"|"#hex"|"rgb()"]
	'none solid none none', // visited border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]
	'5',             // left/right padding ["n" pixels]
	'2',             // top/bottom padding ["n" pixels]
	'transparent',   // background ["color"|"#hex"|"rgb()"|"image.gif"]
	'#ecefc6',       // hover/focus background ["color"|"#hex"|"rgb()"|"image.gif"]
	'transparent',   // visited background ["color"|"#hex"|"rgb()"|"image.gif"]
	'70%',           // font size ["em"|"ex"|"%"|"px"|"pt"|"absolute-size"|"relative-size"]
	'tahoma,sans-serif', // font family ["font1,font2,font3"]
	'normal',        // font weight ["normal"|"bold"|"bolder"|"lighter|"100" to "900"]
	'none',          // text decoration ["none"|"underline"|"overline"|"line-through"]
	'left',          // text-align ["left"|"right"|"center"]
	'#060',          // color ["color"|"#hex"|"rgb()"]
	'#000',          // hover/focus color ["color"|"#hex"|"rgb()"]
	'#060',          // visited color ["color"|"#hex"|"rgb()"]
	'normal',        // font-style ["normal"|"italic"|"oblique"]
	'normal',        // hover/focus font-style ["normal"|"italic"|"oblique"]
	'normal',        // visited font-style ["normal"|"italic"|"oblique"]
	'padding-left:29px;border-right-width:2px;', // additional link CSS
	'padding-left:29px;border-right-width:2px;', // additional hover/focus CSS
	'border-right-width:2px;', // additional visited CSS
	'right-green.gif', // submenu indicator character/image ["text"|"image.gif"|"none"] 
	'right-black.gif', // submenu indicator rollover image ["image.gif"|"none"]
	'3',             // clipping width of indicator image ["n" pixels]
	'..',            // alt text of indicator image ["text"]
	);

margin around items ["n" pixels]

Specify a single value in pixels for the margin around each menu link. You musn't include the "px" unit, just the number. Consecutive items only have a single margin-thickness between them, so in this respect the margins are like table cellspacing.

border size ["n" pixels]

Specify a single value in pixels for the border size around each menu link. You musn't include the "px" unit, just the number.

border collapse ["collapse"|"separate"]

This mimics the CSS border-collapse property of tables - if the margin between items is "0" you can specify whether borders should "collapse", so that there's only one thickness between adjacent links, or remain "separate".

Border collapse works by applying a negative margin to each link, causing it to overlap the previous one. The overall positions of the menu links will allow for this automatically, by shifting down to compensate.

If there are border rollovers, the script uses dynamic z-index to maintain the integrity of individual borders - each link is moved to the top of the stack when highlighted. Unfortunately this doesn't work in IE5. Therefore if you're using border collapse you should probably avoid border rollovers, unless you're working for a known user-base, or you don't mind the discrepancy.

border colors ["color"|"#hex"|"rgb()"]

Specify one, two or four border colors for the default state of menu links, as colornames, hex or rgb color values.

border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]

Specify one, two or four border styles for the default state of menu links, using any valid CSS values. If you use the border-style "none" then please be aware that the border size is part of the menu positioning calculations, and if the border-style is "none" there'll be a value but no rendered border, so you'll get a position discrepancy equal to the border size.

hover/focus border colors ["color"|"#hex"|"rgb()"]

Specify one, two or four border colors for the hover and focus states of menu links, as colornames, hex or rgb color values.

hover/focus border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]

Specify one, two or four border styles for the hover and focus states of menu links, using any valid CSS values.

visited border colors ["color"|"#hex"|"rgb()"]

Specify one, two or four border colors for the visited state of menu links, as colornames, hex or rgb color values.

visited border styles ["solid"|"double"|"dotted"|"dashed"|"groove"|"ridge"|"inset"|"outset"]

Specify one, two or four border styles for the visited state of menu links, using any valid CSS values.

left/right padding ["n" pixels]

Specify the left and right padding of menu links, as a single integer in pixels. You musn't include the "px" unit, just the number.

top/bottom padding ["n" pixels]

Specify the top and bottom padding of menu links, as a single integer in pixels. You musn't include the "px" unit, just the number.

background ["color"|"#hex"|"rgb()"|"image.gif"]

Specify the background for the default state of menu links, as a colorname, a hex or rgb color value, or an image. Images can be GIF, JPEG (JPG), PNG, MNG or BMP. If you want transparency you can use the colorname "transparent".

hover/focus background ["color"|"#hex"|"rgb()"|"image.gif"]

Specify the background for the hover and focus states of menu links, as a colorname, a hex or rgb color value, or an image. This does not have to be the same type as the default state - you can mix colors and images together.

visited background ["color"|"#hex"|"rgb()"|"image.gif"]

Specify the background for the visited state of menu links, as a colorname, a hex or rgb color value, or an image. You can mix background types here as well.

font size ["em"|"ex"|"%"|"px"|"pt"|"absolute-size"|"relative-size"]

Specify the navbar font size using any valid CSS value. "absolute-size" means a value such as "small" or "large"; "relative-size" means "smaller" or "larger".

I strongly recommend you DO NOT use "px" or "pt", because they create unscaleable text in Win/IE. And although you can use "ex" units, I wouldn't recommend them either, because browsers have very different ideas about how big they are.

I think the best units to use are "em" or "%".

font family ["font1,font2,font3"]

Specify the font family used for menu links, as one or more specific or generic family names. Always end with a generic family name - "serif", "sans-serif", "cursive", "fantasy" or "monospace".

font weight ["normal"|"bold"|"bolder"|"lighter|"100" to "900"]

Specify the font weight of menu links.

text decoration ["none"|"underline"|"overline"|"line-through"]

Specify the text-decoration of menu links using any valid CSS value.

There is a text-decoration value "blink", but you shouldn't use it - the Web Content Accessibility Guidelines specifically say to avoid causing content to blink, because it may trigger a seizure in a person who has photosensitive epilepsy.

text-align ["left"|"right"|"center"]

Specify the text-alignment of menu links.

color ["color"|"#hex"|"rgb()"]

Specify the color of the default state of menu links, as a colorname, a hex or rgb color value.

hover/focus color ["color"|"#hex"|"rgb()"]

Specify the color of the hover and focus states of menu links, as a colorname, a hex or rgb color value.

visited color ["color"|"#hex"|"rgb()"]

Specify the color of the visited state of menu links, as a colorname, a hex or rgb color value.

font-style ["normal"|"italic"|"oblique"]

Specify the font-style of the default state of menu links. Very few fonts have different italic and oblique styles.

hover font-style ["normal"|"italic"|"oblique"]

Specify the font-style of the hover and focus states of menu links.

visited font-style ["normal"|"italic"|"oblique"]

Specify the font-style of the visited state of menu links.

additional link CSS

You can use this space to pass any additional CSS to the default state of menu links - for example, if you use image backgrounds you should define a redundent background-color for browsers that don't display images. In theory there are no limitations, but in practise you should be very careful, particularly with properties which are already defined elsewhere, such as position, margins or padding.

Ultimately nothing you do here is guaranteed to work - it's up to you to do thorough testing; some rules may need !important to be stable or have sufficient specificity.

Whatever you define here automatically applies to the visited state as well.

additional hover/focus CSS

Use this space to pass additional CSS to the hover and focus states of menu links - for example, if you use image backgrounds you should define a redundent background-color for browsers that don't display images.

additional visited CSS

Use this space to pass additional CSS to the visited state of menu links - for example, if you use image backgrounds you should define a redundent background-color for browsers that don't display images.

submenu indicator character/image ["text"|"image.gif"|"none"]

Specify a textual character or image which is used to indicate a nested menu, or "none" if you don't want an indicator. If you use an image you must also provide alt text. To help you choose suitable alt text or characters, please read The semantics of menu indicators.

You cannot use entities such as … or … because the characters are created using createTextNode, which cannot create entities (there is a createEntityReference method, but at the time of writing no browser implements it).

You can use unicode characters [PDF] in the form of escaped hex values, for example "\u21d2" is a right-pointing arrow. However these are not particularly well supported cross-browser, and might be problematic in browser-based screenreaders - for example, Home Page Reader sees "?" for an unknown character, and says question mark.

Indicators are not supported in Mac/IE5; image indicators are slightly sketchy in Mozilla Gecko browsers 0.9.4 (Netscape 6.2) or earlier - they don't always appear.

submenu indicator rollover image ["image.gif"|"none"]

If you're using an image indicator you can also specify a rollover image.

If you're using a textual indicator you cannot specify a separate rollover as such - the characters will do whatever CSS changes they inherit from their parent link.

clipping width of indicator image ["n" pixels]

If you're using image indicators you can specify the clipping-width of the image, as an integer in pixels. You musn't include the "px" unit, just the number. This is specifically a clipping region rather than a width - if the value you specify is less than the width of the actual image, only the clipped region will be visible.

alt text of indicator image ["text"]

If you use image arrows you must define alternative text, for the benefit of browsers that don't display images. To help you choose suitable text or characters, please read The semantics of menu indicators.