HierMenus CENTRAL: HierMenus In Progress. HierMenus 5.0 Release Notes (4/7)

[previous] [next]

HierMenus 5.0: Further Frames Instructions and Limitations

When installing a cross-frames implementation of HierMenus, there are two further changes that should be made to your HTML framesets. The first of these is mandatory (but chances are good that you're already doing it) and the second is optional (but we highly recommend it).

Naming the content frame

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 HM_GL/PG_FramesMainFrameName parameter (see the previous page for further information).

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 HM_GL/PG_FramesMainFrameName.

Adding the onload handler

While this 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).

You add this optional onload handler to the main content frame, and it should be 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.

CreateTopOnly Recommended

In a cross-frames implementation such as this, DHTML elements must be recreated and attached to each new page that is loaded into the main content frame. For this reason, we strongly recommend the use of the HM_GL/PG_CreateTopOnly parameter, to avoid forcing HM to recreate all the menus on a page as soon as the page is loaded. HM_GL/PG_CreateTopOnly was first introduced in HierMenus v4.0.3.

Cross-Frames Limitations

While HM 5 should gracefully provide cross-frames capabilities to the majority of HM sites as is, there are a few limitations that you should know about before beginning your implementation. Also, be sure to visit our newly updated Known Issues page where we track browser specific issues that can be triggered by HM.

Content and Navigation in same frameset

The content frame and the navigation frame (i.e., the page in which the scripts and popup links will be loaded) must exist within the same frameset tag of the page. It is not required that the two pages be adjacent to one another, though we suspect this will be the most common arrangement.

In a similar vein, you cannot load both a cross-frames and a stand alone HM implementation in a single frame simultaneously. That is to say, if you have a two frame setup, with HM loaded in the Navigation Frame and producing menus in the Content Frame, you cannot also then have a stand-alone HM version loaded directly within the content frame at the same time.

Cross Domain Scripting and the Same-Origin Policy

All modern browsers implement security restrictions such that pages loaded into one frame cannot manipulate pages loaded into a second frame unless both pages were retrieved from exactly the same domain. This "Same-Origin Policy" exists to protect surfers from frame "spoofing," setting up a frameset that loads scripts in one frame that could potentially read and write sensitive data from a second frame that contains a page loaded from an entirely different site (such as a credit card order form, for example). HM cannot override this security restriction (nor can any DHTML script), therefore if pages are loaded in the content frame of the site from a different domain from that of the frameset and the navigation page, then no popup menus will be displayed in those pages.

JavaScript provides the document.domain property allowing cooperating sites to remove this restriction for their particular Web sites, i.e., pages which specifically set the document.domain property can override (to an extent) the Same-Origin policy to allow scripts such as HM to read and write values across frames as if both pages did come from the same domain.

As this restriction applies to all JavaScript code, the use of document.domain is somewhat out of the scope of our typical HM documentation. However, if you should need it, be aware of two important limitations to its use:

1. The domain name set in document.domain must itself be a suffix of the actual domain that the page came from in the first place. For example, if you retrieve a page from "mySite.myDomain.com", then you can set document.domain="myDomain.com" but you cannot set it to document.domain="microsoft.com" or even document.domain="www.myDomain.com"
2. When using document.domain we've found that it's necessary to include it in all pages of the site that will be loaded into the frames; including the framesets and the navigation pages themselves. I.E., if document.domain is set in any one page of the frameset, it must be set in the frameset and the navigation frame, as well.

Permanent Menus Displayed in Content Frame

You can use permanently visible menus (a feature originally introduced in HM4) in a cross-frames implementation. The menus themselves, however, (including the permanently visible portion) will be displayed in the content frame, and not the navigation frame. Therefore, to popup menus in the content frame from the navigation frame you must define "hotspots" by attaching onmouseover and onmouseout handlers to HTML links within the navigation frame.

In most cases, this will be the preferred setup method for users anyway, as defining hotspots allows the main links of the navigation page to always be present and available to users--even if they are using an unsupported browser or have JavaScript disabled.

Macintosh IE5 Not Supported

Regrettably, we are currently unable to support the Macintosh version of Internet Explorer v5 for cross-frames implementations, though Mac IE5 will continue to work normally for standard (non-frames) implementations. When a Macintosh IE5 user surfs to a cross-frames HM5 implementation, no menus will be popped up when the user rolls over the main navigation links.

Cross-Frames vs. Frames Targets

Finally, bear in mind that throughout this discussion we've been referring to cross-frames menus specifically in this context: defining a set of links in one frame that, when clicked or rolled over, spawn popup menus in another frame. If you need to launch a page from a menu item in a different frame (but the menus themselves are all contained in a single frame) then you do not need to implement "cross-frames" functionality, as this feature can be accomplished using javascript: URLs, which have been supported in HM since version 3. See FAQ #3 for further information.

Having covered cross-frames usage, let's turn our attention to some of the other minor adjustments and changes in HM5.

[previous] [next]