Tutorials > " . "XUL Tutorial"; $pagetitle="7.2 - Document Object Model"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

Document Object Model

The Document Object Model (DOM) can be used with XUL elements to get information about them or modify them.

Modifying Elements with the DOM

XUL elements support the DOM properties and methods which will allow you to get information about elements and modify any element. A full discussion of DOM features will not provided here but some examples will be provided.

The id attribute can be used to identify elements. We've added the id attribute to a number of elements in the find file dialog. For example, we could get the state of the Case Sensitive Search check box by using the code below:

var state=document.getElementById('casecheck').checked;

The value casecheck corresponds to the id of the case sensitive check box. Once we have an indication of whether it is checked or not, we can use the state to perform the search. We could do something similar for the other check box, or any other element that has an id. We'll need to get the text in the input field for example.

It doesn't make sense to have the progress bar and the dummy tree data displayed when the find files dialog is first displayed. These were added so that we could see them. Let's take them out now and have them displayed when the Find button is pressed. First, we need to make them initially invisible. The CSS property display is used to control whether an element is visible or not.

We'll change the progress meter so that is initially hidden. Also, we will add an id attribute so that we can refer to it in a script to show and hide it. While we're at it, let's also hide the splitter and results tree as we only need to show them after a search is performed.

<tree id="results" style="display: none;" flex="1">
<splitter id="splitbar" resizeafter="grow" style="display:none;"/>


  <progressmeter id="progmeter" value="50%"
    style="margin: 4px; display: none;"/>

We've added a CSS style property display and set its value to none. This causes the element to be hidden when it first appears. By default, the display property defaults to a value which tells the element to be displayed. The exact value is different for each element, because each element has a different way of being displayed. Look in the file xul.css in the archive toolkit.jar in the Mozilla chrome directory for details about the default styles for each XUL element and the file html.css in the Mozilla res directory for details about the default styles for each HTML element.

First, let's add a function that is called when the Find button is pressed. We'll put scripts in a separate file findfile.js. In the last section, we added the script element in the XUL file. If you haven't done this, do that now, as shown below. An oncommand handler will also be added to the Find button.

<script src="findfile.js"/>
<button id="find-button" label="Find" default="true"

Now, create another file called findfile.js in the same directory as findfile.xul. We'll add the doFind() function is this file. The script tag does allow code to be contained directly inside of it. However, for various reasons, including better performance, you should always put scripts in separate files, except for short fragments which can be put directly in the event handler.

function doFind()
  var meter=document.getElementById('progmeter');
  meter.setAttribute("style","margin: 4ex; display: -moz-xul-box;");

This function first gets a reference to the progress meter using its id, progmeter. The second line of the function body sets the style attribute of the progress meter to have a display of '-moz-xul-box', which is the value for XUL boxes and elements based on them. Note that we've also had to add the margin so that it doesn't get removed.

Finally, let's have an alert box pop up that displays what will be searched for. Of course, we wouldn't want this in the final version but we'll add it to reassure us that something would happen.

function doFind()
  var meter=document.getElementById('progmeter');
  meter.setAttribute("style","display: inline;");
  var searchtext=document.getElementById('find-text').value;
  alert("Searching for \""+searchtext+"\"");

Now, with that alert box in there, we know what should happen when we click the Find button. We could add additional code to get the selections from the drop-down boxes too.

Creating New Elements

You can create new elements using the createElement function of the document. It takes one argument, the tag name of the element to create. You can then set attributes of the element using the setAttribute function and append it to the XUL document using the appendChild function. For example, the following will add a button to a XUL window:

Example 7.2.1: Source View
function addButton()
  var aBox = document.getElementById("aBox");

  var button = document.createElement("button");
  button.setAttribute("label","A Button");

<box id="aBox">
  <button label="Add" oncommand="addButton();"/>

This script first gets a reference to the box, which is what we will add a new button to. The createElement function creates a new button. We assign a label 'A Button' to the button using the setAttribute function. The appendChild function of the box is called to add the button to it. Finally, we call the sizeToContent method of the window, which causes the window to resize to fit the newly added button.

For a more complete list of functions available for XUL elements, see the element reference.

(Next) Next, we'll find out how to add keyboard shortcuts.

Examples: 7.2.1

Find files example so far: Source View