home / documentation / setup / creating a configuration file

Creating a Configuration File

The HierMenus configuration file is where you will indicate to HierMenus both the content and the relevant behaviors of your menus. Will your menus be scrollable? Will they be permanently displayed on your pages? Will child menus display when menu items are clicked or rolled over? What will the background, font, and rollover colors be? Each of these parameters, and many, many more can be specified within your configuration file.

Inheriting Parameters

Your menus are built by means of assembling building blocks. The three main building blocks of your configuration file are the script defaults, menus, and menu items. Before you can begin building your menus, however, it is important (and can save you a lot of work and file space, in the long run) that you understand how and when these building blocks inherit settings from one another. We'll attack the details of how each of these blocks are specified and defined later; for now focus on the concepts.

At the topmost level of any configuration file are the script defaults. As their name implies, the script defaults are the initial values assigned by HierMenus to all configuration parameters that you will include in your configuration file. These values are automatically inherited by all menus defined within your configuration file(s). The script defaults can be updated via the HM_f_UpdateDefaults method, which we'll describe in detail lower on this page. If you have certain parameters that must be defined in all of your menus; for example, if all of your menus utilize the same rollover color scheme, then the script defaults is the place to make that assignment. Having set your color schemes in the defaults, you needn't reapply them to each of your defined menus. Unless, of course, you have a particular menu that you want to be different from the rest. And remember that for every configuration parameter, HierMenus defines its own, internal default value. You only need to modify the default value if HierMenus' internal default value does not suit your needs. Refer to the reference pages for the individual parameters themselves to discover HierMenus' default setting for each.

The next inheritance level is the menus themselves. You can assign specific configuration parameters directly to menus, in which case those parameters are automatically inherited by all menu items that are assigned to that menu. Note that whether or not the parameter you're setting is actually applicable to a menu is irrelevant. If a menu item specific parameter, such as ItemClass or HM_OnItemOver is set on a menu, it will automatically be inherited by all items on that menu (and consequently, ignored by the menu itself). And by extension, since all menus inherit from the script defaults automatically, then menu items will also automatically inherit from the script defaults all those parameters that are not explicitly set on their parent menus.

(Technically, a Menu Template, which we'll discuss more fully below, provides somewhat of a level of inheritance between the menus and the script defaults.)

By understanding this inheritance scheme you can save yourself a lot of typing and maintenance in your configuration file. For example, if you want a navy blue/light blue color scheme on three menus, one valid way to do it would be like this (again, don't worry about details yet):

HM_f_SetMenus(
   {MenuID:"Menu1",
    BGColor:"navy",
    BGColorOver:"#99CCFF",
    FontColor:"white",
    FontColorOver:"black"},

   {MenuID:"Menu2",
    BGColor:"navy",
    BGColorOver:"#99CCFF",
    FontColor:"white",
    FontColorOver:"black"},

   {MenuID:"Menu3",
    BGColor:"navy",
    BGColorOver:"#99CCFF",
    FontColor:"white",
    FontColorOver:"black"}
);

This will work fine, but will also be a substantial waste of file space. And what if you need to change your default color scheme at some point in the future? The above file requires changes to three places and isn't too bad; but what if you had 30 menus?

The inheritance concept described above provides a better way. Rather than assign your common parameters over and over again on every menu (or worse, every menu item), instead assign them once in your script defaults. This type of configuration would look as simple as this:

HM_f_UpdateDefaults(
   {BGColor:"navy",
    BGColorOver:"#99CCFF",
    FontColor:"white",
    FontColorOver:"black"}
);

HM_f_SetMenus(
   {MenuID:"Menu1"},
   {MenuID:"Menu2"},
   {MenuID:"Menu3"}
);

Much simpler, and much, much more manageable.

A single global exception applies to this inheritance mechanism. The MenuID parameter must be specified individually on every menu and menu item registered in your configuration file. MenuID is not inherited; and in fact, if you attempt to register a menu or menu item without an explicit MenuID HierMenus will silently ignore your request.

One last thought before we leave the inheritance issue. As we described above, all menu items inherit parameter settings from their container menus, and menus inherit parameter settings from the script defaults. Menus do not, however, inherit from other menus; regardless of the order the menus are created in or the child-parent relationships of the menus. A menu that is created with the intention of being a child menu will not automatically inherit parameter settings from its ultimate parent menu. And in fact, a single menu can be used as a child menu of more than one parent; making it impossible for HierMenus to conclusively know which parent it should inherit from anyways. Therefore, all menus inherit parameter settings directly from the script defaults, and never from other defined menus.

Configuration File Building Blocks

Now let's get into the actual details of your actual configuration file definitions. Each configuration file contains some combination of the following building blocks. Click on the links for a detailed explanation of how each is used along with the proper syntax:

• HM_f_DoNothing() is sniffing code that ensures the main execution script has indeed loaded properly. The HM_f_DoNothing() checks are required at the beginning of every configuration file you create.

• HM_f_UpdateDefaults() allows you to update the script's global default settings as described above. You should call HM_f_UpdateDefaults() once, and only once, per page (that includes the case where you may be loading multiple configuration files). Since the default settings are applied to all menus whether they've been defined already or not, you will typically want to include an HM_f_UpdateDefaults() call once, at the top of your main configuration file.

• HM_f_SetMenus() allows you to define one or more menus for use in HierMenus.

• HM_f_SetItems() allows you to define one or more menu items to attach to menus. The menu you are attaching the menu items to must have already been defined previously using a HM_f_SetMenus() call.

• HM_f_SetMenuTemplate() allows you to define an intermediate template that is automatically assigned to all menus defined after it. Unlike the script defaults, menu templates will not have any effect on the menus that were defined before it (the menu template) was created, making it the perfect solution for assigning parameters to groups of menus that differ in some way from the defaults.

• HM_o_RolloverImages is not a function as are the other building blocks, but rather a static object that enables you to define rollover images for embedded images within your menu item displays. Embedded image rollovers were initially introduced in HierMenus version 5.3, and their use in HierMenus version 6 is identical to the 5.3 usage (i.e., the HM_o_RolloverImages object, as well as the actual embedded images themselves, are defined and utilized in the same way).

After reviewing these entries, you'll find that they're all very syntactically similar, differing only in the exact objects that the parameters effect (with the exception of the HM_o_RolloverImages object). For example, HM_f_SetMenus creates menus and HM_f_SetItems creates items; but the syntax for the two is identical, as are the parameter assignments that can be made on each. The parameter assignments, i.e., the individual settings that can be made to each menu and item, are far too numerous to go through here. 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.

Once you've had a chance to study the details of each of the configuration methods above, continue to the example configuration settings below to see how they fit together. You may also want to refer to the sample configuration files in the samples directory of your zip distribution file for further ideas and demonstrations. Finally, once you've completed your configuration file, save it to disk and then upload it to the HierMenus configs directory (that you created in step 1) on your server. Remember to give the file the same name that you indicated in HM_ConfigFiles when you configured your HM_Loader.js file (that's HM_Config.js, if you followed our recommendations).

Sample Configuration File

In the following example file, we utilize JavaScript comments--text beginning with a double slash (//)--to describe the basics of the commands themselves. Such lines are provided here only for your use and would typically not be included in your actual configuration file.

// The DoNothing check is required.
// without it, your configuration file may 
// generate seemingly random errors in each 
// of the major browsers (IE and Mozilla)

function HM_f_DoNothing() {return;}
if(typeof(HM_f_UpdateDefaults)=="undefined") {
	HM_f_UpdateDefaults=HM_f_DoNothing;
	HM_f_SetMenuTemplate=HM_f_DoNothing;
	HM_f_SetMenus=HM_f_DoNothing;
	HM_f_SetItems=HM_f_DoNothing;
}

HM_f_UpdateDefaults({ // these apply globally
   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:(window.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
});

HM_f_SetMenuTemplate({  // these will apply to all following menus
   MenuWidth:100,
   FontColor:"red",
   FontColorOver:"yellow",
   BGColor:"yellow",
   BGColorOver:"black",
   BorderColor:"blue",
   ClickStart:1,
   SeparatorColor:"green"
});

HM_f_SetMenus({
   MenuID:"hm_m_Main",
           // menu id for reference
   TopMenuX:"HM_f_CenterMenu('hm_m_Main')",
           // 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
});
HM_f_SetItems(
   {MenuID:"hm_m_Main",DisplayText:"Experts",LinkURL:"experts/",
            ChildID:"hm_m_Experts"},
   {MenuID:"hm_m_Main",DisplayText:"Contents",LinkURL:"/"},
   {MenuID:"hm_m_Main",DisplayText:"Services",LinkURL:"index2.html",
            ChildID:"hm_m_Services"},
   {MenuID:"hm_m_Main",DisplayText:"About",LinkURL:"about.html"}
);

HM_f_SetMenus(  // create two menus with one call
                // note that the menu template is still
                // in effect here
   {MenuID:"hm_m_Experts"},
   {MenuID:"hm_m_Services"}
);
HM_f_SetItems( // menu items for hm_m_Experts
   {MenuID:"hm_m_Experts",DisplayText:"3-D Animation",LinkURL:"3d/"},
   {MenuID:"hm_m_Experts",DisplayText:"Design",LinkURL:"dlab/"},
   {MenuID:"hm_m_Experts",DisplayText:"HTML",LinkURL:"html/"},
   {MenuID:"hm_m_Experts",DisplayText:"JavaScript",LinkURL:"js/"},
   {MenuID:"hm_m_Experts",DisplayText:"Graphics",LinkURL:"graphics/"},
   {MenuID:"hm_m_Experts",DisplayText:"DHTML",LinkURL:"dhtml/"},
   {MenuID:"hm_m_Experts",DisplayText:"Perl",LinkURL:"perl/"},
   {MenuID:"hm_m_Experts",DisplayText:"XML",LinkURL:"xml/"}
);
HM_f_SetItems(  // menu items for hm_m_Services
   {MenuID:"hm_m_Services",DisplayText:"Services",LinkURL:"news/"},
   {MenuID:"hm_m_Services",DisplayText:"Forum",
            LinkURL:"http://forums.webdeveloper.com/"},
   {MenuID:"hm_m_Services",DisplayText:"How-to",LinkURL:"dev/"},
   {MenuID:"hm_m_Services",DisplayText:"New",LinkURL:"new/"},
   {MenuID:"hm_m_Services",DisplayText:"Hot Sites",LinkURL:"hot/"}
);

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

Having created your configuration file, you're almost ready to begin using HierMenus on your site. The final step is to apply the scripts to your HTML pages. This is the topic in step 3 of our setup instructions.