home / documentation / setup / configuration files / hm_f_setmenutemplate

HM_f_SetMenuTemplate

HM_f_SetMenuTemplate allows you to define a set of configuration parameters that are automatically applied to any menus that are defined after the template is registered. If you have a large group of menus that share some characteristic(s) in common--some characteristic that differs from the defaults--then using a menu template can save you a lot of typing and space in your configuration file. Only a single menu template can be in effect at any given time, therefore, HM_f_SetMenuTemplate accepts only one list of parameter name values (like HM_f_UpdateDefaults).

To call HM_f_SetMenuTemplate, use the following syntax:

HM_f_SetMenuTemplate({
   ParameterName1:ParameterValue1,
   ParameterName2:ParameterValue2,
   ...
   ParameterNameN:ParameterValueN
});

Note especially the following:

• A single pair of curly brackets ({}) encloses the list of parameter:value pairs. This pair of brackets is itself 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_SetMenuTemplate statement itself. (You don't need to know how or why that is; just remember that both the single pair of parentheses (outside) and a single pair of curly brackets (inside) are necessary.)

• The HM_f_SetMenuTemplate({}) 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_SetMenuTemplate? 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_SetMenuTemplate, where they will be happily applied as specific parameters to all menus registered after the template was registered. And once assigned to the menus, the parameters themselves will be utilized by the menu (as necessary) and/or be inherited by the items that are later attached to the menu.

Using a menu template is exactly the same as if you specified each of the template parameters directly with each new menu registration. For example, this (partial) configuration file, which creates 10 identical looking menus:

HM_f_SetMenus(
   {MenuID:"hm_menu1",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu2",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu3",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu4",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu5",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu6",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu7",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu8",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu9",FontColor:"blue",BGColor:"white"},
   {MenuID:"hm_menu10",FontColor:"blue",BGColor:"white"}
);

is identical to this configuration:

HM_f_SetMenuTemplate({FontColor:"blue",BGColor:"white"});

HM_f_SetMenus(
   {MenuID:"hm_menu1"},
   {MenuID:"hm_menu2"},
   {MenuID:"hm_menu3"},
   {MenuID:"hm_menu4"},
   {MenuID:"hm_menu5"},
   {MenuID:"hm_menu6"},
   {MenuID:"hm_menu7"},
   {MenuID:"hm_menu8"},
   {MenuID:"hm_menu9"},
   {MenuID:"hm_menu10"}
);

To clear an existing menu template (so that its settings are no longer automatically applied to subsequent menus) use this command:

HM_f_SetMenuTemplate({});

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_SetMenuTemplate({
   IsPermanent:0,
           // menus will not be permanently displayed
   IsHorizontal:0,
           // menus will be vertically aligned
   PositionChild:"below",
           // child menus should be automatically positioned
           // beneath their parent menu items
   MilliSecondsVisible:0,
           // menus will hide immediately when the 
           // mouse rolls off it it (assuming ClickKill
           // is also false)
   CreateOnLoad:false
           // menus will not be created immediately 
           // after the page loads; rather, they will
           // be created as needed
});

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