Content Panels

In this section, we'll look at how to add panels that can display HTML pages or other XUL files.

Adding Child Panels

There may be times when you want to have part of a document loaded from a different page. Sometimes, you will want to change part of the window. A good example is a step-by-step wizard that guides you through a number of screens, asking a set of questions. Each time the user clicks the Next button, the next screen of the wizard is displayed.

You could create a wizard interface by opening a different window for each screen. There are three problems with this approach. First, each window could appear in a different location (although there are ways around this). Second, the elements such the Back and Next buttons are the same throughout the interface. It would be much better if just the content area of the wizard changed. Third, it would be difficult to co-ordinate scripts when running in different windows.

Note that XUL does have a wizard element which may be used to create wizard interfaces. This will be described in a later section.

Another approach is to use the iframe element, which works much like the HTML element of the same name. It creates a separate document within the window. It has the advantage that it can be placed anywhere and the contents can be loaded from a different file. Set the URL to appear in the frame with the src attribute. This URL may point to any kind of file, although it will usually point to an HTML file or another XUL file. You can use a script to change the contents of the iframe without affecting the main window.

In the Mozilla browser window, the area where the web page is displayed is created by using an iframe. When the user enters a URL or clicks on a link in a document, the source of the frame is changed.

The following is an example of using an iframe:

<toolbox>
  <toolbar id="nav-toolbar">
    <toolbarbutton label="Back"/>
    <toolbarbutton label="Forward"/>
    <textbox id="urlfield"/>
  </toolbar>
</toolbox>

<iframe id="content-body" src="http://www.mozilla.org" flex="1"/>

The example here has created a very simple interface for a web browser. A box has been created containing two elements: a toolbox and an iframe. A Back button, a Forward button and a field for typing is URLs has been added to the only toolbar. The web pages would appear inside the iframe. In this case, the file welcome.html would appear by default.

This example isn't functionally complete. Next, we would want to add script which changes the src attribute at the desired time, for example when the user presses the Enter key.

Browsers

There is a second type of content panel, using the browser tag. You would use this when you want to create a frame that displays content like a browser. Actually, the iframe can do this too, but the browser has a variety of additional features. For example, the browser maintains a page history for use with Back and Forward buttons. The browser can also load pages with referers and other flags. Essentially, the browser tag should be used when you want to create a browser like interface, but the iframe may be used when you just need a simple panel.

A similar element, tabbrowser, provides the functionality of browser but also provides a tab bar for switching between multiple pages. This is the widget used by the Mozilla browser for its tabbed browsing interface. The tabbrowser element is actually implemened as a tabbox containing a set of browser elements. Both types of browser offer similar control over pages that are displayed.

Here is an example browser:

<browser src="http://www.mozilla.org" flex="1"/>

As with the iframe, you can specify the url in a browser using the src attribute. For a tabbrowser, you cannot set the url directly like this, as it doesn't display just one url. Instead, you must use a script and call the loadURI function.

There are three classes of browser, depending on the kind of content that you want to display inside. The type may be specified using the type. The first type is the default and is used if you don't specify a type. In this case, the content loaded inside the browser is treated as if it was part of the same application and has access to the outer window. That means that when a script loaded inside the browser tries to get the topmost window, it will get the outer XUL window.

This would be suitable for a child XUL panel that is part of your application, but this isn't what you want for a browser that loads a web page. Instead, you would want to restrict the web page to only getting access to the web page content. You might note that a Mozilla browser window has XUL content for the toolbars and statusbar and so forth with a tabbrowser forming the main area. This inner area displays a web page, but the web page cannot access the XUL around it. This is because it uses the second type of browser, specified by setting the type attribute to the value content. This prevents the content from traversing up to the XUL window. An example:

<browser src="http://www.mozilla.org" type="content" flex="1"/>

It is important that you set the type attribute correctly if you are going to be displaying remote web sites inside the browser element. The tabbrowser sets the content type automatically on all tabbed browsers that it creates. So you don't have to set this explicitly for tabbed browsers.

The third type is used to indicate the primary content inside the window. The tabbed browser sets this automatically to whichever browser is currently visible. But you can set it on a browser if you have more than one in a window, for example if you have a sidebar displaying some content as well. Set the type attribute to content-primary to specify the primary content. This acts just like the content value except that the content inside is accessible using the XUL window's 'content' property. This makes it easy to access the content of the main browser using a script. It is especially convenient when using a tabbed browser, as you will always be able to access the currently visible content in this way.

(Next) Next, we'll look at how to create a splitter.

Examples: 4.5.1 4.5.2