home / documentation / reference / mini-tutorial: menu event hooks

Menu Event Hooks

HierMenus version 6 introduces Menu Event Hooks, triggers that will fire your own custom developed JavaScript code at key points in HierMenus processing. This custom developed code allows you to synchronize some type of non-HierMenus activity with HierMenus, such as resizing an image to the exact size of a menu just after the menu has been created, or displaying, moving, and hiding additional custom elements of the page when certain menus are displayed, moved, or hidden. Since most event hooks are implemented as methods of the menu or item objects they are applied to, advanced developers can even interact with HierMenus' own menu configuration parameters for the menu or menu item via the this keyword of their custom functions. In this mini-tutorial, we'll be focusing on the general creation and setting of event hooks. Note that the mini-tutorial Custom Transitions deals specifically with the setTrans and killTrans event hooks, which are fundamentally different beasts than the other hooks (though they are defined and set in the same manner as the remaining hooks). And, for further detail on each of the event hooks specifically, we refer you to their reference page entries:

HM_OnMove
HM_OnVisibilityToggle
HM_OnCreateMenu
HM_OnMenuCreated
HM_OnItemHilite
HM_OnBuildMenus
HM_OnItemClick
HM_OnItemHover
HM_OnCreateItem
HM_OnItemCreated
HM_OnMenuOver
HM_OnMenuOut
HM_OnItemOver
HM_OnItemOut
HM_OnLink
setTrans
killTrans

Creating the Hook

Creating an event hook is simple, just create a normal JavaScript function. The function you create will need to be available (defined) before your configuration file is loaded (or within the configuration file itself, which is what we recommend), but other than that restriction you can place your custom function within just about any legal JavaScript block on your page. Here's an example function that might serve as a simple event hook to tell us (via the browser's status bar) that a menu has just been created:

function HM_fc_MadeMenu(menuEl) {
   window.status="Just created: "+this.MenuID;
}

What's this?

All event hooks are applied as methods to internal HierMenus objects, which means you can access the parameters of those objects by using the this keyword. In the example above, we retrieve the MenuID of the object using this.

Exactly what object this refers to depends on the event hook itself. Those that apply to menus are called as methods of HierMenus' menu object for the menu. Those that apply to items are called as methods of the menu item object. One hook in particular--HM_OnBuildMenus--is called as a method of the default menu object (in JavaScript terms, the menu object prototype object). Changing parameters via the this keyword in an HM_OnBuildMenus hook is virtually the same as calling HM_f_UpdateDefaults in the HierMenus configuration file. To determine which object this refers to in a specific hook, check out its reference page entry (and note the Applies To: section).

The parameters passed to your function (menuEl in the example above) also depend on the hook being processed. Again, refer to the reference page for the hook you are using for details.

Registering the Hook

To register the hook on a particular menu (or item, or globally to all menus or items) you assign it as a parameter in your HierMenus configuration file. For the most part this assignment is identical to any other parameter assignment. To set the example function above as a default hook on all menus, you could do this in your configuration file:

HM_f_UpdateDefaults({
   HM_OnMenuCreated:HM_fc_MadeMenu
});

Be sure that your actual assignment happens at a point at or earlier in the HierMenus' inheritance scheme for the actual object the hook applies to, otherwise the hook will be ignored. For example, the HM_OnMenuCreated hook applies only to menus; therefore, setting it on an item via a HM_f_SetItems call will be pointless. But setting it as a default, as in our example above, makes perfect sense; since all menus inherit from the default settings.

Custom Parameters

As described above, the this keyword provides you with instant access to the parameters of the menu or item object as appropriate. This includes all of the standard parameters that you can assign to menus and items as listed in our reference section.

What may not be immediately apparent, however, is that you can pass your own custom properties to a menu or item object in your configuration file, and then access those properties via your custom methods. This is because HierMenus transfers all properties encountered in configuration objects to its own appropriate, internal object whether it recognizes them or not (in fact, it doesn't even attempt to recognize them initially). Even though HM will not use the unrecognized property, it still passes it to the object definitions allowing you to later access them within your own event hooks.

Naming

When naming your custom functions, be sure to choose a name that will not conflict with HierMenus--or your own--JavaScript naming schemes. HierMenus does not use the HM_fc prefix on any of its own internal functions or variables, so it is a safe choice; as would be most schemes that do not begin with the HM_ prefix (which is used on nearly all HierMenus global variables and functions). As far as custom properties go, we recommend a unique prefix based on your site initials, or something of the like (although you're welcome to use the HM_fc prefix for those, too). In the remainder of this tutorial we'll use the hmc_ (HierMenus Custom) prefix for any custom parameters.

Synchronize, not Override

Most of the event hooks are intended to complement (or perhaps, in advanced circumstances, modify) HierMenus own behavior where the hook is applied. For example, if you hook a menu's HM_OnVisibilityToggle event, then you can synchronize the visibility of your own custom elements to a HierMenus menu. But you can't, simply by hooking HM_OnVisibilityToggle, prevent HierMenus from actually performing the visibility toggle on the menu.

The exceptions to this rule include setTrans and killTrans, which replace standard HierMenus functionality and are covered at length in the Custom Transitions Mini-Tutorial; and HM_OnLink, which will, if it returns false, prevent HierMenus from following a menu item link.

Examples

Here are some example methods that you may wish to try out in your own HierMenus implementations.

Adjust an image to the size of a menu.

// Doesn't work in Netscape 4.x
function HM_fc_MenuCreated() {
   if(!document.getElementById&&!document.all) return;
   var theImage=document.getElementById?
                document.getElementById(this.hmc_ImagePlacer):
                document.all(this.hmc_ImagePlacer);
   if(theImage) {
      theImage.style.width=(HM_f_GetMenuDimension(this.MenuID,1))+"px";
      theImage.style.height=(HM_f_GetMenuDimension(this.MenuID,0))+"px";
   }
}

// register as follows:
...
   HM_OnMenuCreated:HM_fc_MenuCreated,
   hmc_ImagePlacer:"MenuPlacerImage",
...

The above routine allows you to resize an in-page image to the same dimensions as the menu itself. It will be called as soon as the menu is finished being created. Note that for the above routine to work, you'll need to have the HM_f_GetMenuDimension routine within your HM_Loader.js file.

Also note the use of the custom property hmc_ImagePlacer. This is a parameter that is not recognized by HierMenus, so you would need to supply it yourself. Alternately, you could just make sure that your images have ids that are based on the MenuID and then use that:

// Doesn't work in Netscape 4.x
function HM_fc_MenuCreated() {
   if(!document.getElementById&&!document.all) return;
   var theImageID=this.MenuID+"placer";
   var theImage=document.getElementById?
                document.getElementById(theImageID):
                document.all(theImageID);
   if(theImage) {
      theImage.style.width=(HM_f_GetMenuDimension(this.MenuID,1))+"px";
      theImage.style.height=(HM_f_GetMenuDimension(this.MenuID,0))+"px";
   }
}

The tradeoff, of course, is that the id that you apply to the target image itself must contain the MenuID for the target menu. In our example above, assuming the MenuID is "ProductsMenu", then the image id would have to be "ProductsMenuplacer."

Assign alternating background colors to items.

function HM_fc_CreateItem() {
   var theColor=(this.ItemCount%2==0)?"#ffffff":"#efefef";
   this.BGColor=theColor;
}

// register as follows:
...
   HM_OnCreateItem:HM_fc_CreateItem,
...

In the above code, note that we refer to the HierMenus internal property ItemCount to determine if we're on an odd or even menu item for the menu. It must be stated here that we will not document every internal structure of the HierMenus script; if you choose to reference HierMenus internal variables or methods in your own coding schemes then you must do so at your own risk (though we will, of course, attempt to keep variables in the same place as best as possible in subsequent version 6 releases).

Fix the pixelate transition.

function HM_fc_FixPixelate(menuEl) {
      if(!window.HM_IE55) return;
      var theFilter=menuEl.filters.item(this.HideTransitionIndex);
      theFilter.apply();
      theFilter.play();
}

// register as follows:
...
   HM_OnMenuCreated:HM_fc_FixPixelate,
...

The Internet Explorer specific Pixelate transition often doesn't work properly on the first display of a menu. The above code usually corrects this problem. Unfortunately, this code requires the existence of an IEHideTransition on the menu as well as an IEShowTransition.

Adding a cone light.

function HM_fc_SetLight(menuEl) {
   if(!window.HM_IE55) return;
   var theFilter=menuEl.filters.item(0);
   var theWidth=HM_f_GetMenuDimension(this.MenuID,1);
   var theHeight=HM_f_GetMenuDimension(this.MenuID,0);
   theFilter.addCone(-200,-200,1,theWidth+10,theHeight+10,
                     153,153,153,60,80);
}

// register as follows:
...
   HM_OnMenuCreated:HM_fc_SetLight,
...

The Internet Explorer specific Light filter is controlled entirely by scripting; while you can add the filter itself to the menu via the standard IEFilters configuration parameter, without additional scripting no actual light effect will be applied to the menu (and in fact, the menu will typically appear "in the dark;" i.e., black and unreadable). The above code will be called just after the menu is created, adding a cone light to the Light filter.

Examples in the HM_Loader.js File

Several of the custom functions in the HM_Loader.js file are intended to be utilized as event hooks. While we won't bother replicating the full code here, we will provide example registrations should you wish to try them.

Using the Internet Explorer IFRAME mask technique to allow menus to cover select boxes and other windowed elements.

// register as follows:
...
   HM_OnMenuCreated:HM_f_IEMaskCreate,
   HM_OnMove:HM_f_IEMaskMove,
   HM_OnVisibilityToggle:HM_f_IEMaskToggle,
...

The above settings combine to create an IFRAME mask in Internet Explorer 5.5 and later that allows menus to covers select boxes and other windowed elements. See the setup instructions and FAQ #1 for further details.

Implementing Sliding Menus

// register as follows:
...
   setTrans:HM_f_SetSlide,
   killTrans:HM_f_KillTrans,
   SlideInFrom:"top",
...

Sliding menu implementation and specifics are covered in the Custom Transitions Mini-Tutorial.