Introduction to XBL

XUL has a sister language, XBL (eXtensible Bindings Language). This language is used for declaring the behavior of XUL widgets.

Bindings

You can use XUL to define the layout of a user interface for an application. You can customize the look of elements by applying styles to them. You can also create new skins by changing the styles. The basic appearance of all elements, such as scroll bars and check boxes may be modified by adjusting the style or by setting attributes on the element. However, XUL provides no means in which you can change how an element works (or add a new element which can be reused). For example, you might want to change how the pieces of a scroll bar function. For this, you need XBL.

An XBL file contains a set of bindings. Each binding describes the behavior of a XUL widget. For example, a binding might be attached to a scroll bar. The behavior describes the properties and methods of the scroll bar in addition to describing the XUL elements that make up a scroll bar.

Like XUL, XBL is an XML language, so it has similar syntax rules. The following example shows the basic skeleton of an XBL file:

<?xml version="1.0"?>
<bindings xmlns="http://www.mozilla.org/xbl">
  <binding id="binding1">
    <!-- content, property, method and event descriptions go here -->
  </binding>
  <binding id="binding2">
    <!-- content, property, method and event descriptions go here -->
  </binding>
</bindings>

The bindings element is the root element of an XBL file and contains one or more binding elements. Each binding element declares a single binding. The id attribute can be used to identify the binding, as in the example above. The template has two bindings, one called binding1 and the other called binding2. One might be attached to a scroll bar and the other to a menu. A binding can be attached to any XUL element. If you use CSS classes, you can use as many different bindings as you need. Note the namespace on the bindings element in the template above. This declares that we are using XBL syntax.

You assign a binding to an element by setting the CSS property -moz-binding to the URL of the bindings file. For example:

scrollbar {
    -moz-binding: url('chrome://findfile/content/findfile.xml#binding1');
}

The URL points to the binding with the id 'binding1' in the file 'chrome://findfile/content/findfile.xml'. The '#binding1' syntax is used to point to a specific binding, much like how you would point to an anchor in an HTML file. You will usually put all of your bindings in a single file. The result in this example, is that all scrollbar elements will have their behavior described by the binding 'binding1'.

A binding has five types of things that it declares:

1. Content: child elements that are added to the element that the binding is bound to.
2. Properties: properties added to the element. They can be accessed through a script.
3. Methods: methods added to the element. They can be called from a script.
4. Events: events, such as mouse clicks and keypresses that the element will respond to. The binding can add scripts to provide default handling. In addition new events can be defined.
5. Style: custom style properties that the XBL defined element has.

Binding Example

The box is generic enough that you can use it to create custom widgets (although you can use any element, even one you make up yourself). By assigning a class to a box tag, you can associate a binding to only those boxes that belong to that class. The following example demonstrates this.

XUL (example.xul):

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<?xml-stylesheet href="chrome://example/skin/example.css" type="text/css"?>
<window
     xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <box class="okcancelbuttons"/>
</window>

CSS (example.css):

box.okcancelbuttons {
    -moz-binding: url('chrome://example/skin/example.xml#okcancel');
}

XBL (example.xml):

<?xml version="1.0"?>
<bindings xmlns="http://www.mozilla.org/xbl"
         xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <binding id="okcancel">
    <content>
      <xul:button label="OK"/>
      <xul:button label="Cancel"/>
    </content>
  </binding>
</bindings>

This example creates a window with a single box. The box has been declared to have a class of okcancelbuttons. The style sheet associated with the file says that boxes with the class okcancelbuttons have a specialized binding, defined in the XBL file. You may use other elements besides the box, even your own custom tags.

We'll look more at the details of the XBL part in the next section. However, to summarize, it causes two buttons to be added automatically inside the box, one an OK button and the other a Cancel button.

In the next section, we will look at creating content with XBL.