nsIXULTemplateBuilder
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 datasource 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:
...
...
...
The 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. Currently, the datasource will either be an
nsIRDFDataSource or a DOM node. In the future, other datasource types may
be used.
The element contains a single query and one or more
elements. There may be more than one if multiple queries are
desired, and this element is optional if only one query is needed -- in
that case the and s are allowed to be children of the
node
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 elements.
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 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 addRuleFilter method.
If a result passes a rule's conditions, this is considered a match, and the
content within the rule's body is inserted as a sibling of the
, 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 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 rootResult property.
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
addResult, removeResult, replaceResult and 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 http://wiki.mozilla.org/XUL:Templates_Plan for details about templates.
## Methods ##
### rebuild() ###
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.
### refresh() ###
Reload any of our RDF datasources that support nsIRDFRemoteDatasource.
@note This is a temporary hack so that remote-XUL authors can
reload remote datasources. When RDF becomes remote-scriptable,
this will no longer be necessary.
### addResult(aResult, aQueryNode) ###
Inform 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.
@throws NS_ERROR_NULL_POINTER if aResult or aQueryNode are null
#### Parameters ####
| aResult |
the result to add
|
| aQueryNode |
the query that the result applies to
|
### removeResult(aResult) ###
Inform 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.
@throws NS_ERROR_NULL_POINTER if aResult is null
#### Parameters ####
| aResult |
the result to remove
|
### replaceResult(aOldResult, aNewResult, aQueryNode) ###
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.
@throws NS_ERROR_NULL_POINTER if either argument is null, or
NS_ERROR_INVALID_ARG if the ids don't match
#### Parameters ####
| aOldResult |
the old result
|
| aNewResult |
the new result
|
| aQueryNode |
the query that the new result applies to
|
### resultBindingChanged(aResult) ###
Inform 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.
@throws NS_ERROR_NULL_POINTER if aResult is null
#### Parameters ####
| aResult |
the result to change
|
### getResultForId(aId) ###
Return 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.
#### Parameters ####
| aId |
the id to return the result for
|
### getResultForContent(aElement) ###
Retrieve the result corresponding to a generated element, or null is
there isn't one.
#### Parameters ####
| aContent |
element to result the result of
|
### hasGeneratedContent(aNode, aTag) ###
Returns true if 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. aTag may be ignored
for builders that don't generate real DOM content.
#### Parameters ####
| aNode |
node to check
|
| aTag |
tag that must match
|
### addRuleFilter(aRule, aFilter) ###
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 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.
#### Parameters ####
| aRule |
the rule to apply the filter to
|
| aFilter |
the filter to add
|
### init(aElement) ###
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 datasources.
### createContents(aElement, aForceCreation) ###
Invoked lazily by a XUL element that needs its child content built.
If aForceCreation is true, then the contents of an element will be
generated even if it is closed. If false, the element will only
generate its contents if it is open. This behaviour is used with menus.
### addListener(aListener) ###
Add a listener to this template builder. The template builder
holds a strong reference to the listener.
### removeListener(aListener) ###
Remove a listener from this template builder.
## Attributes ##
### root ###
The root node in the DOM to which this builder is attached.
### datasource ###
The opaque datasource object that is used for the template. This object
is created by the getDataSource method of the query processor. May be
null if the datasource has not been loaded yet. Set this attribute to
use a different datasource and rebuild the template.
For an RDF datasource, this will be the same as the database. For XML
this will be the nsIDOMNode for the datasource document or node for
an inline reference (such as #name). Other query processors may use
other types for the datasource.
### database ###
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.
### rootResult ###
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.
### queryProcessor ###
The query processor used to generate results.