7.4. XBL and the DOM

7.4.1.1. DocumentXBL methods

The DocumentXBL interface gains access to and interacts with an XBL document. The methods of this interface are as follows:

document.loadBindingDocument('chrome://package/content/myBindings.xml');

var listbox = document.getBindingParent(this);
var cellValue = listbox.childNodes[3].firstChild.label;

7.4.1.2. ElementXBL methods

The ElementXBL interface adds and removes bindings from a bound element. The methods of this interface are as follows:

7.4.1.3. Dynamically adding a binding

The section Section 7.2 covered the attachment of a binding to a bound element using CSS. This technique is the most common method, but you can also attach bindings with the addBinding method.

Using this method as an alternative to CSS attachment is useful when you do not want to attach a binding in all circumstances. In an application based on user input, you may not want to load a binding until certain values are entered. For example, in a membership database, the information that appears on screen may depend on the user's level of membership. The following snippets show how it is used.

<mybinding id="myNewWidget" class="attached" />

To load a binding, add these two lines in your script.

var binding = document.getElementById("myNewWidget");
document.addBinding(binding, "chrome://mypackage/content/myBindings.xml#super");

Notice that the URL used to access the binding takes the same format as in the CSS property -- i.e., the path to the file and the id of the binding qualified by #.

Neither addBinding nor removeBinding are implemented at the time of writing. They are covered because they are part of the XBL 1.0 specification. When implemented, they offer crucial alternatives for attaching and detaching bindings, making XBL a more interactive technology.

7.4.1.4. Removing bindings

The best way to remove a binding attached via CSS is to change the style rule for that element. You can change the class to one that does not have a different or null binding reference, for example. Then a stylesheet can be set up to provide binding references for both an attached and unattached element.

This example shows how to remove a reference to a binding by resetting it to an empty reference:

mybinding.attached {
  -moz-binding : url("mybindings.xml#my-binding");
}
mybinding.unattached {
  -moz-binding : url("");
}

When you want to detach the binding from an element, you can do this:

var mywidget = document.getElementById("binding1");
mywidget.setAttribute("class","unattached");

An element can have only one binding attached at a time, so this is a programmatic trick for knocking the "real" binding out of its place with an empty one, rather than actually removing it.

-moz-binding:url("") can be used at this time as a hack around the -moz-binding:none binding. The later binding does not currently work in Mozilla.

The other method used to detach a binding, which is more intuitive from a DOM perspective, uses the removeBinding method:

var binding = document.getElementById("myNewWidget");
document.removeBinding(binding, "chrome://mypackage/content/myBindings.xml#super");

This method ensures that other style information is not lost if you have it attached to a particular class.

When a binding is removed, the anonymous content is destroyed and the methods, properties, and event handlers no longer apply.

In the case of an inheritance chain (see the Section 7.5 section later in this chapter for more details), the bindings are destroyed from the bottom upwards. This means that if there is tear-down code in the form of a destructor, it is executed last on the base binding.

7.4.3.1. getAnonymousNodes

The method getAnonymousNodes(element) takes a node as a parameter and returns a list of nodes that are in the anonymous content. The following code uses script in the <getter> to access the anonymous node and return a value contained in it.

<getter>
  <![CDATA[
    var list = document.getAnonymousNodes(this)[0];
    return list.selectedItem.getAttribute('label');
  ]]>
</getter>

If we assume that this binding's content is a XUL menu list, then this code gets the label attribute of the menu item that is currently selected in that list (list.selectedItem). The list variable contains the value returned by the getAnonymousNodes function, which is passed the binding node (this). The method returns an array, so the item is accessed via the first index of 0.

7.4.3.2. getAnonymousElementByAttribute

The method getAnonymousElementByAttribute(element, attr, value) returns a single anonymous node rather than a list. This node is qualified by an element name, a particular attribute, and the value of that attribute, and returns this specific node. This retrieval provides faster access to anonymous content elements when you know an attribute's value.

<property name="emailID" onget="return document.getAnonymousElementByAttribute(this, 'id', 'emailAddressNode');" readonly="true"/>

This example uses an id attribute to retrieve a specific node. You can use this method when multiple elements of the same type exist and you need to get access to a particular one -- for example, a particular field on a database entry submission form like an email address or a telephone number.

Although these two functions (getAnonymousNodes and getAnonymousElementsByAttribute) were probably designed to be used within a binding scope, they can be used both inside and outside a binding to access anonymous content. Bindings are meant to be self-contained, and getting anonymous nodes outside a binding breaks this philosophy. However, these functions can act as a bridge between scopes if you are careful.

7.4.4.1. Working with children of the bound element

Zero or more children can be contained in anonymous content. These children are marked up with the XBL-specific <children> tag. They can be either the content of the element using the binding or anonymous content generated by the base binding. If the <children> tag contains its own elements, then it will be used as the default content. If the element the binding is attached to contains children, the default content will be ignored.

The location of the <children> tags determines the content's insertion point. Insertion points play an important role in the generation of content within a template because they affect how the content is displayed and accessed by the DOM.

<binding id="my-binding">
  <content>
    <xul:vbox>
      <children />
    </xul:vbox>
  </content>
</binding>

This stripped-down binding has only a vertical box as its own content and looks to the children of the bound element for more content by using the <children> element. Here is the XUL content that uses the binding:

<mybinding id="myNewWidget" flex="1" class="attached">
  <label value="this is child 1" />
  <label value="this is child 2" />
</mybinding>

When the binding is attached and the content is drawn, the insertion point for the two labels is inside the container vertical box inside the binding. This scenario could be used when a binding is used multiple times. Each time, it needs to be rendered differently with extra content that can be provided this way.

7.4.4.2. Selective inclusion

Sometimes multiple siblings are located within a box in the XUL, but you want to use only some of them in the binding, such as when a user logs into a system and content is displayed depending on its level of membership. In these cases, you can be selective about which children should be included in the binding. Example 7-5 shows how to use the includes attribute on the <children> element.

<binding id="my-binding">
  <content>
    <xul:vbox class="insideBox">
      <xul:description value="Top" />
      <xul:box>
        <children includes="image" />
      </xul:box> 
      <xul:description value="Bottom" />
    </xul:vbox>
  </content>
</binding>

The children element in Example 7-5 essentially tells, "Of all the content contained in the bound element, insert only the image element at this particular insertion point." Here is the XUL code that goes with this example:

<mybinding id="myNewWidget" flex="1">
  <image src="http://www.mozdev.org/sharedimages/header.gif" />
  <label value="a non includes element" />
</mybinding>

The image is the only child taken from the XUL content and the label is ignored.

If you have children that are not defined in the includes attribute, then the binding is discarded and not used. If the bound element uses another element in addition to an image element, the binding is discarded and only the explicit content is used. If the image element isn't used at all, the binding is discarded.

<mybinding id="myNewWidget" flex="1">
  <image src="http://www.mozdev.org/sharedimages/header.gif" />
  <label value="an element" />
</mybinding>

This example renders the image and the label and discards the binding. The anonymous content does not appear because the binding is discarded and only the explicit content is used.