[Table of Contents] [Previous: Popup Content] [Next: Persistence and Sharing]

Feature Owner: Dave Hyatt

[XUL Fragments are in flux and there are numerous bugs which make them dangerous to use right now. Dangerous elements include boxes (and therefore anything that derives from box, like toolbar, tab, and toolbox), tables (and trees), and menus.]

It will commonly be the case that a piece of UI has been designed using XUL, and the UI designer wants to share this UI in many different types of windows, without having to cut and paste the UI into the windows each time. The designer would like to reference the UI description from the various files describing the windows and only have to worry about editing one file when the UI description changes.

XUL fragments address this problem. A XUL fragment file describes a XUL subtree that can be included in other XUL documents (that can themselves be fragments). A fragment is included by placing the include attribute on a XUL tag. The value of this attribute is the URL of the fragment that should be included as a subtree of the XUL tag. This URL can point to a fragment in the same document (using #), or it can point to a fragment in an external XUL fragment file.

XUL fragments can be used on any nodes in the XUL or HTML namespace.

<toolbar include="chrome://global/content/mainToolbar.xul"/>

A XUL fragment file has a fragment tag as its root. Namespaces must be set up again in the fragment file (since you have no idea what namespaces might have been defined in the place where you do the include). The contents of a fragment are the children that will be placed underneath any node that references the fragment.

<fragment xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"> <titledbutton value="Back"/> <titledbutton value="Forward"/> ... </fragment>

A node that specifies the inclusion of a fragment may also overlay additional children of its own. [At the moment these children can only be placed in front of the children in the fragment.]

<toolbar include="chrome://global/content/mainToolbar.xul"> <titledbutton value="I come first! Bwa-ha-ha!"/> </toolbar>

[Not yet implemented] Fragments can also be declared directly in a document and used more than once within the same document.

<fragment xmlns="(etc.etc.)" id="format"> [contents of menu] </fragment> ... <menubar> ... <menu name="Paragraph Format" include="#format"/> ... </menubar> ... <popup id="formatContextMenu"> <menu include="#format> </popup>

If attributes are set on a fragment node, they will be placed on the node that is including the fragment, e.g., the name of the format menu in the example above could have been placed directly on the fragment.