MozillaZine

Bindings

From MozillaZine Knowledge Base

Bindings are a way to extend CSS in Mozilla applications to achieve complex effects. Mozilla applications use bindings extensively to create elements in the user interface. This article describes how to use bindings to extend your own CSS in userChrome.css or userContent.css files.

Bindings use an XML-based language, XBL, which in turn can include JavaScript code.

Contents

Enabling user bindings

Bindings are normally allowed only in the Mozilla application's own code and in extensions. To allow bindings to be used in the chrome directory where your userChrome.css and userContent.css files are, you must use an extension to enable them.

For example, install the User Chrome extension, which enables bindings in the chrome directory by defining a "chrome://userchrome/content" base URL and does nothing else.

  • Starting with Firefox 4.0, Thunderbird 5.0, and SeaMonkey 2.1, the preference extensions.alwaysUnpack has to be toggled to "true" prior to installing the User Chrome extension.
  • For SeaMonkey 2.0 and later, you also have to add its compatibility information to the install.rdf file in chrome.xpi (e.g., by replacing the Flock UUID with SeaMonkey's 92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a), or disable compatibility checks.

Creating and editing a bindings file

To create a bindings file, use your operating system tools. The bindings file is designed to be manually edited using a text editor. Anything valid in an XBL file is valid in this file. To make your definitions or any changes take effect, you must restart the application.

Go to your profile folder. Then go to the chrome folder there, creating it if necessary. In the chrome folder, create a plain text file named: userChrome.xml

The file name is not important, but the name userChrome.xml is used in the example that follows.

Copy and paste the following code into the file:

<?xml version="1.0"?>
<!DOCTYPE bindings >
<bindings xmlns="http://www.mozilla.org/xbl"
 xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<!-- bindings go here -->

</bindings>

This creates an empty bindings file. You can add whatever bindings you need in the body of the file, replacing the comment <!-- bindings go here -->. Ensure that the </bindings> end tag is always the last thing in the file, no matter how many bindings there are.

Notes:

  • If you have more than one profile, then each of your profiles has a separate userChrome.xml file.
  • There is another chrome folder where the Mozilla application's code is installed. Do not create a userChrome.xml file there—it will not work.

Defining a binding

To create a working binding there are two steps: specify the binding in a bindings file, and write a CSS rule that binds elements of the user interface to the binding.

For example, when you write an e-mail message in Thunderbird and attach a file with a long name, the attachments list does not expand to show the entire file name. This is because the column displaying the attachments has a flex attribute that allows it to contract, cropping the file name. You cannot override this attribute using CSS alone, but you can override it using a binding.

First add a binding to your bindings file, userChrome.xml. The following binding removes the flex attribute:

<binding id="attachment-listcol">
  <implementation>
    <constructor><![CDATA[
    this.removeAttribute("flex")
    ]]></constructor>
  </implementation>
</binding>

Then add a CSS rule to your userChrome.css file, binding every listcol element in every list of attachments:

#attachmentBucket listcol {
  -moz-binding: url(chrome://userchrome/content/userChrome.xml#attachment-listcol);
}

Extending a binding

Frequently a binding is already provided in the application, but you'd like to make modifications to a method and/or add further methods. To do this, you'll need first to identify the respective binding and its location. For the following sequence, let's assume you want to derive a modified version of a (fictional) test binding, naming it mytest:

  • Start out as before defining your mytest binding.
  • Search in http://mxr.mozilla.org/ for the -moz-binding URL of test, then add the original's path and name to the new binding you define in an extends attribute:
<binding id="mytest" extends="chrome://somewhere/content/something.xml#test">
  • Define an <implementation> and then <method> for any method you want to overlay (all other definitions of the original binding are inherited unless overridden).
  • Trying to overlay a <handler> may execute both the original handler and the one defined in your extending binding if only an event but no id is identified.
  • Follow the rules for the userChrome.css entry to associate your modified mytest binding which each element using the original binding, where you will need to add an !important to ensure that your binding will be taken.

An example for overriding the buildViews method in Thunderbird's mail-multi-emailHeaderField method is given in this forum thread. Instead of replacing the binding for specific elements, you could also use the original's binding name in userChrome.css to apply for all elements using this binding.

Moving and copying a bindings file

You can move or copy userChrome.xml to a different profile. If it imports or references other files such as images, then you must also move or copy these other files. To make the changes take effect, you must restart the application.

Deleting a bindings file

You can delete userChrome.xml to get rid of any user bindings defined there. You should also delete the CSS rules that refer to those bindings. To make the change take effect, you must restart the application.

Troubleshooting

For some information about common problems, see: Editing configuration – Troubleshooting

Related files and folders

See also

External links