home / documentation / setup / configuration files / hm_f_updatedefaults

HM_f_UpdateDefaults

HM_f_UpdateDefaults, as its name implies, updates the script defaults to match your browser preferences. You can call HM_f_UpdateDefaults at any time in any of your configuration files, and the defaults will be updated for all menus on the page, whether they (the menus and items) have been defined already or not. That is, all menus and items that do not explicitly set a particular parameter will inherit your default settings, even if the menu or item was previously defined. Because HM_f_UpdateDefaults applies to the defaults used on all menus, you should only call it once per page. For better maintainability, we recommend including it as the first command in your main configuration file, just after the HM_f_DoNothing check.

To call HM_f_UpdateDefaults, use the following syntax:

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

Note especially the following:

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

• The HM_f_UpdateDefaults({}) 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. This is the golden rule in HierMenus configuration files; you will see it again and again, so it's best to learn it now. Whenever a list of items is specified (in this case name:value pairs, but later we'll see it applies to multiple items or menus when set in HM_f_SetMenus and HM_f_SetItems) 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_UpdateDefaults? 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 on a global scale--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_UpdateDefaults, where they will happily be inherited by the menus and/or items on your page that need them.

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:"blue",

  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.

Example

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_UpdateDefaults({
   MenuWidth:150,                  // width of menu, in pixels
   BaseURL:"http://mydomain.com/", // base href for all item URLs
   ClickKill:0,                    // menus hide on rollover
   MilliSecondsVisible:300,        // menus remain visible for 
                                   // 3/10 of a second
   ScrollEnabled:1,                // menus will scroll vertically 
                                   // if they don't fit on screen
   ScrollOver:1,                   // scrollable menus do so on 
                                   // mouseover
   ScrollBothBars:1,               // scrollable menus always display
                                   // top and bottom scrollbars
   ScrollInterval:(HM_MacN7)?100:20, // scrolling speed for scrolling 
                                // menus is set slower (100) if 
                                // the variable  HM_MacN7 is true; 
                                // faster (20) otherwise
   FontWeight:"normal",         // fonts are displayed normally (no 
                                // bold)
   FontColor:"blue",            // font color of menu items is blue
   FontColorOver:"blue",        // rollover font color is blue
   BGColor:"#dddddd",           // background color of menu items 
                                // is gray
   BGColorOver:"#ffcccc",       // rollover background color of 
                                // menu items is pink (ish)
   BorderColor:"black",         // menu border is black
   SeparatorSize:2,             // menu separators (the bars between 
                                // menu items) are 2 pixels in size
   SeparatorColor:"#d0ff00",    // separator color is green (ish)
   KeepHilite:1,                // parent items will remain hilited
                                // when their child menus are rolled
                                // over
   ShowLinkCursor:1,            // the link cursor (typically a 
                                // pointing finger icon) will appear 
                                // over menu items with links
   CreateOnLoad:false,          // menus will not be created on page 
                                // load but will instead be created
                                // when they are needed
   NSFontOver:0                 // Netscape 4.x will not change font 
                                // colors on rollover
});

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