home / bulletins / 7 / page 2

[previous] [next]

Menu Creation Options

The new menu creation options available in HM 5.2 allow you to control the creation of menus on page load, as well as whether or not child menus of a menu tree are created recursively (all at the same time) or individually (as they are requested by the user).

 HM_GL_CreateMenusOnLoad and HM_PG_CreateMenusOnLoad

Description:

Indicates whether or not HM should attempt to create menus (based on the existing menu arrays) as soon as the HTML page completes its loading process. If true, menus will be created (subject to HM_xx_CreateTopOnly and HM_xx_CreateChildrenJIT). If false, no menus will be immediately created on page load; instead, menus will be created on-the-fly as they are needed when the user rolls over the links that spawn the menus.

Value:

Boolean (true/false,1/0) or any expression that evaluates to a true/false value.

Comments:

Whether true or false, how many menus are actually created (whenever they are created) is governed by the HM_xx_CreateTopOnly and HM_xx_CreateChildrenJIT parameters. HM_xx_CreateMenusOnLoad only controls whether or not menus are created when the HTML page loads.

For stability reasons, we recommend that this parameter always be set to true in Macintosh Internet Explorer 5. An example of this type of conditional setting can be seen below.

Examples:

Menus are created on load:

HM_GL_CreateMenusOnLoad = true;

Menus are not created on page load:

HM_GL_CreateMenusOnLoad = 0;

Menus are created on load in Macintosh Internet Explorer 5, but not created on load in all other browsers:

HM_GL_CreateMenusOnLoad = (HM_IE&&HM_Mac) ? 1 : 0;

Further examples and scenario discussions are presented lower on this page.

Default:

True. HM always attempts to create menus on page load by default.

 HM_GL_CreateChildrenJIT and HM_PG_CreateChildrenJIT

Description:

When creating a menu tree, HM checks the HM_xx_CreateChildrenJIT parameter to decide how deeply wihin the menu tree to immediately create child menus. If this parameter is set to true, then only the immediate child menu being requested is created; if false then all child and grandchild menus of the menu being requested are created (subject to the setting of HM_xx_CreateTopOnly).

The net effect of setting HM_xx_CreateChildrenJIT to true is that all child menus on a page are created only when the user specifically requests to use them for the first time.

Value:

Boolean (true/false,1/0) or any expression that evaluates to a true/false value.

Comments:

Note the relationship of HM_xx_CreateChildrenJIT to HM_xx_CreateTopOnly. When HM_xx_CreateChildrenJIT is true, then HM_xx_CreateTopOnly is also, by definition, true; since whenever HM attempts to create a top level menu the HM_xx_CreateChildrenJIT setting will force it to stop immediately after the top-level menu is created. When HM_xx_CreateChildrenJIT is false, then whether or not HM creates only the topmost menu in a menu tree or the entire tree at once depends on the value of HM_xx_CreateTopOnly.

Examples:

Child menus are created as needed:

HM_GL_CreateChildrenJIT = true;

All child menus are created when the menu tree is created:

HM_GL_CreateChildrenJIT = 0;
HM_GL_CreateTopOnly=0;

Top level menus are created individually, the remaining menus in each menu tree are created all at once when the user first requests that tree:

HM_GL_CreateChildrenJIT = 0;
HM_GL_CreateTopOnly=1;

Child menus are created as needed in all browsers but Mac IE5:

HM_GL_CreateChildrenJIT = (HM_IE&&HM_Mac) ? 1 : 0;

Further examples and scenario discussions are presented lower on this page.

Default:

False. By default, HM attempts to create all child menus for a tree when the tree itself is created.

 HM_a_TreesToBuild

Description:

Collection (array) of top level menus that should be built when the page loads. This overrides the HM_xx_CreateMenusOnLoad parameter setting and HM's normal menu building process.

Value:

Array of menu tree IDs.

Comments:

HM_a_TreesToBuild does not come in global and page specific flavors. Rather, HM_a_TreesToBuild is always interpreted as a global parameter.

HM_a_TreesToBuild is available in HM v4.x and later; but was not officially documented until HM v5.2.

The easiest way to set HM_a_TreesToBuild is to use array literals; i.e., to force HM to build only menu trees 1, 3, and 6 on page load (regardless of HM parameter settings or other menu trees defined in HM_Arrays.js):

HM_a_TreesToBuild = [1,3,6];

Note that assigning a single menu entry via this method can be problematic in Netscape 4.x, however; therefore, when only one menu is to be set in HM_a_TreesToBuild we recommend this alternate lingo:

HM_a_TreesToBuild = [];
HM_a_TreesToBuild[0] = 3;

In cross-frame scenarios HM_a_TreesToBuild represents the menus that will be built immediately when each new content page is loaded (for browsers that support the onload event of frames) or when the user rolls over a menu-spawning link after hitting--and returning from--a page outside the site's domain.

Examples:

Create menu trees 1 and 5 on page load:

HM_a_TreesToBuild = [1,5];

Create only menu tree 8 on page load:

HM_a_TreesToBuild = [];
HM_a_TreesToBuild[0] = 8;

Further examples and scenario discussions are presented lower on this page.

Default:

Undefined. If no user defined setting is found for HM_a_TreesToBuild then HM assumes all top level menus defined in HM_Arrays.js should be built; unless HM_CreateMenusOnLoad is false, in which case HM assumes that no top level menus should be built on page load.

Sample Configurations

A few sample configuration scenarios will help to clarify the above new parameters and how they interact with one another.

1. All menus created on page load:

   HM_GL_CreateMenusOnLoad=true;
   HM_GL_CreateTopOnly=false;
   HM_GL_CreateChildrenJIT=false;

   This is the default menu loading behavior for HierMenus, and the one we recommend for smaller menu sets (8-10 smallish menus or less). The menu build process will cause a slight delay in the loading of the page, but it's typically negligible. And having all the menus created on page load means they will respond instantly when requested by the user.

   Since this is HM's default behavior, this is also what will happen if the three variables above are omitted entirely.

2. Top level menus created on page load, remaining portion of each menu tree created all at once when first requested:

   HM_GL_CreateMenusOnLoad=true;
   HM_GL_CreateTopOnly=true;
   HM_GL_CreateChildrenJIT=false;

   This will be a common choice for those who use a single, permanently visible menu with multiple (8-10 or more) choices; where the individual choices are not deeply nested (i.e., 1 or at most 2 menu levels are included beneath the main menu choices). The initial top level menu is created and displayed immediately on page load, but the remaining portions of each menu tree are not built until the user rolls over the top level choice for that menu tree for the first time. When the remaining portion of the menu tree is created, however, it is created in its entirety; including child and grandchild menus of the tree, if they exist.

3. All menus are created on the fly, when they are requested:

   HM_GL_CreateMenusOnLoad=false;
   HM_GL_CreateChildrenJIT=true;

   This new setting will be a popular choice for large and/or deeply nested menu sets. With this configuration, no menus are built on page load. Instead, menus are built one at a time as their parent items or links are rolled over on the page. There is a small delay as each menu is built for the first time; but this delay is preferable, rather than a mass delay on page load as all the menus are being built.

4. Menu tree 4 is created in its entirety on page load. No other menus are created:

   HM_a_TreesToBuild=[];
   HM_a_TreesToBuild[0]=4;

   Here, we've forced HM to override its normal menu build process, and specified Menu tree 4 (HM_Arrays4) as the menu tree to build. No other menus will be built on this page (either on page load or later) even if multiple other menu definitions appear within the HM_Arrays file.

5. The top level menus of trees 2 and 6 are created on page load. All other linked-to menus are created as needed:

   HM_a_TreesToBuild=[2,6];
   HM_GL_CreateMenusOnLoad=false;
   HM_GL_CreateChildrenJIT=true;

   Note how the inclusion of HM_a_TreesToBuild allows you to force a certain menu (or menus) to build immediately on page load, while the remaining menus are not built until they are requested. If you have both a permanently visible menu (that must be immediately be displayed) and a large number of pop-up menus spawned from other links on the same page, this is the choice for you.

Menu creation choices are not the only new parameters available in HierMenus 5.2. On the next page, we examine another new feature you've requested of us: the ability to override HM's default "Keep In Window" behavior for all or specific top level menus.

[previous] [next]