home / documentation / setup / applying menus to pages

Applying HierMenus to Your Pages

When loading the HierMenus scripts, there are three basic types of implementations: one for stand alone (no frames) sites, and two for cross frames sites. While each of these implementations share many things in common, they also each have some unique characteristics that will have an impact on how you apply the scripts to your HTML pages and which pages you must apply the scripts to.

• Stand alone.
  By far the most common type of implementation. Stand alone implementations are for typical sites where no frames are implemented (i.e., each page loads in the full browser window). If you do not use frames on your pages, then this is the implementation method you will use.

• Standard Cross Frames.
  If your site uses frames, and you would like to be able to click or roll over HTML links in a navigation frame that popup menus in a different frame, then you need to implement one of the cross frames implementations. Each of the two cross frames implementations has its own pros and cons, which are described more fully in our Cross Frames Primer, but for now note that the standard cross frames method requires that your scripts be applied to your navigation page, and not your content pages.

• Alternate Cross Frames.
  While the standard cross frames implementation method is adequate for most sites, it does suffer from some limitations which you may find unacceptable. The alternate cross frames implementation method has fewer limitations and is generally better supported in browsers (especially Opera 7). The catch? The alternate cross frames method requires that both the navigation frame and the content pages (the pages that the menus will actually appear in) be modified to load scripts (the main scripts load in the content pages, and a small script is loaded in the navigation pages as well).

Our Cross Frames Primer should be considered required reading for anyone considering implementing either of the cross frames implementation methods described above. The primer will discuss in detail the advantages and disadvantages of each of the cross frames methods, as well as some restrictions and information that apply to all cross frame implementations in general. Once you've reviewed the cross frames primer and decided which of the implementation methods you'll be using, you can continue with the application of scripts to your pages.

Stand Alone Implementations

When deploying a stand alone implementation, you must add to your HTML the statement that loads the HierMenus scripts, as well as (optionally) add dummy function declarations and onmouseover/onmouseout commands to the links from which menus should popup.

Loading the Execution Scripts

All HierMenus implmenentations share this step in common (though which page you must perform it on varies): In order for the HierMenus scripts to function on your pages, you must include the following statement in your HTML, which calls the HM_Loader.js file that you modified and uploaded back in step 1:

<script type="text/javascript"
        language="JavaScript1.2"
        src="/hm/scripts/HM_Loader.js">
</script>

The value of the src attribute should be the location of the HierMenus scripts directory that you created in step 1; the same place you uploaded your modified HM_Loader.js file. If you opted to create two script directories, one each for the optimized and verbose versions of the execution scripts, now is where you choose which version you would like to use. For example, if you created verbose and optimized subdirectories beneath your HierMenus script directory, then you could load the verbose scripts via this statement:

<script type="text/javascript"
        language="JavaScript1.2"
        src="/hm/scripts/verbose/HM_Loader.js">
</script>

And you would load the space optimized scripts via this statement:

<script type="text/javascript"
        language="JavaScript1.2"
        src="/hm/scripts/optimized/HM_Loader.js">
</script>

For stand alone implementations, you may insert this statement anywhere on your page that you like; either in the head or body of your page. Since your users will have to wait for the script to download before the remainder of the page is displayed, however, we recommend placing the script at the very bottom of your page, just before your closing body tag:

<script type="text/javascript"
        language="JavaScript1.2"
        src="/hm/scripts/HM_Loader.js">
</script>
</body>
</html>

The placement of this statement will have no effect on when HierMenus creates the menus, or where in the page the menus are physically inserted. See FAQ #10 for further details.

Those of you familiar with HTML standards may have noticed our use of the deprecated language attribute in the external script load above. Using this tag will invalidate your HTML if you are coding to a strict version of the HTML standard. This invalidation will not, to the best of our knowledge, cause you any actual errors or problems in browsers, most of which will simply ignore attributes they do not understand. Unfortunately, however, we've found that Netscape 4.x will not properly load the HierMenus scripts without the inclusion of this deprecated attribute, which is why we require it in the above script tag. If you must code to strict HTML compliance, then your only choice is to disable Netscape 4.x support in HierMenus. If you do this, then you may feel free to remove the language attribute from the script tag above, which will not cause any problems in HM supported browsers other than Netscape 4.x. You can find instructions for disabling HierMenus support for Netscape 4.x in the Advanced Topics section of the setup instructions.

Adding Pop Ups

If you have no "Pop Up" menus, that is, menus that will be displayed when an in-page HTML link is rolled over or clicked; or, if you have elected to identify your in-page links via the LinkID parameter (which is not compatible with Netscape 4.x; see the reference page for further details), then congratulations: you're done! The inclusion of the execution scripts as described above is the only thing you need to do to apply the HierMenus scripts to your HTML pages. If, however, you are using pop ups (our recommended menuing style) and you are not using LinkID, read on.

In the head of your document, you should copy and paste this small script. Copy and paste the whole thing, script tags and all, somewhere into the head section of your document:

<script type="text/javascript">
<!--
if(window.event + "" == "undefined") event = null;
function HM_f_PopUp(){return false};
function HM_f_PopDown(){return false};
// -->
</script>

Note that if you've also placed the HM_Loader.js call (described in the previous section above) in the head of the document, then these new statements must be placed before the HM_Loader.js call.

Two dummy functions are declared, HM_f_PopUp() and HM_f_PopDown(). These functions will later be called by links in the document, links that are visible to all browsers. The actual functions are redeclared in the menu script later, for menu-enabled browsers. By placing these "dummy" functions here, older browsers that do not support HierMenus will not generate an error when they encounter a menu-enabled link since they will find and execute these dummy versions of the functions.

Fourth generation browsers have a built-in event object, passed as an argument to HM_f_PopUp(). Old browsers do not have this object, so they consider event to be a user-defined variable. We must, therefore, define it as a dummy variable for these browsers to again avoid errors.

Again, for those of you watching standards, the above code is not strictly XHTML compliant; since you must avoid the use of certain characters in scripts and our use of the HTML comment (<!-- -->)--an old trick to prevent the very oldest browsers (and any other user agent that doesn't implement the script tag) from attempting to interpret our JavaScript as HTML--would be invalid here. For those coding to XHTML standards we recommend calling the above as an external script, or using CDATA declarations in the scripts to allow the normally not allowed characters in an XHTML document. The external file is easiest and most compatible with the oldest browsers (and non-script compatible useragents). To implement it, you would create a file containing this, let's assume we'll call it HM_DummyFunctions.js (the name is up to you, but the .js extension is highly recommended):

if(window.event + "" == "undefined") event = null;
function HM_f_PopUp(){return false};
function HM_f_PopDown(){return false};

(You'll notice that's the same as the above, just without the script tags and HTML comment identifiers.) Upload this file into the HierMenus scripts directory on your server, and then include this in the head of your document instead of the full length script as above:

<script type="text/javascript"
        src="/hm/scripts/HM_DummyFunctions.js">

Having added your dummy functions, you must now add the onmouseover/onmouseout calls to your links that you wish menus to pop from. Follow this syntax:

<body>
.
. other HTML
.
<p>
<a href="/"
   onmouseover="HM_f_PopUp('hm_m_main',event)"
   onmouseout="HM_f_PopDown('hm_m_main')">HierMenus Central</a>

<a href="/documentation/"
   onmouseover="HM_f_PopUp('hm_m_docs',event)"
   onmouseout="HM_f_PopDown('hm_m_docs')">Documentation</a>
.
. other HTML
.
</body>

Where:

href

Make sure that a valid URL is included as the value of the href attribute. All browsers that do not support menus will not display them or their associated links, and need this link to navigate.

onmouseover / onmouseout

The event handlers must be onmouseover and onmouseout even if you have set the ClickStart and ClickKill parameter variables to true (displaying and/or hiding menus with mouse click). The menu script will adapt to the parameters you have set.

HM_f_PopUp() / HM_f_PopDown()

HierMenus includes two functions that control the initial display and the hiding of the menus. These are HM_f_PopUp() and HM_f_PopDown(), respectively. Since JavaScript is case-sensitive, make sure you refer to the functions as HM_f_PopUp and HM_f_PopDown. Calls to HM_F_POPUP(), hm_f_popup() or hM_F_pOpUp() will generate errors.

HM_f_PopUp('hm_m_main',event)

HM_f_PopUp() takes two arguments:

1. The first is the menu identifier (which you set on the menu via the MenuID parameter), passed as a string. The MenuID should be specified in quotes.

   You may pop up any of the menus you defined within your configuration file, but note that a single menu can appear on the page in only one position at a time. If you popup a menu that is already showing on the page, chances are HM will not reposition and redisplay the menu as a result of the newly rolled over link. If, however, the menu is not already being displayed, then it will be displayed as a result of the link.

2. The second is the event object.

   It must be included, as many browsers need the event object to be passed to sub-functions explicitely, if from an HTML event handler defined via an attribute.

HM_f_PopDown('hm_m_main')

HM_f_PopDown() takes only one argument, but it must be the same MenuID that was used as the HM_f_PopUp() first argument. That is, if HM_f_PopUp() has "hm_m_main" as its first argument, HM_f_PopDown() must have "hm_m_main" as its sole argument.

link display text

The link's display text should, of course, describe the menu options, but should also make sense to users who will not see the menus. For example, the link text should never read: "Menu 2" or "Mouseover to see Menu." Since an old browser user will click on it to navigate, they must be informed of where they are going.

Standard Cross Frames Implementations

Standard Cross Frames implementations are almost identical to Stand Alone implementations, and therefore we refer you to the instructions above for setting up your site. The only differences in a Standard Cross Frames implementation are these:

• The changes described above should be made only to the navigation page of the frameset. With the possible exception of style sheet classes, no changes should be made to the actual content pages--i.e., the pages that will be loaded into your main content frame (where the menus will actually be displayed). When inserting the command to load the execution script (the HM_Loader.js call) you must do so within the body of the HTML page. In standard cross frame implemenations you may not call HM_Loader.js from the head of the navigation page.

  If you are using HM 6's new ability to assign class names to menus and menu items, then those class name definitions (the actual style sheet rules) must be included in the actual content pages to be properly applied to the menus.

• The HM_FramesEnabled parameter in the HM_Loader.js file must be set to true.

• The FramesMainFrameName and FramesNavFramePos configuration parameters must be set via HM_f_UpdateDefaults (see step 2 for details on HM_f_UpdateDefaults) to appropriate values. For details on the valid FramesMainFrameName and FramesNavFramePos settings, see their reference entries.

• The content frame of your site, i.e., the one that the menus will be popped up within, must have a name assigned to it via the name attribute of the frame tag that defined it. Further, this name must match the name assigned to the FramesMainFrameName parameter. This name is assigned from directly within the appropriate frame tag that defines the content frame itself. For example:

  <frame name="main" src="myPage.html">

  The actual name you use is unimportant to HM, so chances are you've already assigned a name to your main content frame (since it's the easiest way to target links from other frames) that will work fine. Just make sure that the name you're using matches that which is indicated in FramesMainFrameName.

• While this last step is optional, we highly recommend it as it provides the most efficient means for rebuilding menus between page loads in certain browsers (specifically, IE5.5 and IE6). Add an optional onload handler to the main content frame, specified as follows:

  <frame name="main"
   onLoad="HM_UseFrameLoad=1;if(window.HM_f_LoadMenus)HM_f_LoadMenus();"
   src="myPage.html">

  If you have your own commands already present in the onload handler of your main frame, then you can add those commands to the beginning or ending of these statements. But in any case, the code above must appear somewhere within the onload handler exactly as is.

Alternate Cross Frames implementations

With Alternate Cross Frame implementations, you must insert the execution scripts, i.e., add this tag as described in the stand alone implementation instructions above:

<script type="text/javascript"
        language="JavaScript1.2"
        src="/hm/scripts/HM_Loader.js">
</script>

to every content page on the site within which menus will be displayed. You needn't, however, add the dummy functions and the onmouseover/onmouseout commands to links within the content pages, unless you actually want to pop up menus from links that appear within the actual content page itself. In other words, each content page of the site that will have menus displayed within it must be setup as a stand alone HierMenus implementation, with the only caveat that applying pop ups to links within the content pages themselves is optional.

In addition to the content page adjustments, you must also setup the navigation page(s) of your frameset almost as if they are stand alone pages, too. There are three main differences, however, in the navigation page setup instructions

1. When including the statement that loads the execution scripts, you call HM_NavFrameLoad.js instead of HM_Loader.js:

   <script type="text/javascript"
           language="JavaScript1.2"
           src="/hm/scripts/HM_NavFrameLoad.js">
   </script>

   HM_NavFrameLoad.js is in your scripts directory, and must be modified in the same manner as HM_Loader.js. HM_NavFrameLoad.js, however, has only one parameter to configure, not 6: HM_ScriptDir. Once modified, be sure that HM_NavFrameLoad.js gets uploaded to the HierMenus script directory on your Web server.

2. When including onmouseover calls for the links within your navigation pages, you must include an additional parameter:

   onmouseover="HM_f_PopUp('hm_m_main',event,'left');

   The additional parameter (left in the example above) indicates to HierMenus the FramesNavFramePos for this link--the position of the link itself in relation to the content frame for purposes of menu positioning. In Alternate Cross Frames implementations, the FramesNavFramePos setting as specified in the content pages itself is ignored, thus it must be specified from within the link itself.

3. Unlike the other implementation methods above, if you want your menus to pop up when the link is clicked (instead of rolled over) you must explicitly set the onclick handler of the link. Therefore, in a link that you wish to activate the menu on click, your link would look something like this:

   <a href="/"
      onclick="HM_f_PopUp('hm_m_main',event,'left')"
      onmouseout="HM_f_PopDown('hm_m_main')">HierMenus Central</a>

   Note the use of onclick instead of onmouseover. Also note the onmouseout call remains the same.

Some final thoughts on the Alternate Cross Frames implementation:

• If you are popping up your menus from multiple navigation frames, then each navigation frame page must be modified as in the bullets above.

• In the Alternate Cross Frames implementation, HM_FramesEnabled in the main HM_Loader.js file must be false.

• In the Alternate Cross Frames implementation, you needn't assign the name of the content frame (FramesMainFrameName) to the navigation scripts; nor should you assign the special onload handler to the content frame's frame tag. These are unnecessary and will be ignored by HierMenus. To find the content frame within which the menus should be displayed, HierMenus will simply search all of the frames for the existence of the loaded execution script (which will be performed via the inclusion of the execution script call in the content pages themselves).

What's Next

This concludes the installing, configuring, and application of the HierMenus script on your site. You may now wish to browse (if you haven't already) the Advanced Topics section of the setup instructions to discover some of the finer points of HierMenus use. Additionally, if you haven't already we strongly suggest you read through the individual entries in the reference section to know the full breadth of parameters you may assign to your menus and how they interact with each other. With over 100 parameters to assign, it's simply impossible for us to provide you with example codings of all of them; looking through what's available is the best way to ensure you're not missing anything.