 |
|
|
|
 |
| Bulletins |
| About |
| Documentation |
| FAQ |
| Samples |
| Known Issues |
| Technology Jobs |
|
|
 |
 |
|
home / documentation / setup / Using the Custom Code in HM_Loader.js Using the Custom Code in HM_Loader.js In the past, we've introduced (and/or alluded to) several helpful JavaScript routines and techniques that you could utilize to augment the native capabilities of HierMenus. In HierMenus version 6, we've included several of these routines directly within HM_Loader.js, providing you with immediate access to them should you decide you would like to use them in the future. Since the routines are within HM_Loader.js, and HM_Loader.js is loaded (one way or another) on every page of your site, you can access these routines at any time you choose. This ease of access is not without one catch, however; including these routines within the HM_Loader.js file lengthens the size of that file, increasing the total bytes that must be downloaded by the user in order to see your menus. This increase in download time is generally only noticeable the first time your users hit your site (from that point on the scripts will typically be retrieved from the user's browser cache); but nonetheless you can lessen this impact by removing from the HM_Loader.js all those routines that you will not actually be using. In order to know whether you will want to use the functions or not, you will need to know what what they do. That's the topic of the remainder of this page. Where Are They?All of the custom code in HM_Loader.js is located in the section of the page which begins with this comment: // Custom functions. (There may be additional writing on the comment line, but it will always start with the above.) The custom function block ends with this line: // End custom functions Within this section are each of the routines described below, each separated with its own comment block describing its basic use and function. HM_f_CenterMenuHM_f_CenterMenu returns the centered left position of a menu within the user's current browser document. It is typically called from within the TopMenuX/ChildMenuX parameter settings. To use it, you pass to it the MenuID of the menu you are positioning. HM_f_CenterMenu will retrieve that menu, examine its width, compare that width to the current width of the browser document, and return the appropriate integer for use in the left (X) setting of the menu. Example settings: TopMenuX:"HM_f_CenterMenu('hm_m_main')",
// center hm_m_main when displayed as a top level menu
ChildMenuX:"HM_f_CenterMenu('hm_m_products')",
// center hm_m_products when displayed as a child menu
Further information: TopMenuX HM_f_SetSlide / HM_f_KillSlideUsed together, these routines are an example of a "custom transition" and can be used to implement sliding menus on your site. They are one of the main topics of the Custom Transitions Mini Tutorial and are controlled by the SlideInFrom/OutTo, SlideInInterval/OutInterval, and SlideInPercent/OutPercent parameters, as well as the setTrans/killTrans event hooks. Example settings: setTrans:HM_f_SetSlide, killTrans:HM_f_KillSlide, SlideInFrom:"left", // menus slide into display from the left SlideInInterval:50, SlideInPercent:5, // slow (relatively) sliding effect Further information: setTrans HM_f_GetElementXYHM_f_GetElementXY retrieves the current location of an in-page element, such as an existing image or link. You can then use this position as the base from which to position your own menus. While unfortunately not perfect, HM_f_GetElementXY does work properly in a great number of settings. HM_f_GetElementXY is described at length in the Menu Positioning Mini Tutorial. Example settings: HM_f_SetMenus({
MenuID:"MyMenu",
IsPermanent:true,
TopMenuX:"HM_f_GetElementXY('image1','x')",
TopMenuY:"HM_f_GetElementXY('image1','y')",
ChildOffset:10,
ChildOverlap:20
});
Further information: TopMenuX HM_f_GetMenuDimensionUsing HM_f_GetMenuDimension, you can position the top/left corner of your menu based on the current width or height of the menu itself, and thus achieve bottom or right-edge based menu positioning. HM_f_GetMenuDimension was covered in detail in Bulletin 11, when it was introduced back in the HierMenus version 5 release cycle. We refer you to that discussion for further information. Note that when we intially released the code it was called HM_fc_GetMenuDimension, but when you refer to the function in HierMenus version 6, you must do so via HM_f_GetMenuDimension. Additionally, the first parameter passed to HM_f_GetMenuDimension should be the full MenuID of the menu in question, not just its menu "number" (which has no relevance in HierMenus version 6 configuration files). Other than those differences, the new version 6 function works in the same manner as described in Bulletin 11. Example settings: HM_f_SetMenus({
MenuID:"MyMenu",
IsPermanent:false,
RightToLeft:true,
TopMenuX:"HM_default_x_position-HM_f_GetMenuDimension('MyMenu',true)",
// pop up menu to the left and below mouse
ChildOffset:10,
ChildOverlap:20
});
Further information: TopMenuX HM_f_ToggleElementListHM_f_ToggleElementList can be used to "hide" (toggle the visibility of) a list of elements on the page, or all of a particular type of element on the page. It can be used, for example, to hide all the form select elements on a page, thereby avoiding the infamous "Menus covered by page elements" problem as described in FAQ #1. (Another possible solution to the problem which is specific to IE5.5/6 is presented below, in the form of the HM_IEMaskCreate, HM_IEMaskMove, and HM_IEMaskToggle functions.) HM_f_ToggleElementList was covered in detail in Bulletin 6, when it was introduced back in the HierMenus version 5 release cycle. We refer you to that discussion for further information. The version of HM_f_ToggleElementList within the HM6 loader file uses the same syntax as the original version presented in Bulletin 6. Example settings: HM_f_SetMenus({
MenuID:"MyMenu",
IsPermanent:false,
TopUponDisplay:"HM_f_ToggleElementList(false,['select'],'tag')",
// hide all selects when this menu is displayed
TopUponHide:"HM_f_ToggleElementList(true,['select'],'tag')",
// show all selects when this menu is displayed
ChildOffset:10,
ChildOverlap:20
});
Further information: TopUponDisplay HM_f_IEMaskCreate / HM_f_IEMaskToggle / HM_f_IEMaskMoveHM_f_IEMaskCreate, HM_f_IEMaskToggle and HM_f_IEMaskMove can be used together to implement an IFRAME based technique that allows windowed elements, such as select elements, Flash, or Java Applets, to be covered by Menus in Internet Explorer 5.5 and Internet Explorer 6. The same technique will not work in other browsers, and the functions therefore do nothing unless they are executed by Internet Explorer 5.5 or 6. This IFRAME masking technique potentially provides an alternate solution to the "Menus covered by page components" problem as described in FAQ #1, albeit an alternate solution which is specific to these two browsers only. In Internet Explorer 5.5 and later, iframe elements support a very unusual behavior. They can both cover windowed elements on a page, as well as be covered by dynamically generated elements, such as our menus, depending on the z-order of the elements. Therefore, by inserting an iframe between the menu and the page elements, the elements become masked by the iframe while the menu is allowed to be displayed over the iframe. Microsoft has documented this behavior in their knowledge base: MSDN - IFRAMES and Windowed Element zIndex settings You implement the HM_f_IEMaskCreate, HM_f_IEMaskToggle and HM_f_IEMaskMove functions by assigning them to the HM_OnMenuCreated, HM_OnVisibilityToggle, and HM_OnMove Menu event hooks for the menu you wish to mask. Alternately, you can assign the masks to all menus by assigning them via an HM_f_UpdateDefaults call; but keep in mind that each time you call the HM_IEMaskCreate function an additional element is dynamically generated and inserted into the page. Therefore, for best results, you should limit the IFRAME masking to only those menus that you know will actually need it; i.e., only those menus that actually will be displayed over windowed elements. For more on Menu Event Hooks, review the Menu Event Hooks Mini-Tutorial. Example settings: HM_f_SetMenus({
MenuID:"MyMenu",
IsPermanent:false,
TopUponDisplay:(window.HM_IE55)?null:
"HM_f_ToggleElementList(false,['select'],'tag')",
// if browser is not IE5.5 or 6
// hide all selects when this menu is displayed
TopUponHide:(window.HM_IE55)?null:
"HM_f_ToggleElementList(true,['select'],'tag')",
// if browser is not IE5.5 or 6
// show all selects when this menu is displayed
HM_OnMove:HM_f_IEMaskMove,
HM_OnVisibilityToggle:HM_f_IEMaskToggle,
HM_OnMenuCreated:HM_f_IEMaskCreate,
ChildOffset:10,
ChildOverlap:20
});
Further information: TopUponDisplay |
