XUL Tutorial - Creating a Window

We're going to be creating a simple find files utility throughout this tutorial. First, however, we should look at the basic syntax of a XUL file.

Creating a XUL File

A XUL file can be given any name but it really should have a .xul extension. The simplest XUL file has the following structure:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<window
    id="findfile-window"
    title="Find Files"
    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 ...
</window>

A breakdown line by line is necessary:

1. <?xml version="1.0"?>
   

   This line simply declares that this is an XML file. Currently only one version exists (1.0) but if or when a new version is published, the browser can determine what version to expect. You would normally add this line as is at the top of each xul file, much like one would put the HTML tag at the top of an HTML file.

2. <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

   This line is used to specify the style sheets to use for the file. This is the syntax that XML files use to import style sheets. In the case, we import the styles found in the global/skin chrome directory. We didn't specify a specific file so Mozilla will determine which files in the directory to use. In the case, the all-important global.css file is selected. This file contains all the default declarations for all of the XUL elements. Because XML does not have any knowledge of how elements should be displayed, the file indicates how. Generally, you will put this line at the top of every XUL file. You can also import other style sheets using a similar syntax. Note that you would normally import the global style sheet from with-in your own style sheet file.

3. <window
   

   This line declares that you are describing a window. Each user interface window is described in a separate file. This tag is much like the BODY tag in HTML which surrounds the entire file. Several attributes can be placed in the window tag -- in this case there are three. In the example, each attribute is placed on a separate line but they do not have to be.

4. id="findfile-window"
   

   The id attribute is used as an identifier so that the window can be referred to by scripts. You will usually put an id attribute on all elements. The name can be anything you want although it should be something relevant.

5. title="Find Files"
   

   The title attribute describes the text that would appear on the title bar of the window when it is displayed. In this case the text 'Find Files' will appear.

6. xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

   This is an XML feature that indicates that the file is a XUL file. It looks strange. The xmlns attribute, which stands for XML namespace, indicates how Mozilla should interpret the tags. The URL specified would normally point to a definition of XUL. Since its a work in progress, this is just a dummy name and will probably change. For now, just add this to the window tag and everything should work fine. Note that this URL is never actually downloaded. Mozilla will recognize this URL internally.

7. ...
   

   This is where the elements (the buttons, menus and other user interface components) would be declared. We'll add some of these in the next set of sections.

8. </window>
   

   And finally, we need to close the window tag at the end of the file.

Opening a Window

In order to open a XUL window, there are several methods that can be used. If you are only in the development stage, you can just type the URL (whether a chrome:, file: or other URL type) into the location bar in a Mozilla browser window. The XUL window will appear in the browser window as opposed to a new window, but this is often sufficient during development.

The correct way, of course, is to open the window using JavaScript. No new syntax is necessary as you can use the window.open() function as one can do for HTML documents. However, one additional flag, called 'chrome' is necessary to indicate to the browser that this is a XUL document to open. The syntax is described below:

window.open(url,windowname,flags);
window.open(url,windowname,flags,secondary_url);

where the flags contains the flag "chrome". The secondary_url is only necessary in the case where you are opening a new browser window and you want to specify the URL of the page to load in the window.

Example:
window.open("chrome://bookmarks/content/bookmarks.xul", "bmarks", "chrome,width=600,height=300");

There are several ways to view a XUL file. You could type the URL of the XUL file into the browser's URL field. It won't open in a new window in this case, but it will be visible in the content area and will be functional.

You can refer to the find files dialog with either a chrome or file URL. The chrome URL would be better but requires us to create a manifest file and install the package properly. This requires extra work which we'll save for later. For now, we could use a file type of URL.

Instead of a file URL, we could use a variant which has its root directory in the Mozilla directory. This is the resource URL. Thus, we could refer to the find files dialog with the following resource URL:

You can use the command-line parameter '-chrome' to specify the XUL file to open when Mozilla starts. If this is not specified, the default window open will open. (Usually the browser window.) For example, we could open the find files dialog with:

If you run this command from a command-line (assuming you have one on your platform), the find files dialog will open by default instead of the Mozilla browser window. Of course, since we haven't put anything in the window, nothing will appear to have happened.

To see the effect though, the following will open the bookmarks window:

(Next) In the next section, we will add some buttons to the window.