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

An 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"
    orient="horizontal"
    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<!-- Other elements go here --> 
</window>

This window will not do anything since it doesn't contain any UI elements. Those will be added in the next section. In fact, there will not be shown any window at all. If you want to force the window to become visible you can add the width and height attribute to the window tag. Here is a line by line breakdown of the code above:

1. <?xml version="1.0"?>
   This line simply declares that this is an XML file. You would normally add this line as is at the top of each xul 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 this case, we import the styles found in the global part of a skin package. We didn't specify a specific file so Mozilla will determine which files in the directory to use. In this 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 within 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 HTML tag which surrounds an entire HTML document, except that a user interface window is described instead of a document. Several attributes can be placed in the window tag -- in this case there are four. 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. orient="horizontal"
   The orient attribute specifies the arrangement of the items in the window. The value horizontal indicates that items should be placed horizontally across the window. You may also use the value vertical, which means that the items are placed in a column. This is the default value, so you may leave the attribute off entirely if you wish to have vertical orientation.
7. xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
   This line declares the namespace for XUL, which you should put on the window element to indicate that all of its children are XUL. Note that this URL is never actually downloaded. Mozilla will recognize this URL internally.
8. <!-- Other elements go here -->
   Replace this comment block with other elements (the buttons, menus and other user interface components) to appear in the window. We'll add some of these in the next set of sections.
9. </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. You should also be able to double-click the file in your file manager, assuming that XUL files are associated with Mozilla. The XUL window will appear in the browser window as opposed to a new window, but this is often sufficient during the early stages of development.

Note: The local XUL document can be opened in the browser as mentioned above only if |dom.allow_XUL_XBL_for_file| preference in "about:config" has been set to |true| . If it does not exist, then it needs to be created and set to |true|.

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 chrome document to open. This will open the window without the toolbars and menus and so forth that a normal browser window has. The syntax is described below:

window.open(url,windowname,flags);

where the flags contains the flag "chrome" as in this example

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

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

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 will open. (Usually the browser window.) For example, we could open the find files dialog with either of the following:

mozilla -chrome chrome://findfile/content/findfile.xul 
mozilla -chrome resource:/chrome/findfile/content/findfile.xul

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, because we haven't put any UI elements in the window, you won't see a window appear. We'll add some elements in the next section.

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

mozilla -chrome chrome://communicator/content/bookmarks/bookmarksManager.xul

If you are using Firefox, try below.

firefox -chrome chrome://browser/content/places/places.xul

The '-chrome' argument doesn't give the file any additional privileges. Instead, it causes the specified file to open as a top-level window without any browser chrome, such as the address field or menu. Only chrome URLs have additional privileges.

Troubleshooting

• If the XUL window fails to show up on the desktop but has an icon on the desktop tool bar, check the xml-stylesheet declaration. Make sure that you have included the stylesheet correctly:

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

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