Chapter 7. Extending the UI with XBL

You now know that XUL is the basic tool set for creating your application interface, but even it has limitations. It is just a finite set of widgets that your programming needs may transcend. If you find that you reimplement many of the same groups of widgets in different applications, or if you want to extend your application's interface in some other way, you will find the eXtensible Binding Language (XBL) an invaluable tool.

This chapter describes what XBL is and how it is used. Basically, XBL provides a way to attach new content or behavior to your application by using XBL bindings. XBL can extend, add to, and reorganize user interfaces. XBL can also help you organize scattered XUL code into a set of self-contained widgets that make building and maintaining your Mozilla application much easier. Appendix C provides a reference for the XBL element set, with which new elements can be created.

7.1. What Is XBL?

XBL is an XML markup language invented specifically for creating widgets. XBL looks similar to XUL, and may even contain XUL or HTML and other markup (see the Section 7.1.3 section later in this chapter for more information about how other markup is used in XBL bindings), but its purpose is different. Flexibility and interoperability are the point of XBL.

If the XUL textbox is inadequate, for example, you can use XBL to create and attach a new widget called <datafield/>, possibly based on textbox, that provides special attributes and functionality for validating input data against a database.

A binding is a single XBL language entity that can contain content as other markup (such as XUL) behavior that is represented as methods and properties, and event-handling capabilities. Bindings can be anything from small widget objects to large, complex blocks of code with extensive functionality. Figure 7-1 shows the different components that make up a binding: fields, properties, functions, event handlers, and content. The section Section 7.2, later in this chapter, provides more detail about a binding's structure.

Bindings differ from XUL overlays because they are fully self-contained, reusable, and generally have no dependencies outside of the binding itself. Although XUL is used most often as content in an XBL binding, XBL can also bind to and from HTML and XML. If you have worked with Java or C#, you may recognize some parallels between XBL bindings and Java objects.

7.1.1. XBL Terminology

The following terms are used to describe XBL and its use in the XPFE:


An acronym for the eXtensible Binding Language. In some contexts, the term XBL refers to actual code (e.g., "the XBL in this example . . . "). XBL is an XML syntax.


A single unit of the XBL language, one or more of which is contained in a binding document. Most bindings are made up of content and implementation, although each are mutually exclusive; if you add event handlers to that list, each one can appear on its own in a binding.

Binding document

An XBL file with an .xml extension that contains one or more bindings.

Bound document

A XUL (or HTML) document that has one or more bindings attached to it as content.

Bound element

A bound element is a widget or element that uses a particular binding. It can be an existing element in the XUL or HTML set or a newly invented one.

Anonymous content

Content (e.g., XUL elements) contained in a binding that is hidden from the document object (DOM). Refer to the section Section 7.4, later in this chapter, for a more detailed discussion of its characteristics and how to programmatically gain access to the content.

Attachment and detachment

Attachment is the process through which a binding is associated with a bound element. It is essentially a way of telling the element which binding to use. Detachment is the process of removing that link and with it, the binding display.

Insertion point

The point in anonymous content at which children of the bound element are inserted. The section Section 7.4.4, later in this chapter, details the insertion process.


During inheritance, characteristics of one object are passed on to another object. In XBL, this process is multifaceted. Bindings can inherit from other bindings, anonymous content can inherit attributes from the bound element, and a binding implementation can inherit the behavior of another widget. All concepts are explained in the section Section 7.5, later in this chapter.

7.1.2. An XBL Document

XBL documents are files saved with an .xml filename extension. Most bindings implement XUL content and behavior with script, so XBL files reside in your XUL application's chrome content area and have full access to XPConnect-wrapped XPCOM objects.

Several bindings often reside inside the same XBL file. Performance benefits from this arrangement, if you have multiple related bindings, because only one XBL document needs to be loaded, rather than multiple documents. Organization is another factor. Mozilla has dozens of bindings that are interrelated by either inheritance or filename identifiers. Individual pieces to a menu widget reside in a file called menu.xml, button bindings are in button.xml, and so forth. Keeping these bindings together is wise.

The XBL document's root container is the <bindings> tag. Inside this element is one or more individual child bindings, defined by the <binding> tag. A simple XBL document is as follows:

<?xml version="1.0"?>
<bindings id="dataBindings" ...>
  <binding />
  <binding />

An XBL document is a valid XML document. The XML preamble you are used to seeing in XUL files is present. It also contains the single root element (in this case, <bindings>) and the child nodes that define the bindings (empty).

Bindings are the atomic units of an XBL document. An XBL document may define any number of individual bindings, each of which is bound (i.e., associated with other XML/XUL elements by way of CSS class definitions) somewhere in the interface. In other words, an XBL document may be a set of unrelated or barely related bindings that are picked up by the XUL interface.

7.1.3. Namespaces and XBL

Because XBL is a binding language for other markup, remember to distinguish between the XBL markup (such as <binding> and <handler>) and markup from another language (such as XUL). Namespaces are a feature of the XML language that was invented to handle this separation of intermingled markup, and XBL uses namespaces. For more information on namespaces, refer to the W3C at

Namespaces are declared in the root element of an XML document. The most common implementation is the declaration of two namespaces: a default namespace for XBL and a namespace for the other markup. This code shows the root of a bindings document in which the XUL namespace declaration (xmlns:xul) and the XBL default namespace are declared:

<bindings id="dataBindings" 

An NCName is the part of a namespace declaration that qualifies the markup type for that particular namespace. It is placed after a colon, and in many XPFE documents, is the markup language name (xul, xbl, or rdf). The XBL namespace is the default in this instance because it does not declare a namespace prefix (NCName).

You can choose to namespace your document in a different way. For example, if you have a large mass of XUL code in your binding and do not wish to use the xul: prefix repeatedly, you can declare the XBL namespace as xmlns:xbl; you won't need to use prefixes on the XUL content since it is set as the default. Another option is to namespace a parent element:

<box xmlns="">

This code enables all children inside the <box> to be in the scope of the XUL namespace; therefore the explicit xul: tag prefix declaration is not necessary.