Bindings

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.

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.

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.

Creating 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);
}

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

• userChrome.css
• userChrome-example.css
• userContent.css
• userContent-example.css
• userChrome.js

See also

• Chrome element names and IDs
• Editing configuration

External links

• XBL Starting Page at the Mozilla Developer Center
• XBL Tutorial at the Mozilla Developer Center
• Insert HTML button—using a binding to add a button in Thunderbird's formatting toolbar.
• Deactivate right mouse click on tab—using a binding to prevent Thunderbird tabs from closing when right-clicked
• Hide the Smart Folders view—using a binding to disable Thunderbird's Smart Folders (Unified Folders) view
• Display attachments at the top and Display attachments at the side—using bindings to move Thunderbird's attachments pane around
• Disable the "more"-button logic—extending an existing binding in Thunderbird 3.1 to display all e-mail addresses without showing the "more" in any case