nsITemplateBuilder interface controls the display of elements using a XUL template element and is automatically attached to an element containing a
datasources attribute. A template builder, given an input source of data, a template, and a reference point, generates a list of results from the input, and copies part of the template for each result. Templates may generate content recursively, using the same template, but with the previous iteration's results as the reference point. As an example, for an XML data source the initial reference point would be a specific node in the DOM tree and a template might generate a list of all child nodes. For the next iteration, those children would be used to generate output for their child nodes and so forth.
A template builder is attached to a single DOM node; this node is called the root node and is expected to contain a XUL
template element as a direct child. Different template builders may be specialized in the manner in which they generate and display the resulting content from the template.
The structure of a template is as follows:
<rootnode datasources="" ref=""> <template> <queryset> <query></query> <rule> <conditions>...</conditions> <bindings>...</bindings> <action>...</action> </rule> </queryset> </template> </rootnode>
datasources attribute on the root node is used to identify the source of data to be used. The
ref attribute is used to specify the reference point for the query.
<queryset> element contains a single query and one or more
<rule> elements. There may be more than one
<queryset> if multiple queries are desired, and this element is optional if only one query is needed -- in that case the
<rule>s are allowed to be children of the
The contents of the query are processed by a separate component called a query processor. This query processor is expected to use this query to generate results when asked by the template builder. The template builder then generates output for each result based on the
This allows the query processor to be specific to a particular kind of input data or query syntax, while the template builder remains independent of the kind of data being used. Due to this, the query processor will be supplied with the
datasource and query which the template builder handles in an opaque way, while the query processor handles these more specifically.
Results implement the
nsIXULTemplateResult interface and may be identified by an id which must be unique within a given set of query results.
Each query may be accompanied by one or more
<rule> elements. These rules are evaluated by the template builder for each result produced by the query. A rule consists of conditions that cause a rule to be either accepted or rejected. The condition syntax allows for common conditional handling; additional filtering may be applied by adding a custom filter to a rule with the builder's
If a result passes a rule's conditions, this is considered a match, and the content within the rule's
<action> body is inserted as a sibling of the
<template>, assuming the template builder creates real DOM content. Only one rule will match a result. For a tree builder, for example, the content within the action body is used to create the tree rows instead. A matching result must have its
ruleMatched() method called. When a result no longer matches, the result's
hasBeenRemoved() method must be called.
Optionally, the rule may have a
<bindings> section which may be used to define additional variables to be used within an action body. Each of these declared bindings must be supplied to the query processor via its
addBinding() method. The bindings are evaluated after a rule has matched.
Templates may generate content recursively, using the previous iteration's results as reference point to invoke the same queries. Since the reference point is different, different output will typically be generated. The reference point
nsIXULTemplateResult object for the first iteration is determined by calling the query processor's
translateRef() method using the value of the root node's
ref attribute. This object may be retrieved later via the builder's
For convenience, each reference point as well as all results implement the
nsIXULTemplateResult interface, allowing the result objects from each iteration to be used directly as the reference points for the next iteration.
When using multiple queries, each may generate results with the same id. More than one of these results may match one of the rules in their respective queries, however only the result for the earliest matching query in the template becomes the active match and generates output. The
resultBindingChanged methods may be called by the query processor to indicate that the set of valid results has changed, such that a different query may match. If a different match would become active, the content for the existing match is removed and the content for the new match is generated. A query processor is not required to provide any support for updating results after they have been generated.
See the Template Guide for more information about templates.
| || ||Readonly: The root node in the DOM to which this builder is attached.|
| || || |
The opaque datasource object that is used for the template. This object is created by the
For an RDF datasource, this will be the same as the database. For XML this will be the
| || ||Readonly: The composite datasource that the template builder observes and uses to create content. This is used only for RDF queries and is maintained for backwards compatibility. It will be the same object as the datasource property. For non-RDF queries, it will always be null.|
| || ||Readonly: The virtual result representing the starting reference point, determined by calling the query processor's translateRef method with the root node's ref attribute as an argument.|
| || ||[noscript] Readonly: The query processor used to generate results.|
Force the template builder to rebuild its content. All existing content will be removed first. The query processor's
done() method will be invoked during cleanup, followed by its
initializeForBuilding() method when the content is to be regenerated.
Reloads any RDF datasources that support
Informs the template builder that a new result is available. The builder will add this result to the set of results. The query node that the new result applies to must be specified using the
aQueryNode parameter. The builder will apply the rules associated with the query to the new result, unless a result with the same id from an earlier query supersedes it, and the result's
ruleMatched() method will be called if it matches.
void addResult( in nsIXULTemplateResult aResult, in nsIDOMNode aQueryNode );
Informs the template builder that a result no longer applies. The builder will call the remove content generated for the result, if any. If a different query would then match instead, it will become the active match. This method will have no effect if the result isn't known to the builder.
void removeResult( in nsIXULTemplateResult aResult );
Inform the template builder that one result should be replaced with another. Both the old result (
aOldResult) and the new result (
aNewResult) must have the same id. The query node that the new result applies to must be specified using the
aQueryNode parameter. This method is expected to have the same effect as calling both
removeResult for the old result and
addResult for the new result.
void replaceResult( in nsIXULTemplateResult aOldResult, in nsIXULTemplateResult aNewResult, in nsIDOMNode aQueryNode );
NS_ERROR_NULL_POINTERif either argument is
NS_ERROR_INVALID_ARGif the ids don't match
Informs the template builder that one or more of the optional bindings for a result has changed. In this case, the rules are not reapplied as it is expected that the same rule will still apply. The builder will resynchronize any variables that are referenced in the action body.
void resultBindingChanged( in nsIXULTemplateResult aResult );
Returns the result for a given ID. Only one such result is returned and is always the result with that ID associated with the active match. This method will return
null is there is no result for the ID.
nsIXULTemplateResult getResultForId( in AString aId );
The result for the given ID.
Retrieves the result corresponding to a generated element, or
null is there isn't one.
nsIXULTemplateResult getResultForContent( in nsIDOMElement aElement );
The result for the specified element.
Determines whether or not the node has content generated for it. This method is intended to be called only by the RDF query processor. If
aTag is set, the content must have a tag name that matches
aTag may be ignored for builders that don't generate real DOM content.
boolean hasGeneratedContent( in nsIRDFResource aNode, in nsIAtom aTag );
true if the node has content generated for it; otherwise returns false.
Adds a rule filter for a given rule, which may be used for specialized rule filtering. Any existing filter on the rule is removed. The default conditions specified inside the
<rule> tag are applied before the rule filter is applied, meaning that the filter may be used to further filter out results but not reaccept results that have already been rejected.
void addRuleFilter( in nsIDOMNode aRule, in nsIXULTemplateRuleFilter aFilter );
Called to initialize a XUL content builder on a particular root element. This element presumably has a
datasources attribute, which the builder will parse to set up the template builder's data sources.
[noscript] void init( in nsIContent aElement );
Invoked lazily by a XUL element that needs its child content built.
[noscript] void createContents( in nsIContent aElement, in boolean aForceCreation );
true, the contents of the element are generated even if the element is closed; this behavior is used with menus. If
false, the element's contents are only generated if it's open.
Adds a listener to this template builder. The template builder holds a strong reference to the listener.
void addListener( in nsIXULBuilderListener aListener );
nsIXULBuilderListenerobject representing the listener to add to the template builder.
Removes a listener from this template builder.
void removeListener( in nsIXULBuilderListener aListener );
nsIXULBuilderListenerobject representing the listener to remove from the template builder.