home / documentation / setup / configuration files / hm_f_setmenus

HM_f_SetMenus

HM_f_SetMenus registers actual menus in the HierMenus system. Note that individual menu items are not set via HM_f_SetMenus; only the actual menu containers themselves. As described on the previous page, all parameters set specifically on a menu override the global defaults for that menu. Additionally, each menu item that is later attached to this menu will automatically inherit all the parameters assigned to the menu.

To call HM_f_SetMenus, use the following syntax:

HM_f_SetMenus(
  {Menu1ParameterName1:Menu1ParameterValue1,
   Menu1ParameterName2:Menu1ParameterValue2,
   ...
   Menu1ParameterNameN:Menu1ParameterValueN},

  {Menu2ParameterName1:Menu2ParameterValue1,
   Menu2ParameterName2:Menu2ParameterValue2,
   ...
   Menu2ParameterNameN:Menu2ParameterValueN},

  ...

  {MenuNParameterName1:MenuNParameterValue1,
   MenuNParameterName2:MenuNParameterValue2,
   ...
   MenuNParameterNameN:MenuNParameterValueN}
);

Note especially the following:

• Unlike HM_f_UpdateDefaults and HM_f_SetMenuTemplate, HM_f_SetMenus allows for the registration of multiple menus with a single HM_f_SetMenus call. You may also elect to register only one menu at a time with HM_f_SetMenus, which we expect will be a common choice. The parameter list for each new menu must be enclosed in curly brackets ({}). Each menu (each curly bracket pair) must be separated by a comma. Like the parameter name:value pairs (described below) the final menu setting in HM_f_SetMenus must not be followed by a comma.

• A single pair of curly brackets ({}) encloses each list of parameter:value pairs. All of the menu settings (all of the curly bracket sets) are together enclosed in a pair of parentheses (). It is these parentheses that indicate to JavaScript that a function is being executed and therefore the left (opening) parentheses must be immediately after the HM_f_SetMenus statement itself. (You don't need to know how or why that is; just remember that both the single pair of parentheses (outside) and the curly brackets surrounding each menu setting are necessary.)

• The HM_f_SetMenus({}) command itself is followed by a semi-colon (after the closing, or right parentheses).

• Each parameter:value pair must be separated by a comma. The last name:value pair in the list must not be followed by a comma. Remember the HierMenus configuration file golden rule: Whenever a list of items is specified (in this case name:value pairs) each entry in the list must be separated by commas, but the last entry in the list must not be followed by a comma. JavaScript syntax requires this; if you vary from this rule you will find that your menus may not work at all.

• Parameter names are always separated from their values with a colon (:).

• Parameter names are always case-sensitive; ClickKill and clickKill are two completely different parameter names in HierMenus. Parameter values are often case sensitive, too (if you are in doubt, assume that they are).

What parameters can you set in HM_f_SetMenus? A lot. A complete listing and reference can be found in our Reference Section, and we recommend that you browse that listing to at least get a feel for the available parameters and their capabilities. And remember that whether not a particular variable is applicable to menus--ItemClass, for example applies only to items, not menus; and MenuBGColor only to menus, not items--is irrelevant. Both of these settings are equally welcome in HM_f_SetMenus, where they will be happily applied to the menu (as necessary) and be inherited by the items that are later attached to this menu.

When setting parameter:value pairs, note that the values supplied nearly always follow this simple rule. If the value supplied is entirely numeric, then no quotes should surround the value. If, on the other hand, the value contains any non-numeric characters, then the value is a string and must be enclosed in quotes. For example:

   MenuWidth:150,
   BaseURL:"http://mydomain.com/",
   MilliSecondsVisible:300,
   ScrollEnabled:1,
   FontWeight:"normal",
   BGColor:"#dddddd",

etc. Exceptions to this rule include:

• Boolean values (true/false) must not be enclosed in quotes.

  KeepHilite:true,

• The keyword null must not be enclosed in quotes.

  MenuBackgroundImage:null,

• When JavaScript expressions are used, they typically should not be enclosed in quotes.

  MenuBackgroundImage:(HM_NS4)?null:"bgImg.gif",

  There is, however, an exception to this exception. A small number of parameters accept as valid values String JavaScript expressions, and these parameters allow quoted JavaScript expressions. See the reference entries for TopMenuX, TopMenuY, ChildMenuX, ChildMenuY, TopUponDisplay, TopUponHide, ChildUponDisplay, and ChildUponHide for further details. See also the Menu Positioning Mini-Tutorial for a description of the difference between normal, and String JavaScript expressions.

If you are in any doubt as to what type of value is acceptable in each parameter, visit the parameter's reference entry.

Examples

In the following example file, we utilize JavaScript comments--text beginning with a double slash (//)--to describe the basics of the parameters. Though syntactically valid (they will be accepted by JavaScript) such lines are provided here only for your use and would typically not be included in your actual configuration file.

HM_f_SetMenus({
   MenuID:"hm_m_Products",   
           // menu id for reference
   TopMenuX:"HM_f_CenterMenu('hm_m_Products')",
           // retrieve a centered left position for the menu 
           // via the custom loader code HM_f_CenterMenu
   TopMenuY:"HM_f_GetElementXY('placer1','y')",
           // retrieve the top position for the menu 
           // via the custom loader code HM_f_GetElementXY
           // HM_f_GetElementXY gets the top position of
           // an in page element called "placer1" and 
           // returns it to be used as the menu's top 
           // position
   IsPermanent:1,
           // menu will be permanently displayed
   IsHorizontal:1,
           // menu will be horizontally aligned
   PositionChild:"below",
           // child menus that descend from menu items 
           // in this menu should be automatically positioned
           // beneath the menu items
   MilliSecondsVisible:0,
           // this menu will hide immediately when the 
           // mouse rolls off it it (assuming ClickKill
           // is also false)
   CreateOnLoad:true
           // this menu will be created immediately after
           // the page loads
});

The above example registered only one menu. Let's see an example that registers multiple menus. Also, the name:value pairs for each menu do not need to be specified on separate lines, as above; they can be applied on a single line, as shown here:

HM_f_SetMenus(
   {MenuID:"Pr1",FontColor:"blue"},
   {MenuID:"Pr2",FontColor:"gray"},
   {MenuID:"Pr2",FontColor:"green"},
   {MenuID:"Pr2",FontColor:"red"},
   {MenuID:"Pr2",FontColor:"yellow"},
   {MenuID:"Pr2",FontColor:"black"}
);

As the above example indicates, menu creation needn't be exceptionally verbose. By properly utilizing your global defaults and HM_f_SetMenuTemplate, the actual creation of the menu often requires only the specification of its MenuID (which is a critical, and required parameter of every menu setting).

Again, for full details on each of the parameters described above, visit our Reference Section.