WebReference.com - Part 1 of chapter 5 from Creating Applications with Mozilla. From O'Reilly (3/6).

Methods in the DOM allow you to access and manipulate any element in the user interface or in the content of a web page. Getting and setting attributes, creating elements, hiding elements, and appending children all involve direct manipulation of the DOM. The DOM mediates all interaction between scripts and the interface itself, so even when you do something as simple as changing an image when the user clicks a button, you use the DOM to register an event handler with the button and DOM attributes on the image element to change its source.

The DOM Level 1 and Level 2 Core specifications contain multiple interfaces, including Node, NodeList, Element, and Document. The following sections describe some interface methods used to manipulate the object model of application chrome, documents, or metadata in Mozilla. The Document and Element interfaces, in particular, contain useful methods for XUL developers.

The code samples in this chapter use a method called dump( ) to print data to STDOUT. This method is primarily used for debugging your code and is turned on using a PREF. You can turn this PREF on using the following code:

const PREFS_CID      = "@mozilla.org/preferences;1";
const PREFS_I_PREF   = "nsIPref";
const PREF_STRING    = "browser.dom.window.dump.enabled";
try {
var Pref        = new Components.Constructor(PREFS_CID, PREFS_I_PREF);
var pref        = new Pref( );
pref.SetBoolPref(PREF_STRING, true);
} catch(e) {}

This code is necessary only if you are doing development with a release distribution build of Mozilla. If you are using a debug or nightly build, this PREF can be set from the preferences panel by selecting Edit > Preferences > Debug > Enable JavaScript dump( ) output.

getElementById(aId) is perhaps the most commonly used DOM method in any programming domain. This is a convenient way to get a reference to an element object by passing that element's id as an argument, where the id acts as a unique identifier for that element.

DOM calls like this are at the heart of Mozilla UI functionality. getElementById is the main programmatic entry point into the chrome and is essential for any dynamic manipulation of XUL elements. For example, to get a box element in script (i.e., to get a reference to it so you can call its methods or read data from it), you must refer to it by using the box id:

<box id="my-id" />

Since the return value of getElementById is a reference to the specified element object, you usually assign it to a variable like this:

var boxEl = document.getElementById('my-id');
dump("boxEl="+boxEl+"\n");
console output: boxEl=[object XULElement]

Once you have the box element available as boxEl, you can use other DOM methods like getAttribute and setAttribute to change its layout, its position, its state, or other features.

Attributes are properties that are defined directly on an element. XUL elements have attributes such as disabled, height, style, orient, and label.

<box id="my-id" foo="hello 1" bar="hello 2" />

In the snippet above, the strings "my-id," "hello 1," and "hello 2" are values of the box element attributes. Note that Gecko does not enforce a set of attributes for XUL elements. XUL documents must be well-formed, but they are not validated against any particular XUL DTD or schema. This lack of enforcement means that attributes can be placed on elements ad hoc. Although this placement can be confusing, particularly when you look at the source code for the Mozilla browser itself, it can be very helpful when you create your own applications and want to track the data that interests you.

Once you have an object assigned to a variable, you can use the DOM method getAttribute to get a reference to any attribute in that object. The getAttribute method takes the name of the desired attribute as a string. For example, if you add an attribute called foo to a box element, you can access that attribute's value and assign it to a variable:

<box id="my-id" foo="this is the foo attribute" />
<script>
var boxEl = document.getElementById('my-id');
var foo   = boxEl.getAttribute('foo');
dump(foo+'\n');
</script>

The dump method outputs the string "this is the foo attribute," which is the value of the attribute foo. You can also add or change existing attributes with the setAttribute DOM method.

[previous] [next]

Created: September 19, 2002
Revised: September 19, 2002

URL: https://webreference.com/programming/javascript/mozillaapps/chap5/1/3.html