home / documentation / reference / menustobuild

MenusToBuild

Description:

An array of menu IDs to create immediately when the page loads.

Value:

JavaScript array reference, or JavaScript expression that returns a JavaScript array reference.

Applies To:

Globally.

Browser Compatibility:

MenusToBuild is supported in all browsers.

Comments:

By default, HierMenus decides which menus to create when the page loads based on their individual CreateOnLoad settings. MenusToBuild allows you to override that behavior. When MenusToBuild is set, HierMenus will build only those menus with IDs in the MenusToBuild array. In other words, HierMenus assumes all the menus in the MenusToBuild array have CreateOnLoad set to true, while all other menus on the page have CreateOnLoad set to false.

MenusToBuild is provided purely for backwards support with the HierMenus version 4/5 HM_a_TreesToBuild array. Since CreateOnLoad can now be assigned on a menu by menu basis, it has little to no use beginning in HierMenus version 6.

The easiest way to set MenusToBuild is to use array literals; i.e., to force HM to build only the menus with IDs "hm_1", "hm_3", and "hm_6" on page load (regardless of HM parameter settings or other menus defined in the configuration file):

MenusToBuild:["hm_1","hm_3","hm_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 MenusToBuild we recommend this alternate lingo:

HM_a_TreesToBuild = [];
HM_a_TreesToBuild[0]="hm_3";
....
// now in HM_f_UpdateDefaults or in the HM_o_PageDefaults object
MenusToBuild:HM_a_TreesToBuild,

MenusToBuild will be most commonly used as a page-specific default, since applying it as a global default is no different than assigning CreateOnLoad to the individual menus you wish to build. See the setup instructions for further details on page specific variables.

MenusToBuild will only work properly when it is set as a default, i.e., via the HM_o_PageDefaults object or HM_f_UpdateDefaults. Applying MenusToBuild to a menu template, menu, or menu item will have no effect.

Examples:

// Ok:
MenusToBuild:["hm_products","hm_services"],
MenusToBuild:[],
MenusToBuild:(window.prodPage)?["hm_products"]:[],
    // if the user defined variable "prodPage" is true,
    // then build only hm_products

// Incorrect:
MenusToBuild:'["hm_products","hm_services"]',
    // do not quote array literals
MenusToBuild:'(window.prodPage)?["hm_products"]:[]', 
    // no quoted expressions

Default:

[]

See Also:

CreateOnLoad