nsIXULTemplateQueryProcessor

A query processor takes a template query and generates results for it given a datasource and a reference point. There is a one-to-one relationship between a template builder and a query processor. The template builder creates the query processor, and there is no other means to retrieve it.

A template query is the contents inside a <query> element within the template. The actual syntax is opaque to the template builder and defined by a query processor. The query is expected to consist of either text or DOM nodes that, when executed by a call to the generateResults() method, will allow the generation of a list of results.

The template builder will supply two variables, the reference variable and the member variable to further indicate what part of the datasource is to be examined in addition to the query itself. The reference is always a placeholder for the starting point and the member is always a placeholder for the end points (the results).

The reference point is important when generating output recursively, as the query will be the same for each iteration, however, the reference point will differ. For instance, when examining an XML source, an XML query processor might begin at the node referred by the reference variable and end at a list of that node's children. Some queries may not need the reference variable if the syntax or the form of the data implies the value. For instance, a datasource that holds a table that can only produce one set of results.

The reference variable may be specified in a template by setting the "container" attribute on the <template> element to the variable to use. The member variable may be specified in a similar way using the "member" attribute, or it may be specified in the first <action> body in the template as the value of a uri attribute on an element. A breadth-first search of the first action is performed to find this element. If unspecified, the default value of the reference variable is ?uri.

For example, a query might have the following syntax: (?id, ?name, ?url) from Bookmarks where parentfolder = ?start

This query might generate a result for each bookmark within a given folder. The variable ?start would be the reference variable, while the variable ?id would be the member variable, since it is the unique value that identifies a result. Each result will have the four variables referred to defined for it and the values may be retrieved using the result's nsIXULTemplateResult.getBindingFor() and nsIXULTemplateResult.getBindingObjectFor() methods.

The template builder must call initializeForBuilding() before the other methods, except for translateRef(). The builder will then call compileQuery() for each query in the template to compile the queries. When results need to be generated, the builder will call generateResults(). The initializeForBuilding(), compileQuery() and addBinding() methods may not be called after generateResults() has been called until the builder indicates that the generated output is being removed by calling the done() method.

Currently, the datasource supplied to the methods will always be an nsIRDFDataSource or a DOM node, and will always be the same one in between calls to initializeForBuilding() and done().

Method overview

Methods

addBinding()

Add a variable binding for a particular rule. A binding allows an additional variable to be set for a result, outside of those defined within the query. These bindings are always optional, in that they will never affect the results generated. This function will never be called after generateResults(). Any bindings that were added should be applied to each result when the result's ruleMatched method is called, since the bindings are different for each rule. The reference aRef may be used to determine the reference when calculating the value for the binding, for example when a value should depend on the value of another variable. The syntax of the expression aExpr is defined by the query processor. If the syntax is invalid, the binding should be ignored. Only fatal errors should be thrown, or NS_ERROR_UNEXPECTED if generateResults() has already been called.

As an example, if the reference aRef is the variable ?count which holds the value 5, and the expression aExpr is the string '+2', the value of the variable aVar would be 7, assuming the query processor considers the syntax '+2' to mean add two to the reference.

void addBinding(
  in nsIDOMNode aRuleNode,
  in nsIAtom aVar,
  in nsIAtom aRef,
  in AString aExpr
);

Parameters

aRuleNode

Rule to add the binding to.

aVar

Variable that will be bound.

aRef

Variable that holds reference value.

aExpr

Expression used to compute the value to assign.

Exceptions thrown

NS_ERROR_UNEXPECTED

If generateResults() has already been called.

compareResults()

Compare two results to determine their order, used when sorting results. This method should return -1 when the left result is less than the right, 0 if both are equivalent, and 1 if the left is greater than the right. The comparison should only consider the values for the specified variable. If the comparison variable is null, the results may be sorted in a natural order, for instance, based on the order the data in stored in the datasource. This method must only be called with results that were created by this query processor.

PRInt32 compareResults(
  in nsIXULTemplateResult aLeft,
  in nsIXULTemplateResult aRight,
  in nsIAtom aVar,
  in unsigned long aSortHints
);

Parameters

aLeft

The left result to compare.

aRight

The right result to compare.

aVar

Variable to compare.

aSortHints

The sort hints are the flags in nsIXULSortService.

Return value

• -1 if aLeft < aRight
• 0 if aLeft == aRight
• 1 if aLeft > aRight

compileQuery()

Compile a query from a node. The result of this function will later be passed to generateResults() for result generation. If null is returned, the query will be ignored. The template builder will call this method once for each query within the template, before any results can be generated using generateResults(), but after initializeForBuilding() has been called. This method should not be called again for the same query unless the template is rebuilt. The reference variable may be used by the query processor as a placeholder for the reference point, or starting point in the query. The member variable is determined from the member attribute on the template, or from the URI in the first action's rule if that attribute is not present. A rule processor may use the member variable as a hint to indicate what variable is expected to contain the results.

nsISupports compileQuery(
  in nsIXULTemplateBuilder aBuilder,
  in nsIDOMNode aQuery,
  in nsIAtom aRefVariable,
  in nsIAtom aMemberVariable
);

Parameters

aBuilder

The template builder.

aQuery

<query> node to compile.

aRefVariable

The reference variable.

aMemberVariable

The member variable.

Return value

A compiled query object.

done()

Called when the template builder is being destroyed so that the query processor can clean up any state. The query processor should remove as much state as possible, such as results or references to the builder. This method will also be called when the template is going to be rebuilt.

void done();

Parameters

None.

generateResults()

Generate the results of a query and return them in an enumerator. The enumerator must contain nsIXULTemplateResult objects. If there are no results, an empty enumerator must be returned. The datasource will be the same as the one passed to the earlier initializeForBuilding() method. The context reference aRef is a reference point used when calculating results. The value of aQuery must be the result of a previous call to compileQuery() from this query processor. This method may be called multiple times, typically with different values for aRef.

nsISimpleEnumerator generateResults(
  in nsISupports aDatasource,
  in nsIXULTemplateResult aRef,
  in nsISupports aQuery
);

Parameters

aDatasource

Datasource for the data.

aRef

Context reference value used as a starting point.

aQuery

The compiled query returned from query compilation.

Return value

An enumerator of nsIXULTemplateResult objects as the results.

Exceptions thrown

NS_ERROR_INVALID_ARG

If aQuery is invalid.

getDatasource()

Retrieve the datasource to use for the query processor. The list of datasources in a template is specified using the datasources attribute as a space separated list of URIs. This list is processed by the builder and supplied to the query processor in the aDataSources array as a list of nsIURI objects or nsIDOMNode objects. This method may return an object corresponding to these URIs and the builder will supply this object to other query processor methods. For example, for an XML source, the datasource might be an nsIDOMNode. All of these URIs are checked by the builder so it is safe to use them, however note that a URI that redirects may still needs to be checked to ensure that the document containing aRootNode may access it. This is the responsibility of the query processor if it needs to load the content of the URI. If the query processor needs to load the datasource asynchronously, it may set the aShouldDelayBuilding returned parameter to true to delay building the template content, and call the builder's Rebuild method when the data is available.

nsISupports getDatasource(
  in nsIArray aDataSources,
  in nsIDOMNode aRootNode,
  in boolean aIsTrusted,
  in nsIXULTemplateBuilder aBuilder,
  out boolean aShouldDelayBuilding
);

Parameters

aDataSources

The list of nsIURI objects and/or nsIDOMNode objects.

aRootNode

The root node the builder is attached to.

aIsTrusted

true if the template is in a trusted document.

aBuilder

The template builder.

aShouldDelayBuilding

Whether the builder should wait to build the content or not.

Return value

A datasource object.

initializeForBuilding()

Initialize for query generation. This will be called before the rules are processed and whenever the template is rebuilt. This method must be called once before any of the other query processor methods except for translateRef().

void initializeForBuilding(
  in nsISupports aDatasource,
  in nsIXULTemplateBuilder aBuilder,
  in nsIDOMNode aRootNode
);

Parameters

aDatasource

Datasource for the data.

aBuilder

The template builder.

aRootNode

The root node the builder is attached to.

Exceptions thrown

NS_ERROR_INVALID_ARG

If the datasource is not supported.

NS_ERROR_UNEXPECTED

If generateResults() has already been called.

translateRef()

Translate a ref attribute string into a result. This is used as the reference point by the template builder when generating the first level of content. For recursive generation, the result from the parent generation phase will be used directly as the reference so a translation is not needed. This allows all levels to be generated using objects that all implement the nsIXULTemplateResult interface.

This method may be called before initializeForBuilding(), so the implementation may use the supplied datasource if it is needed to translate the reference.

nsIXULTemplateResult translateRef(
  in nsISupports aDatasource,
  in AString aRefString
);

Parameters

aDatasource

Datasource for the data.

aRefString

The ref attribute string.

Return value

The translated ref.

See also

• A tutorial on how to implement a custom XUL query processor component can be found here.