XUL Tutorial

http://www.xulplanet.com/

<All pictures are omitted>

The XUL Tutorial was created by Neil Deakin, upload by thp117

1. Introduction

Introduction

This tutorial guides you to learning XUL (XML User-interface Language) which is a cross-platform language for describing user interfaces of applications.

This tutorial will demonstrate creating a simple find file user interface, much like that provided by the Macintosh's Sherlock or the find file dialog in Windows. Note that only the user interface will be created and some limited functionality. The actual finding of files will be not be implemented. A blue line will appear to the left of a paragraph where the find file dialog is being modified. You can follow along at these sections.

What is XUL and why was it created?

XUL (pronounced zool and it rhymes with cool) was created to make development of the Mozilla browser easier and faster. It is an XML language so all features available to XML are also available to XUL.

Most applications need to be developed using features of a specific platform making building cross-platform software time-consuming and costly. A number of cross-platform solutions have been developed in the past. Java, for example, has portability as a main selling point. XUL is one such language designed specifically for building portable user interfaces. It takes a long time to build an application even for only one platform. The time required to compile and debug can be lengthy. With XUL, an interface can be implemented and modified quickly and easily.

XUL has all the advantages of other XML languages. For example XHTML or other XML languages such as MathML or SVG can be inserted within it. Also, text displayed with XUL is easily localizable, which means that it can be translated into other languages with little effort.

What kinds of user-interfaces can be made with XUL?

XUL provides the ability to create most elements found in modern graphical interfaces. Some elements that can be created are:

Input controls such as textboxes and checkboxes

Toolbars with buttons or other content

Menus on a menu bar or pop up menus

Tabbed dialogs

Trees for hierarchical or tabular information

Keyboard shortcuts

The displayed content can be created from the contents of a XUL file or with data from a datasource. In Mozilla, such datasources include a user's mailbox, their bookmarks and search results. The contents of menus, trees and other elements can be populated with this data, or with your own data supplied in an RDF file.

There are several ways that XUL applications are created:

Firefox extension - an extension adds functionality to the browser itself, often in the form of extra toolbars, context menus, or UI to customize the browser UI. This is done using a feature of XUL called an overlay, which allows the UI provided from one source, in this case, the Firefox browser, to be merged together with the UI from the extension. Extensions may also be applied to other Mozilla based products such as Thunderbird.

Standalone XULRunner application - XULRunner is a packaged version of the Mozilla platform which allows you to create standalone XUL applications. A browser isn't required to run these applications, as they have their own executable file.

XUL package - in between the other two are applications which are created in the same way as an extension, but they act like a separate application in a separate window. This is used when you don't want to have the larger size of a complete XULRunner application, but don't mind requiring a Mozilla browser to be installed to be able to run the application.

Remote XUL application - you can also just place XUL code on a web server and open it in a browser, as you would any other web page. This method is limited however, as there will be security concerns that will limit the kinds of things you will be able to do, such as opening other windows.

The first three types all require an installation to be performed on the user's machine. However, these types of applications do not have security restrictions placed on them, so they may access local files and read and write preferences, for example. For extensions, the XUL files and associated scripts and images used by an application would be packaged into a single file and downloaded and installed by the user. Mozilla applications such as Firefox provide an extension manager which allows packages to be installed without having to write a lot of complex code.

It is also possible to open XUL files directly from the file system or from a remote web site, however they will be restricted in the kinds of operations they can do, and some aspects of XUL will not work. However, if you do want to load XUL content from a remote site, the Web server must be set up to send XUL files with the content type 'application/vnd.mozilla.xul+xml'. XUL is usually stored in files with a .xul extension. You can open a XUL file with Mozilla as you would any other file, using the Open File command from the File menu or typing the URL into the address bar.

What do I need to know to use this tutorial?

You should have an understanding of HTML and at least a basic understanding of XML and CSS. Here are some guidelines to keep in mind:

XUL elements and attributes should all be entered in lowercase as XML is case-sensitive (unlike HTML).

Attribute values in XUL must be placed inside quotes, even if they are numbers.

XUL files are usually split into four files, one each for the layout and elements, for style declarations, for entity declarations (used for localization) and for scripts. In addition, you may have extra files for images or for platform specific data.

XUL is supported in Mozilla and browsers that are also based upon on the Gecko engine, such as Netscape 6 or later and Mozilla Firefox. Due to various changes in XUL syntax over time, you will want to get the latest version for the examples to work properly. Most examples should work in Mozilla 1.0 or later. XUL is fairly similar in Firefox and in other Mozilla-based browsers, although there are some specific differences such as support for customizable toolbars.

This tutorial attempts to cover much of XUL's functionality, however, not all features are discussed. Once you are familiar with XUL, you can use the XUL Element Reference to find out about other features supported by specific elements.

XUL Structure

We'll begin by looking at how the XUL is handled in Mozilla.

How XUL is Handled

In Mozilla, XUL is handled much in the same way that HTML or other types of content are handled. When you type the URL of an HTML page into the browser's address field, the browser locates the web site and downloads the content. The Mozilla rendering engine takes the content in the form of HTML source and transforms it into a document tree. The tree is then converted into a set of objects that can be displayed on the screen. CSS, images and other technologies are used to control the presentation. XUL functions in much the same way.

In fact, in Mozilla, all document types, whether they are HTML or XUL, or even SVG are all handled by the same underlying code. This means that the same CSS properties may be used to style both HTML and XUL, and many of the features can be shared between both. However, there are some features that are specific to HTML such as forms, and others which are specific to XUL such as overlays. Since XUL and HTML are handled in the same way, you can load both from either your local file system, from a web page, or from an extension or standalone XULRunner application.

Content from remote sources, regardless or whether they are HTML or XUL or another document type, are limited in the type of operations they can perform, for security reasons. For this, reason, Mozilla provides a method of installing content locally and registering the installed files as part of its chrome system. This allows a special URL form to be used called a chrome URL. By accessing a file using a chrome URL, the files receive elevated privileges to access local files, access preferences and bookmarks and perform other privileged operations. Obviously, web pages do not get these privileges, unless they are signed with a digital certificate and the user has granted permission to perform these operations.

This chrome package registration is the way in which Firefox Extensions are able to add features to the browser. The extensions are small packages of XUL files, Javascript, style sheets and images packed together into a single file. This file can be created by using a ZIP utility. When the user downloads it, it will be installed onto the user's machine. It will hook into the browser using a XUL specific feature called an overlay which allows the XUL from the extension and the XUL in the browser to combine together. To the user, it may seem like the extension has modified the browser, but in reality, the code is all separate, and the extension may be uninstalled easily. Registered packages are not required to use overlays, of course. If they don't, you won't be able to access them via the main browser interface, but you can still access them via the chrome URL, if you know what it is.

Standalone XUL applications may include XUL code in a similar way, but, of course, the XUL for application will be included will be included as part of the installation, instead of having to be installed separately as an extension. However, this XUL code will be registered in the chrome system such that the application can display the UI.

It is worth noting that the Mozilla browser itself is actually just a set of packages containing XUL files, JavaScript and style sheets. These files are accessed via a chrome URL and have enhanced privileges and work just like any other package. Of course, the browser is much larger and more sophisticated than most extensions. Firefox and Thunderbird as well as number of other components are all written in XUL and are all accessible via chrome URLs. You can examine these packages by looking in the chrome directory where Firefox or another XUL application is installed.

The chrome URL always begins with 'chrome://'. Much like how the 'http://' URL always refers to remote web sites accessed using HTTP and the 'file://' URL always refers to local files, the 'chrome://' URL always refers to installed packages and extensions. We'll look more at the syntax of a chrome URL in the next section. It is important to note that when accessing content through a chrome URL, it gains the enhanced privileges described above that other kinds of URLs do not. For instance, an HTTP URL does not have any special privileges, and an error will occur if a web page tries, for example, to read a local file. However, a file loaded via a chrome URL will be able to read files without restriction.

This distinction is important. This means that there are certain things that content of web pages cannot do, such as read the user's bookmarks. This distinction is not based on the kind of content being displayed; only on the type of URL used. Both HTML and XUL placed on a web site have no extra permissions; however both HTML and XUL loaded through a chrome URL have enhanced permissions.

If you are going to use XUL on a web site, you can just put the XUL file on the web site as you would an HTML file, and then load its URL in a browser. Ensure that your web server is configured to send XUL files with the content type of 'application/vnd.mozilla.xul+xml'. This content type is how Mozilla knows the difference between HTML and XUL. Mozilla does not use the file extension, unless reading files from the file system, but you should use the .xul extension for all XUL files. You can load XUL files from your own machine by opening them in the browser, or by double-clicking the file in your file manager. Remember that remote XUL will have significant restrictions on what it can do.

Mozilla uses a distinctly different kind of document object for HTML and XUL, although they share most of their functionality. There are three main types of document in Mozilla: HTML, XML and XUL. Naturally, the HTML document is used for HTML documents, the XUL document is used for XUL documents, and the XML document is used for other types of XML documents. Since XUL is also XML, the XUL document is a subtype of the more generic XML document. There are subtle differences in functionality. For example while the form controls on an HTML page are accessible via the 'document.forms' property, this property isn't available for XUL documents since XUL doesn't have forms in the HTML sense. On the other hand, XUL specific features such as overlays and templates are only available in XUL documents.

This distinction between documents is important. It is possible to use many XUL features in HTML or XML documents since they aren't document type specifc, however other features require the right kind of document. For instance, you can use the XUL layout types in other documents since they don't rely on the XUL document type to function.

To summarize the points made above:

Mozilla renders both HTML and XUL using the same underlying engine and uses CSS to specify their presentation.

XUL may be loaded from a remote site, the local file system, or installed as a package and accessed using a chrome URL. This is what browser extensions do.

Chrome URLs may be used to access installed packages and open them with enhanced privileges.

HTML, XML and XUL each have a different document type. Some features may be used in any document type whereas some features are specific to one kind of document.

The next few sections describe the basic structure of a chrome package which can be installed into Mozilla. However, if you just want to get started building a simple application, you may skip ahead to section 2 and save this section for later.

Package Organization

Mozilla is organized in such a way that you can have as many components as you want pre-installed. Each extension is also a component with a separate chrome URL. It will also have one component for each installed theme and locale. Each of these components, or packages, is made up of a set of files that describe the user interface for it. For example, the messenger component will have descriptions of the mail messages list window, the composition window and the address book dialogs.

The packages that are provided with Mozilla are located within the chrome directory, which you will find in the directory where you installed Mozilla. The chrome directory is where you will find all the files that describe the user interface used by the Mozilla browser, mail client and other applications. You will typically put all of the XUL files for an application in this directory, except for extensions which will be installed in the extensions directory for a particular user. Just copying a XUL file into the 'chrome' directory doesn't give the file any extra permissions nor can it be accessed via a chrome URL. To gain the extra privileges, you will need to create a manifest file and put that in the chrome directory. This file is easy to create, as it is typically only a couple of lines long. It is used to map a chrome URL to a file or directory path on the disk where the XUL files are located. Details of how to create this file will be discussed in the next section.

The only way to create content that can be accessed through a chrome URL is by creating a package as described in the next few sections. This directory is called 'chrome' likely because it seemed like a convenient name to use for the directory where the chrome packages that are included with Mozilla are kept.

To further the confusion, there are two other places where the word chrome might appear. The first is the '-chrome' command line argument, and the chrome modifier to the 'window.open' function. Neither of these features grant extra privileges; instead they are used to open a new top-level window without the browser UI such as the menu and toolbar. You will commonly use this feature in more complex XUL applications since you wouldn't want the browser UI to exist around your dialog boxes.

The files for a package are usually combined into a single JAR file. A JAR file may created and examined using a ZIP utility. For instance, you can open the JAR files in Mozilla's chrome directory to see the basic structure of a package. Although it's normal to combine the files into a JAR file, packages may also be accessed in expanded form into a directory. Although you don't normally distribute a package this way, it is handy during development since you can edit the file directly and then reload the XUL file without having to repackage or reinstall the files.

There are usually three different parts to a chrome package, although they are all optional. Each part is stored in a different directory. These three sets are the content, the skin and the locale, described below. A particular package might provide one or more skins and locales, but a user can replace them with their own. In addition, the package might include several different applications each accessible via different chrome URLs. The packaging system is flexible enough so that you can include whatever parts you need, and allow other parts, such as the text for different languages, to be downloaded separately.

The three types of chrome packages are:

Content - Windows and scripts

The declarations of the windows and the user interface elements contained within them. These are stored in XUL files, which have a xul extension. A content package can have multiple XUL files, but the main window should have a filename that is the same as the package name. For example, the editor package will have a file within it called editor.xul. Scripts are placed in separate files alongside the XUL files.

Skin - Style sheets, images and other theme specific files

Style sheets describe details of the appearance of a window. They are stored separately from XUL files to facilitate modifying the skin (theme) of an application. Any images used are stored here also.

Locale - Locale specific files

All the text that is displayed within a window is stored separately. This way, a user can have a set for their own language.

Content Packages

The name of the JAR file might describe what it contains, but you can't be sure unless you view its contents. Let's use the browser package included with Firefox as an example. If you extract the files in browser.jar, you will find that it contains a directory structure much like the following:

content

browser

browser.xul

browser.js

-- other mail XUL and JS files goes here --

bookmarks

-- bookmarks files go here --

preferences

-- preferences files go here --

.

.

.

This is easily recognizable as a content package, as the top-level directory is called 'content'. For skins, this directory will usually be called 'skin' and for locales, it will usually be called 'locale'. This naming scheme isn't necessary but this is a common convention to make the parts of a package clearer. Some packages may include a content section, a skin and a locale. In this case, you will find a subdirectory for each type. For example, Chatzilla is distributed in this way.

The content/browser directory contains a number of files with xul and js extensions. The XUL files are the ones with the xul extension.