|
home / bulletins / 6 / page 2
Using the HM_f_ToggleElementList Function
The HM_f_ToggleElementList function presented on the
previous page is intended to be a drop-in script that you can use on any
of your HTML pages. The only global variables declared, HM_DOM,
HM_IE, and HM_NS4 use our familiar HM_ prefix
naming as a convenience when using the function in combination with
HierMenus (a task that we will discuss on the next page
of this article).
To install HM_f_ToggleElementList, simply copy
and paste the script code into the <head> or
<body> section of your page (we recommend the
<head>) and then call it from your own JavaScript or event
handlers as appropriate.
Calling HM_f_ToggleElementList
Three parameters are passed into the HM_f_ToggleElementList
function that tell it what to do with the elements (hide them or show
them), which elements should be changed, and whether the element list
represented in the second parameter is a list of HTML tags or
object IDs. Let's look at these parameters one at a time:
show: The first parameter passed to HM_f_ToggleElementList
is a simple boolean variable. You can pass the keywords true or false
directly to the function, as well as any expression or value that will be converted
to true or false by JavaScript, such as 1 or 0.
For example, this call:
HM_f_ToggleElementList(false,['form'],'tag');
will hide all form tags on the page, while this call:
HM_f_ToggleElementList(1,['form'],'tag');
will display all form tags on the page. elList: A list of strings that represent either IDs or
HTML tags. This list must be passed into the function as an array of strings.
In JavaScript 1.1 or later environments you can use array literals as a simple
way to pass your intended elements. If backward compatibility is required then
you will need to simulate the array separately and then pass in the name of your
array-object instead (but note that the HM_f_ToggleElementList function itself
assumes JavaScript1.2 compatibility and will silently return for browsers that
do not comply. The parameter passing is simply mentioned here to avoid errors
triggered in the actual calling of the function).
Thus, if you wanted to hide all <select> and
<input> elements in a JavaScript 1.1+ capable setting, you
might use this:
HM_f_ToggleElementList(false,['select','input'],'tag');
and to make the same call without triggering errors in a
backwards compatible environment try this instead:
var theArray = new Object;
theArray[0] = 'select';
theArray[1] = 'input';
theArray.length = 2;
HM_f_ToggleElementList(false,theArray,'tag');
toggleBy: Indicates whether the element list passed as
the second parameter should be treated as a series of IDs (use id) or
a series of HTML tags (use tag). Thus, you can use this same procedure
to hide one or more specific objects using their known ID attributes,
or you can simply hide/restore all elements that were created using a specific
HTML tag in the document. To hide all the tables, forms, and spans of a page
you could use this:
HM_f_ToggleElementList(0,['table','form','span'],'tag');
and to display the page objects identified with the IDs of
widget1, 2, and 3 you could use this:
HM_f_ToggleElementList(true,['widget1','widget2','widget3'],'id');
Our sample page, which
opens in a new window, provides examples of each of the above types of calls.
Technical Notes, Cross-Browser Considerations
The HM_f_ToggleElementList function is quite straightforward; if you are
familiar with JavaScript and especially DHTML usage you probably won't find anything
terribly unusual. A couple points about the function, however, require some direct
discussion.
The function makes several provisions specifically for Netscape
4.x browsers. This is because in Netscape 4.x you cannot toggle the visibility of
just any element on the page, as you can in later browsers. Rather, you can
only toggle the visibility of positioned layers created using the layer
constructor or corresponding HTML/CSS syntax within the HTML page. Therefore,
if you call HM_f_ToggleElementList with a toggleBy indicator of
tag Netscape 4.x will silently and immediately return without doing
anything; and if you call the function with an id list Netscape 4.x
will only perform the visibility toggle if it can find a matching layer
on the page with the same id. (Remember that when an HTML object is
positioned in Netscape 4.x it is internally represented as a layer.
Therefore, if you create your positioned object using a DIV tag you can still
use HM_f_ToggleElementList to toggle its visibility, even though no
layer tag was used in the HTML.)
This results in a serious limitation in hiding elements in
Netscape 4.x since it means that all elements that you want to hide must, via
one means or another, be contained within a positioned element (and that you
must use the id based method of hiding the element when calling
HM_f_ToggleElementList.) Sadly, this is a limitation of the Netscape 4.x
browser itself and cannot be helped; it's one of the many crosses we must bear
when dealing with older browsers.
Note the use of inherit when restoring the visibility of
objects, instead of the more commonly used visible (or show).
visible works fine in most instances, but when objects are nested within
other objects and both the internal and external objects are hidden and made
visible again, the results can be confusing and are inconsistent among
many browsers. The difference has to do with whether or not the browser honors
the visibility setting of visible on nested objects when their container
objects are marked hidden. Some browsers will (Mozilla, IE5+) and some
will not (IE4, Opera). Thus, even if you hide a particular parent object, some of
its children may still remain visible (specifically, the children that have previously
been hidden and then made visible using the visible parameter setting).
To examine this behavior for yourself, have a look at
this page, which is identical to the previously
supplied example with the exception that on this page we use the visible
keyword instead of inherit. Try clicking each pair of links on the page,
and then click through to each pair of links again. Note that the <select>
specific links work consistently across all browsers, since they represent the innermost
elements of the page (or at least the innermost elements whose visibility we're
toggling). Hiding and showing the outer form or div element, however,
produces interesting results since in some browsers the inner select elements may or
may not be hidden depending on whether or not you've already toggled them on the
page.
Compare this behavior with that of the sample page containing our
actual function (earlier on this page). The result using inherit is consistent
among browsers and probably closer to what you actually want when hiding a
container object.
What About HierMenus?
Now that we've examined the standalone function in detail,
let's see what's necessary to incorporate it into your
v4.x or later HierMenus installation.
  
[previous] [next]
|
