home / documentation / reference / mini-tutorial: using classes

Using Classes

Beginning with version 6 of HierMenus, you may assign style sheet class names to menus, menu items, and in later version browsers, menu item buttons. You assign class names via the new MenuClass, ItemClass, ItemClassOver, ItemClassSelected, ButtonClass, ButtonClassOver, and ButtonClassSelected configuration parameters. No HierMenus class name support is provided (at all) in Netscape 4, and in Internet Explorer 4 the ButtonClass family of parameters is not supported.

To make use of style sheet class names in HierMenus, you must have a working knowledge of style sheets themselves; both the necessary syntax for building them and how to apply them to your documents, as well as the results of their use in various browsers. HierMenus implements class name support by simply assigning your designated class names to the menus, items, and buttons of the menus; it makes no guarantees (nor could it) as to how individual browsers will respond to your specific style settings. For further information on style sheets you may wish to visit the W3C's dedicated section on the topic.

When assigning class name designations to menus and items, special care must be taken to ensure that the specific HierMenus parameters related to the style settings you're using in your style sheet are properly set, or most likely, properly cleared. Otherwise, even though you may be applying a class name assignment to a menu, HierMenus own configuration parameters, since they are considered to be more specific then a generic class setting, will take precedence; and as a result you may not see all the stylings you intended to on your menus or menu items.

Basic Class Name Assignments

Let's have a look at a basic use of class names in a simple horizontal menu. Consider this style sheet entry and the accompanying HierMenus configuration file:

<style type="text/css">
   .hmMenus     {font-family:Times, serif; font-size:14px}
   .hmItems     {color:white; background-color:#99CCFF}
   .hmItemsOver {color:white; background-color:navy}
</style>
...
HM_f_SetMenus(
{
   MenuID:"Class1",
   IsHorizontal:true,
   MenuWidth:125,
   IsPermanent:true,
   MenuClass:"hmMenus",
   ItemClass:"hmItems",
   ItemClassOver:"hmItemsOver",
   ItemClassSelected:"hmItemsOver",
   CreateOnLoad:true,
   TopKeepInWindowX:false,
   TopKeepInWindowY:false,
   ScrollEnabled:false,
   TopMenuX:"HM_f_GetElementXY('placer1','x')",
   TopMenuY:"HM_f_GetElementXY('placer1','y')"
}
);

HM_f_SetItems(
{MenuID:"Class1",DisplayText:"Menu Item 1",LinkURL:"link1.html"},
{MenuID:"Class1",DisplayText:"Menu Item 2",LinkURL:"link2.html"},
{MenuID:"Class1",DisplayText:"Menu Item 3",LinkURL:"link3.html"},
{MenuID:"Class1",DisplayText:"Menu Item 4",LinkURL:"link4.html"}
);

And the resulting menu looks like this:

But wait a minute... what happened to our Times font? And what of our light blue to navy rollover behavior? Though our configuration setup looks fine, it looks like our class names are not being applied. But this is not the case. The classes are being applied to the menus, but what is not immediately apparent is that the exact styling we are trying to apply, namely the font face and size and the rollover colors, is also being applied directly via HierMenus. Even though we don't specify these parameters directly within our menu configuration, HierMenus will still use its own defaults. Since all HierMenus parameter settings are considered to be more specific then a class name counterpart, they are the settings you actually see in the above menu.

So how do you override these default settings? Simply clear them when the menu (or menu template) is defined. Let's have another look at the same menu, this time clearing (via the empty string, or "") the FontFamily, FontSize, and rollover colors:

HM_f_SetMenus(
{
   MenuID:"Class2",
   IsHorizontal:true,
   MenuWidth:125,
   IsPermanent:true,
   MenuClass:"hmMenus",
   ItemClass:"hmItems",
   ItemClassOver:"hmItemsOver",
   ItemClassSelected:"hmItemsOver",
   CreateOnLoad:true,
   TopKeepInWindowX:false,
   TopKeepInWindowY:false,
   ScrollEnabled:false,
   FontFamily:"",
   FontSize:"",
   FontColor:"",
   FontColorOver:"",
   FontColorSelected:"",
   BGColor:"",
   BGColorOver:"",
   BGColorSelected:"",
   TopMenuX:"HM_f_GetElementXY('placer2','x')",
   TopMenuY:"HM_f_GetElementXY('placer2','y')"
}
);

HM_f_SetItems(
{MenuID:"Class2",DisplayText:"Menu Item 1",LinkURL:"link1.html"},
{MenuID:"Class2",DisplayText:"Menu Item 2",LinkURL:"link2.html"},
{MenuID:"Class2",DisplayText:"Menu Item 3",LinkURL:"link3.html"},
{MenuID:"Class2",DisplayText:"Menu Item 4",LinkURL:"link4.html"}
);

Our new menu looks like this:

Much better! Now our font styles and colors are being applied from our style sheet rules, as we expected.

When using item class names, we recommend that you control all of your rollover colors (the on, off, and selected colors for both the font and the backgrounds) via your class name settings, and then clear HierMenu's default settings as above. Some browsers--particularly Netscape 6.x--may not perform your color rollovers properly unless you do so. (For an example of the problem, roll your mouse over the top menu above--the one that does not have the HM parameters cleared--in a Netscape 6.x browser. You'll notice the background colors, once swapped, are not properly restored when the mouse leaves the menu item.)

Note: The examples on this page use the same script engine as the navigation menus on the left side of thie page. To simplify this type of menu creation, (and make the tutorial clearer) we've elected to add the menus individually, setting each of the needed parameters within each new menu designation or within a new Menu Template. In your own configurations, you will nearly always find it more efficient to use the global defaults for your general menu settings (HM_f_UpdateDefaults) and/or a single menu template (HM_f_SetMenuTemplate). See our HierMenus version 6 setup instructions for further details.

Class Name Restrictions

Before using class names, you need to be aware of some important restrictions imposed by HierMenus.

• Dimension settings not allowed.
  You may not dimension your menus via style sheet rules; which is to say you may not set width, height, padding-width, or border-widths within your style sheet rules. These will always be overridden by HierMenus settings (i.e., you cannot "clear" any of these settings as we described above).

  Button Classes (described below) are an exception to this rule; with button classes you may feel free to adjust the border and padding widths (but for best results we recommend that you still do not attempt to set width or height).

• Font changes on rollover not recommended.
  Do not change the font size or weight in your rollover behaviors. HierMenus does not automatically resize a menu or menu item based on the newly displayed font weight or size, and therefore the resulting menu item on rollover may appear to be clipped and/or won't properly fill the menu item cell.

• Leave room for more images in button classes.
  As we mentioned above, button classes are not quite as restrictive in terms of what you can and can't style. This is because HierMenus takes--for the most part--a "hand's off" approach when it comes to the buttons themselves; it creates them and places your item text within them, but it does not apply any specific styling other than the button class names.

  The catch for this extended freedom is "more" images. Since HM does not alter the button dimensions, it does not automatically reserve space in the menu item itself for the display of the more image. Therefore, if you're using more images, be sure to reserve space in your button classes (via the padding-right or padding-left property, as appropriate) for the more images, otherwise your menu item text may overlap the image. More on this in the "Button Classes" section below.

• Standard Cross Frames and Content Pages.
  When using class names in a cross frames implementation, the style sheet classes that you refer to must be defined within the content frame of your frameset; i.e., in the same page that the menus will actually appear over. This is because the menus themselves are actually created as a part of the content frame, and in order to properly find the style sheet rules that are represented by the class names, those rules must exist in the same page the menus are appearing in. This is an exception to the typical "the content pages do not require modification" rule of standard cross frame implementations.

• Netscape 4.x not supported.
  Remember that class name support is not enabled in Netscape 4.x. If NS4 compatibility is important to you, then you may wish to supply alternate parameter settings for that browser.

That last point deserves a little bit of further discussion. If you happened to view our second menu example above in Netscape 4.x, what you saw would probably not have been pretty. This is because Netscape 4 ignores all the class name settings; but, unfortunately, it doesn't ignore the cleared font and color settings. The result, therefore, is typically a solid colored menu with no visible items (since Netscape 4 typically doesn't react well when setting a background color to "").

To counteract this, you can supply alternate color settings specifically for the Netscape 4.x browser. (Alternately, you could supply an entirely separate configuration file, if you prefer.) The basic technique for browser specific parameter settings was discussed back in Bulletin 4. Here's a look at what the above example might look like with Netscape 4 compatibility:

HM_f_SetMenus(
{
   MenuID:"Class2",
   IsHorizontal:true,
   MenuWidth:125,
   IsPermanent:true,
   MenuClass:"hmMenus",
   ItemClass:"hmItems",
   ItemClassOver:"hmItemsOver",
   ItemClassSelected:"hmItemsOver",
   CreateOnLoad:true,
   TopKeepInWindowX:false,
   TopKeepInWindowY:false,
   ScrollEnabled:false,
   FontFamily:(window.HM_NS4)?"Times":"",
   FontSize:(window.HM_NS4)?"14px":"",
   FontColor:(window.HM_NS4)?"white":"",
   FontColorOver:(window.HM_NS4)?"white":"",
   FontColorSelected:(window.HM_NS4)?"white":"",
   BGColor:(window.HM_NS4)?"#99CCFF":"",
   BGColorOver:(window.HM_NS4)?"navy":"",
   BGColorSelected:(window.HM_NS4)?"navy":"",
   TopMenuX:"HM_f_GetElementXY('placer2','x')",
   TopMenuY:"HM_f_GetElementXY('placer2','y')"
}
);

HM_f_SetItems(
{MenuID:"Class2",DisplayText:"Menu Item 1",LinkURL:"link1.html"},
{MenuID:"Class2",DisplayText:"Menu Item 2",LinkURL:"link2.html"},
{MenuID:"Class2",DisplayText:"Menu Item 3",LinkURL:"link3.html"},
{MenuID:"Class2",DisplayText:"Menu Item 4",LinkURL:"link4.html"}
);

Admittedly not as elegant, but at least Netscape 4.x viewers will now see a valid and usable menu. Note that there is no need to conditionally apply the actual class names themselves; as Netscape 4 simply ignores them, anyway.

Button Classes

Finally, let's have a look at button classes, also newly introduced in HierMenus version 6.

Button classes provide you with a means to add border rollover effects (such as swapping a border's style from outset to inset or changing a border's color on rollover) to individual menu items. Put simply, the "button" is the inner portion of the menu item, the portion within the limits defined by HierMenus' ItemPadding parameter. Unlike the menu items in general, buttons are created and styled entirely via the use of the button class names and your own style sheet rules. This provides you with great flexibility in the styling and effects of your item rollovers (but you must still keep in mind the restrictions mentioned above).

The most common use for button classes is the ability to add border rollover effects to menu items, so that is the use we will concentrate on in this mini-tutorial. Consider the following style sheet and menu configuration, and the menu it produces below it:

<style type="text/css">
   .hbutton1 {padding:2px 6px 2px 6px; border:2px solid #cccccc}
   .hbutton1over {padding:2px 6px 2px 6px; border:2px outset #eeeeee}
   .hbutton1select {padding:2px 6px 2px 6px; border:2px inset #eeeeee}
</style>
...
HM_f_SetMenuTemplate({
   MenuWidth:400,
   FontFamily:"MS Sans Serif",
   FontSize:"10px",
   FontWeight:"normal",
   FontColor:"black",
   FontColorOver:(window.HM_NS4||window.HM_IE4)?"white":"black",
   FontColorSelected:(window.HM_NS4||window.HM_IE4)?"white":"black",
   BGColor:"#cccccc",
   BGColorOver:(window.HM_NS4||window.HM_IE4)?"navy":"#cccccc",
   BGColorSelected:(window.HM_NS4||window.HM_IE4)?"navy":"#cccccc",
   BorderColor:(window.HM_NS4)?"black":"#eeeeee",
   BorderStyle:"outset",
   ButtonClass:"hbutton1",
   ButtonClassOver:"hbutton1over",
   ButtonClassSelected:"hbutton1select",
   MenuPaddingTop:2,
   MenuPaddingRight:2,
   MenuPaddingBottom:2,
   MenuPaddingLeft:2,
   MenuBGColor:"#cccccc",
   SeparatorSize:0,
   IsVariableWidth:true,
   MoreImagesVisible:false,
   ItemPadding:(window.HM_NS4||window.HM_IE4)?3:0,
   TopKeepInWindowY:false,
   TopKeepInWindowX:false,
   StatusDisplayLink:false,
   ClickStart:true,
   KeepHilite:true,
   ChildMenuY:"HM_default_y_position-3",
   CreateOnLoad:false,
   ScrollEnabled:false,
   ShowLinkCursor:true
})

HM_f_SetMenus({
   TopMenuX:"HM_f_GetElementXY('placer3','x')",
   TopMenuY:"HM_f_GetElementXY('placer3','y')",
   IsPermanent:1,
   IsHorizontal:1,
   PositionChild:"below",
   CreateOnLoad:true,
   MenuID:"Class3"
});
HM_f_SetItems(
   {MenuID:"Class3",DisplayText:"Menu Item 1",LinkURL:"item1.html",
            ChildID:"Class3_1"},
   {MenuID:"Class3",DisplayText:"Menu Item 2",LinkURL:"item2.html"},
   {MenuID:"Class3",DisplayText:"Menu Item 3",LinkURL:"item3.html"},
   {MenuID:"Class3",DisplayText:"Menu Item 4",LinkURL:"item4.html"}
);

HM_f_SetMenus({MenuID:"Class3_1"});
HM_f_SetItems(
   {MenuID:"Class3_1",DisplayText:"Menu Item 1",LinkURL:"item1.html"},
   {MenuID:"Class3_1",DisplayText:"Menu Item 2",LinkURL:"item2.html"},
   {MenuID:"Class3_1",DisplayText:"Menu Item 3",LinkURL:"item3.html"},
   {MenuID:"Class3_1",DisplayText:"Menu Item 4",LinkURL:"item4.html"}
);

Study the above example carefully, and notice especially these specific techniques:

• We've disabled HierMenus' own rollover and selected behavior, by setting the rollover and selected colors to be identical to the default colors. Without this, HierMenus would alter the background color of the entire menu item (beneath the menu button) when the item is rolled over or selected. While this might produce an interesting effect in some scenarios, it's not what we desire here.

• Several critical parameters are set conditionally for Netscape 4 and Internet Explorer 4. Remember that neither of these browsers support button classes, and the alternate settings allow those browsers to still produce a working, usable menu.

• We've disabled separator bars by setting SeparatorSize to 0.

• Since our item padding is controlled entirely within our button classes, we set HierMenus' own ItemPadding setting to 0.

• To ensure our buttons have some "clearance" all around the menu (but not between the menu items themselves) we've also set MenuPadding on the menu and a Menu Background Color (MenuBGColor).

• Our rollover and selected effect is completely controlled by our button class assignments, corresponding to the three button classes in our style sheet. Note especially that our three button classes are all dimensioned identically, with the same padding and border width settings. This is to ensure that, when rolled over, the text within the button "stays put" and is not shifted to accommodate the new dimensions of the displayed button. Again, we strongly recommend that your related class name assignments all use the same dimensions. To achieve the initial "no border" effect, we simply set the border color of the default button class to be the same as the menu item's default background color. And to see the result of the ButtonClassSelected assignment, click on the first menu item.

Example 2

One further, and common, example before we conclude this tutorial. Again, have a look at the style sheet entry, configuration file, and the resulting menu first:

<style type="text/css">
   .hbutton2 {padding:2px 9px 2px 6px; border:1px solid #FFCC99; 
              background-color:#FFCC99}
   .hbutton2over {padding:2px 9px 2px 6px; border:1px solid black; 
                  color:white; background-color:#996633}
   .hbutton2select {padding:2px 9px 2px 6px; border:1px solid black; 
                    color:white; background-color:#996633}
</style>
...
HM_f_SetMenuTemplate({
   MenuWidth:125,
   FontFamily:"MS Sans Serif",
   FontSize:"14px",
   FontWeight:"normal",
   FontColor:"black",
   FontColorOver:(window.HM_NS4||window.HM_IE4)?"white":"black",
   FontColorSelected:(window.HM_NS4||window.HM_IE4)?"white":"black",
   BGColor:"#FFCC99",
   BGColorOver:(window.HM_NS4||window.HM_IE4)?"#996633":"#FFCC99",
   BGColorSelected:(window.HM_NS4||window.HM_IE4)?"#996633":"#FFCC99",
   BorderColor:"#996633",
   BorderStyle:"solid",
   ButtonClass:"hbutton2",
   ButtonClassOver:"hbutton2over",
   ButtonClassSelected:"hbutton2select",
   MenuPaddingTop:2,
   MenuPaddingRight:2,
   MenuPaddingBottom:2,
   MenuPaddingLeft:2,
   MenuBGColor:"#FFCC99",
   SeparatorSize:0,
   MoreImagesVisible:true,
   ItemPadding:(window.HM_NS4||window.HM_IE4)?3:0,
   TopKeepInWindowY:false,
   TopKeepInWindowX:false,
   StatusDisplayLink:true,
   PositionChild:"below",
   ClickStart:false,
   KeepHilite:true,
   ChildOverlap:10,
   ChildOffset:3,
   ImageHorizSpace:3,
   ImageWidth:5,
   ImageHeight:9,
   IsVariableWidth:true,
   ScrollEnabled:false,
   ShowLinkCursor:true
})

HM_f_SetMenus({
   TopMenuX:"HM_f_GetElementXY('placer4','x')",
   TopMenuY:"HM_f_GetElementXY('placer4','y')",
   IsPermanent:1,
   IsHorizontal:1,
   CreateOnLoad:true,
   MenuID:"Class4"
});
HM_f_SetItems(
   {MenuID:"Class4",DisplayText:"Menu Item 1",LinkURL:"item1.html",
           ChildID:"Class4_1"},
   {MenuID:"Class4",DisplayText:"Menu Item 2",LinkURL:"item2.html"},
   {MenuID:"Class4",DisplayText:"Menu Item 3",LinkURL:"item3.html"},
   {MenuID:"Class4",DisplayText:"Menu Item 4",LinkURL:"item4.html"}
);

HM_f_SetMenus({MenuID:"Class4_1"});
HM_f_SetItems(
   {MenuID:"Class4_1",DisplayText:"Menu Item 1",LinkURL:"item1.html"},
   {MenuID:"Class4_1",DisplayText:"Menu Item 2",LinkURL:"item2.html"},
   {MenuID:"Class4_1",DisplayText:"Menu Item 3",LinkURL:"item3.html"},
   {MenuID:"Class4_1",DisplayText:"Menu Item 4",LinkURL:"item4.html"}
);

The example above is nearly identical to our earlier example, but we wanted to bring one subtle, but important difference to your attention. Specifically, note that we are using a more image (the triangular image that denotes the existence of a child menu) in the first item. Since HierMenus will not automatically alter the padding of your buttons, it is your responsibility to add padding to the button for the more images if you elect to use them (or just cancel the display of more images entirely via the MoreImagesVisible parameter setting). Without this additional padding, you run the risk of running your menu item text beneath the more image itself. In our example above, we adjust the right padding of the menu items to account for this:

   .hbutton2 {padding:2px 9px 2px 6px; border:1px solid #FFCC99; 
              background-color:#FFCC99}
...

(Note the "9px" for the right padding.) This provides us with enough breathing room in our menu items for the existence of the more image itself. If you do not want to apply the padding to all of your menu items, you can always add separate class names to your style sheet to apply to only those menu items that will spawn child menus.

Some final thoughts on button classes:

• In order to create a button in a menu item, you must supply a button class (ButtonClass). Without a button class, HierMenus will ignore any further button settings.

• When buttons are created, certain HierMenus activities are moved to be within the button itself, instead of within the menu item (remember that the button exists within the ItemPadding of the menu item; so there theoretically could be a small space between the edge of the button and the menu item that a user could rollover and/or click). These activities include embedded image rollovers, menu item clicks (to launch a new page or menu), more image rollovers, and link cursor displays (when ShowLinkCursor is true).