home / documentation / setup / configuration files / hm_f_setitems

HM_f_SetItems

HM_f_SetItems registers actual menu items in the HierMenus system. Note that individual menus are not set via HM_f_SetItems; only the actual menu items that will be applied to menus. And, in fact, before you can attach items to any menu, that menu must be defined; its registration via the HM_f_SetMenus command must have already been performed. As described on the previous page, all parameters set specifically on a menu item override the inherited defaults for that menu item.

To call HM_f_SetItems, use the following syntax:

HM_f_SetItems(
  {Item1ParameterName1:Item1ParameterValue1,
   Item1ParameterName2:Item1ParameterValue2,
   ...
   Item1ParameterNameN:Item1ParameterValueN},

  {Item2ParameterName1:Item2ParameterValue1,
   Item2ParameterName2:Item2ParameterValue2,
   ...
   Item2ParameterNameN:Item2ParameterValueN},

  ...

  {ItemNParameterName1:ItemNParameterValue1,
   ItemNParameterName2:ItemNParameterValue2,
   ...
   ItemNParameterNameN:ItemNParameterValueN}
);

Note especially the following:

• Unlike HM_f_UpdateDefaults and HM_f_SetMenuTemplate, HM_f_SetItems allows for the registration of multiple menu items with a single HM_f_SetItems call. You may also elect to register only one item at a time with HM_f_SetItems, though we suspect you will prefer to register multiple items (generally, all the items that will be used on a specific menu) together. The parameter list for each new item must be enclosed in curly brackets ({}). Each menu item (each curly bracket pair) must be separated by a comma. Like the parameter name:value pairs (described below) the final item setting in HM_f_SetItems must not be followed by a comma.

• A single pair of curly brackets ({}) encloses each list of parameter:value pairs. All of the menu item 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_SetItems 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 item setting are necessary.)

• The HM_f_SetItems({}) 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; IsSelected and isSelected are two completely different parameter names in HierMenus. Parameter values are often case sensitive, too (if you are in doubt, assume that they are).

• Menu items are attached to the menu in the order they are defined; whether all the items for the menu are defined at once in a single HM_f_SetItems call, or whether multiple HM_f_SetItems calls register items for the same menu. In a vertical menu, for example, the first item defined for the menu will be the topmost item in that menu; the second will be just below the top menu item, and so on.

What parameters can you set in HM_f_SetItems? 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. No other HierMenus objects inherit from menu items (with the exception of buttons, but these are controlled entirely by CSS style sheets), and therefore it is pointless (and a waste of space) to specify parameters that apply only to menus--such as MenuBGColor or MenuClass--on an item. These will simply be ignored by HierMenus.

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:

   SeparatorSize:3,
   LinkURL:"mypage.html",
   DisplayText:"Menu Item 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.

  ItemBackgroundImage:null,

• JavaScript expressions should not be enclosed in quotes.

  ItemBackgroundImage:(HM_IE4)?null:"bgImg.gif",

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_Menu2_1"});  // register the menu
HM_f_SetItems(
   {MenuID:"HM_Menu2_1",         // menu to attach this item to
    IsRollover:1,                // this item is a rollover item
    IsPermHilite:0,              // this item is not perm hilited
    MoreImagesVisible:0,         // do not display a "more" image
    ChildID:"HM_Menu2_1_1",      // this item will have a child menu.
                                 // the menu id of the child menu (as
                                 // registered on the menu itself) is
                                 // HM_Menu2_1_1.
    DisplayText:"3-D Animation", // the text display of the menu item
    LinkURL:"3d/"}               // link to be followed when clicked
);

Note especially in the above example that, though the menu you are attaching the items to must have already been registered, menus that you are identifying as child menus of these items (via the ChildID parameter) do not have to have been previously registered. So HM_Menu2_1_1 in the above example can be actually defined later in the configuration file.

The above example registers only one menu item for the menu HM_Menu2_1. Let's see an example that registers multiple menu items. Also, the name:value pairs for each menu item 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:"HM_Menu2_1"});
HM_f_SetItems(
   {MenuID:"HM_Menu2_1",DisplayText:"3-D Animation",LinkURL:"3d/"},
   {MenuID:"HM_Menu2_1",DisplayText:"Design",LinkURL:"dlab/"},
   {MenuID:"HM_Menu2_1",DisplayText:"HTML",LinkURL:"html/"},
   {MenuID:"HM_Menu2_1",DisplayText:"JavaScript",LinkURL:"js/"},
   {MenuID:"HM_Menu2_1",DisplayText:"Graphics",LinkURL:"graphics/"},
   {MenuID:"HM_Menu2_1",DisplayText:"DHTML",LinkURL:"dhtml/",
            ChildID:"HM_Menu2_1_6"},
   {MenuID:"HM_Menu2_1",DisplayText:"Perl",LinkURL:"perl/"},
   {MenuID:"HM_Menu2_1",DisplayText:"XML",LinkURL:"xml/"}
);

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

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