home / documentation / upgrade

Upgrading From HierMenus 4/5 to Version 6

Many changes were made to HierMenus version 6 to accommodate its new feature set. For those of you familiar with HierMenus version 4/5 implementations, this guide will help you to both know what the changes are, as well as provide a series of steps to assist you with the upgrade process. Note that this page is not intended to present all of the new features of HierMenus 6; for a listing of new features please see the HierMenus 6 Release Bulletin.

What's Changed

For the do-it-yourselfers who just want the facts and only the facts, here's an at-a-glance listing of all the primary changes in HierMenus version 6.

New Configuration File

By far the biggest single change to HierMenus 6 is our new, easier to manage configuration file, which allows for named menus (no more 1_2_3_4 naming schemes) and the setting of parameters by name (you no longer have to remember which "slot" in the array a particular parameter occupies and count commas up to that slot). Additionally, a built-in inheritance scheme allows you to easily set parameters on a global basis that are then inherited by all menus defined, or a menu specific basis that are then inherited by all items of the menu. Visit step 2 of our setup instructions for further details on the new configuration file layout.

Our Array Conversion Tool will give you a great head start in the transferring of your existing arrays to the new configuration file format.

Browser Compatibility

Browser compatibility in version 6 remains the same as it was in version 5, with three important exceptions.

Internet Explorer on the Macintosh is no longer supported by HierMenus. Despite our best efforts, we continue to uncover menuing problems in this browser for which we can discover no graceful workarounds. This, combined with Microsoft's decision to produce no new versions of Internet Explorer for Mac led us to our decision to drop support for Mac IE entirely in HierMenus version 6.

Konqueror 3.x is disabled in HierMenus version 6. Unlike Macintosh Internet Explorer v5, it is our hope that we can reinstate Konqueror support in HierMenus in a later maintenance release. For now, however, we've uncovered several key problems in our Konqueror implementation that we were unable to resolve in time for this initial publication. We will continue to work on these issues and hope to provide you with a Konquerer capable version in the near future.

Finally, as mentioned above, note that not all of our new features are implemented in all browsers. See our compatibility page for basic support of each of the major new features, as well as the reference entries for the parameters corresponding to the features, each of which now states which browsers they are or are not compatible with.

Global Variables Specified In Configuration File

With a few exceptions (6, to be exact) global parameter defaults (formerly represented by the HM_GL_xxx series of variables) are no longer specified in the HM_Loader.js file. Rather they are set via the HM_f_UpdateDefaults command in the configuration file. The 6 global parameters that must be set in HM_Loader.js are described in step 1 of the setup instructions.

Page Specific Variables Changed

Similar to the above, page specific variables also have a new syntax, which is described in the advanced topic Page Specific Variables in the setup instructions.

Configuration File After Scripts, Not Before

For those dynamically generating a configuration file apart from the standard HierMenus loading process, you must now generate the file after the HierMenus execution scripts are loaded, not before (unless you are continuing to use arrays, in which case they should still be before the HM_Loader.js call).

No Restrictions On Permanent/Horizontal/Position Under Menus

In v4/5 of HierMenus, permanently displayed menus (IsPermanent equals true), and position under menus were never allowed to be scrollable and never followed the standard HierMenus keep in window behavior. Additionally, horizontal menus were also never allowed to be scrollable. In HM 6, these restrictions have been removed. If you want to emulate the version 5 behavior, you will therefore need to set your permanent, horizontal, and/or position under menus like this:

IsPermanent:true,
ScrollEnabled:false,
TopKeepInWindowX:false,
TopKeepInWindowY:false,
ChildKeepInWindowX:false,
ChildKeepInWindowY:false

Position Under

Speaking of which, the menu array parameter formerly known as position under is now called PositionChild and accepts two possible values: above and below.

Top vs. Child

In the new configuration file, a single menu can serve as both a top level menu and a child menu (and in fact, it can serve as a child menu to multiple parent items). This necessitated the separation of several parameters into "Top" vs. "Child" entries; i.e., the "Top" version of the parameter is applied to the menu when it is being used as a top level menu, and the "Child" version of the parameter is used when the menu is being utilized as a child menu. The parameters so split include: TopMenuX, TopMenuY, ChildMenuX, ChildMenuY, TopUponDisplay, TopUponHide, ChildUponDisplay, ChildUponHide, TopKeepInWindowX, TopKeepInWindowY, ChildKeepInWindowX, and ChildKeepInWindowY.

FontSize

FontSize now accepts length units ("px", "em", etc.).

FontBold, FontItalic

FontBold is now called FontWeight, and FontItalic is now called FontStyle. Each of the parameters now accepts as valid values any valid CSS setting for their corresponding CSS properties.

MenuID, ChildID

All menus must now include a MenuID, which identifies the menu. Child menus are assigned to menu items by assigning their ChildID parameter to a valid, existing MenuID.

CreateChildrenJIT, CreateMenusOnLoad, CreateTopOnly Obsolete

CreateChildrenJIT, CreateMenusOnLoad, and CreateTopOnly are now obsolete; replaced instead with the single variable CreateOnLoad, which, like most other parameters, can be assigned independently on a menu-by-menu basis.

TopSecondsVisible, TreeSecondsVisible Obsolete

TopSecondsVisible and TreeSecondsVisible are now obsolete; replaced instead with the single variable MilliSecondsVisible, which, like most other parameters, can be assigned independently on a menu-by-menu basis. Separate top vs. tree hiding times are no longer available; instead, the entire menu tree will be hidden simultaneously based on the MilliSecondsVisible setting of the last menu rolled over.

HoverTimeTop, HoverTimeTree Obsolete

HoverTimeTop and HoverTimeTree are now obsolete; replaced instead with the single variable HoverTimeMilliSeconds, which, like most other parameters, can be assigned independently on a menu-by-menu basis.

HM_a_TreesToBuild

The HM_a_TreesToBuild parameter has been replaced with MenusToBuild.

ImageSize

ImageSize is now known as ImageWidth.

mouse_x_position / mouse_y_position

The keywords formerly known as mouse_x_position and mouse_y_position are now known as HM_default_x_position and HM_default_y_position. see the Menu Positioning Mini Tutorial for further information.

Some Optimized Variable Names Changed

To accommodate the new application of global parameters as object properties instead of global variables, some optimized parameter names have changed. This only effects you if you're using the optimized code set and have applied your own custom routines or functions that interact with HierMenus internal variables. See the new cross-reference chart for a complete listing.

Upgrade Steps

With the above changes in mind, you should follow these general steps when upgrading from version 4/5 of HierMenus to version 6.

1. Install and setup the HierMenus 6 scripts on your server in accordance with step 1 of the version 6 setup instructions. We recommend creating an entirely new directory for this step, so that you can--at least temporarily--keep your new configurations entirely separate from your old.

2. Read through the documentation for the configuration file (step 2 of the setup instructions) to get a feel for the layout of the new configuration commands and syntax. Then use our Conversion Tool to perform the initial conversion of your existing arrays into the HM6 configuration file format. Finally, review the results of the conversion in light of the step 2 documentation, and install your resulting configuration file on your server as in the step 2 instructions. It's important that you review the results of your configuration file before directly implementing to ensure that the transfer was made as expected. The conversion tool is quite thorough, but will not necessarily create the most efficient configuration file possible. For example, it will generate a new HM_f_SetMenuTemplate call with each new menu tree definition; which, if all your menu trees are designed the same way, may not be necessary (but will still work, of course). Also, if you have an HM_o_RolloverImages object defined in your existing array file, copy it as is (the HM6 syntax is identical) to the new configuration file. If you don't know what HM_o_RolloverImages is then you aren't using it.

3. Convert page specific variables--if you still need them--to the new syntax. See the advanced topic Page Specific Variables for further information (and note that many, many existing HierMenus version 4/5 implementations misuse page specific variables badly. Both the advanced topic described above and our array conversion tool discuss this point).

4. Apply HierMenus to your test pages (always work with test pages first) as per the instructions in step 3 of the setup instructions. With the exception of the alternate cross frames implementation method (new to HierMenus version 6) you will find these instructions to be syntactically identical to the version 4/5 application instructions; including the loading of the HM_Loader.js file as well as the onmouseover / onmouseout commands for pop up menus. The only differences include:

   • The popUp and popDown dummy functions are no longer officially documented (but you may continue to use them if you like; simply continue to include them in your dummy functions declaration script).
   • When specifying a menu name in your HM_f_PopUp and HM_f_PopDown calls, you must now use the menu's MenuID. If you used the conversion script above, you will find that the MenuID was automatically assigned in the same manner as HM 4/5 (i.e., HM_Menu1, HM_Menu1_2_4, etc.). But in any event, the elMenu1, elMenu1_2_4 etc. syntax is no longer supported in HierMenus 6; you must refer to the actual MenuID in your HM_f_PopUp and HM_f_PopDown calls.

As always, feel free to contact us if you run into any snags with this process.