nsIXULTemplateBuilder
| IID: | A583B676-5B02-4F9C-A0C9-CB850CB99818 |
| Inherits From: | nsISupports |
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
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
If a result passes a rule's conditions, this is considered a match, and the
content within the rule's
Optionally, the rule may have a
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.
This interface is implemented by the following components:
Properties
readonly nsIRDFCompositeDataSource 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.
readonly nsIXULTemplateQueryProcessor queryProcessor
The query processor used to generate results.
readonly nsIDOMElement root
The root node in the DOM to which this builder is attached.
readonly nsIXULTemplateResult 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.
Methods
void addListener ( nsIXULBuilderListener listener )
void addResult ( nsIXULTemplateResult result , nsIDOMNode queryNode )
void addRuleFilter ( nsIDOMNode rule , nsIXULTemplateRuleFilter filter )
[noscript] void createContents ( nsIContent element , PRBool forceCreation )
nsIXULTemplateResult getResultForContent ( nsIDOMElement element )
nsIXULTemplateResult getResultForId ( AString id )
PRBool hasGeneratedContent ( nsIRDFResource node , nsIAtom tag )
[noscript] void init ( nsIContent element )
void rebuild ( )
void refresh ( )
void removeListener ( nsIXULBuilderListener listener )
void removeResult ( nsIXULTemplateResult result )
void replaceResult ( nsIXULTemplateResult oldResult , nsIXULTemplateResult newResult , nsIDOMNode queryNode )
void resultBindingChanged ( nsIXULTemplateResult result )
void addListener ( nsIXULBuilderListener listener )
Add a listener to this template builder. The template builder holds a strong reference to the listener.
- Arguments:
- listener
void addResult ( nsIXULTemplateResult result , nsIDOMNode queryNode )
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 queryNode 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.
- Arguments:
- result: the result to add
- queryNode: the query that the result applies to
void addRuleFilter ( nsIDOMNode rule , nsIXULTemplateRuleFilter filter )
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
- Arguments:
- rule: the rule to apply the filter to
- filter: the filter to add
void createContents ( nsIContent element , PRBool forceCreation )
Invoked lazily by a XUL element that needs its child content built. If forceCreation is true, then the contents of a 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.
- Arguments:
- element
- forceCreation
nsIXULTemplateResult getResultForContent ( nsIDOMElement element )
Retrieve the result corresponding to a generated element, or null is there isn't one.
- Arguments:
- element
nsIXULTemplateResult getResultForId ( AString id )
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.
- Arguments:
- id: the id to return the result for
PRBool hasGeneratedContent ( nsIRDFResource node , nsIAtom tag )
Returns true if the node has content generated for it. This method is intended to be called only by the RDF query processor. If tag is set, the content must have a tag name that matches tag. tag may be ignored for builders that don't generate real DOM content.
- Arguments:
- node: node to check
- tag: tag that must match
void init ( nsIContent element )
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.
- Arguments:
- element
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.
void removeListener ( nsIXULBuilderListener listener )
Remove a listener from this template builder.
- Arguments:
- listener
void removeResult ( nsIXULTemplateResult result )
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.
- Arguments:
- result: the result to remove
void replaceResult ( nsIXULTemplateResult oldResult , nsIXULTemplateResult newResult , nsIDOMNode queryNode )
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 queryNode parameter.
This method is expected to have the same effect as calling both removeResult for the old result and addResult for the new result.
- Arguments:
- oldResult: the old result
- newResult: the new result
- queryNode: the query that the new result applies to
void resultBindingChanged ( nsIXULTemplateResult result )
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.
- Arguments:
- result: the result to change
References
This interface is the type of the following properties:
This interface is passed as an argument to the following methods:
nsIXULBuilderListener.didRebuild, nsIXULBuilderListener.willRebuild, nsIXULTemplateQueryProcessor.compileQuery, nsIXULTemplateQueryProcessor.getDatasource, nsIXULTemplateQueryProcessor.initializeForBuilding
Reference documentation is generated from Mozilla's source.