Creating Applications with Mozilla
PrevChapter 3. XUL Elements and FeaturesNext

3.8. Content Panels

Content widgets allow you to load content into the UI for display. These widgets -- browser and editor -- provide a window into which you can load. In the standard browser, these documents can be written in HTML, XML, text, or other supported content types.

3.8.1. Browser and IFrame

The <browser> element displays online content and provides full browsing capabilities to your application, such as navigation features or maintaining a history. 

<browser id="content" type="content-primary" src="ch3.html"/>

The behind-the-scenes implementation for browser gives you access to certain interfaces that can be used in your scripts. These interfaces include:

Without going into detail, these interfaces all provide sophisticated functionality for web browsing and other browser-like services, and are made available to JavaScript in the application interface. You can explore them further by looking at the interfaces themselves -- at the IDL files of the same name in the Mozilla source tree.

Tip

If you would like to learn more about these available interfaces, the best place to look is the source code. The two recommended files to start with are browser.xml, which shows how the interfaces are exposed, and navigator.js, which shows how they are used. Both files can be browsed on the online Mozilla Cross Reference, at http://lxr.mozilla.org.

An alternative to <browser> is the <iframe>. It's similar to the browser widget in appearance, but better suited for simple or ephemeral content. It's often used as a preview window in HTML/XML editors and other WYSIWYG applications. iframes can also be good for dynamic document editing, as in the following example, in which the frame provides access to the document loaded as content. This can then be written to: 

<iframe id="simple-content" />

The document's open( ), write( ), and close( ) methods, which are standard in the JavaScript engine, are used to write to the document: 

var doc = window.frames[1].document;
doc.open( );
doc.write("<html><body>Come fly with me ...</body></html>");
doc.close( );

In this code snippet, you get a handle to the particular frame that you want by using window.frames, which returns an array of all frames contained in a document. There can be multiple frames in a document, which are indexed. Here it is assumed that we get the second (1 in a zero-based array) frame. The doc variable has a reference to the content area and uses the methods available on the document object to write content -- in this case, HTML.

Ideas for using content panels include:[1]

3.8.2. Editor

The <editor> element loads editable content and can handle text or HTML editing. A good example of its usage is in Mozilla Composer, the HTML editor that comes bundled with Mozilla.

The <editor> tag creates an instance of the nsEditorBoxObject interface when it's initialized. From that point, you can use JavaScript (via the element.editorShell property) to get to the editorShell methods for carrying out editing on the loaded document.

The editor is also used in the various XUL and HTML text widgets in Mozilla, such as textbox and HTML forms, and for composing HTML messages in Mail and News. The text widgets differ from the full-blown editor because they act on a subtree of the document. Also, text widgets have limited text-editing services.

Uses for the editor, both practical and speculative, include:

Keeping Track in Multiframe Documents

The content contained in a <browser>, <iframe>, and <editor> is treated as a separate document. At times, you may want to access that specific content, so how do you keep track of different content?

To return all the content frames in a document, you can use:

var contentAreas = content.frames;

There are two ways to access specific content in a script: through the index of the frame within the containing document or by using the id attribute.

By index, starting at 0:

var content = window.frames[ 1 ];

By id:

var content = window.frames[ contentId ];

This code returns the second frame.

To flag one as default, use the type attribute and give it a value. 

<iframe id="print-panel" type="content-primary" src="about:blank" flex="1""/>

This code allows quick access to the default via the window.content property: 

window.content.print( );

Notes

[1]

Note that these examples are distinct from embedding the Gecko layout engine in your generic application. A separate toolkit and a set of APIs is available for doing this.

PrevHomeNext
Widget InteractionUpThe Box Model