| /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ |
| /* ***** BEGIN LICENSE BLOCK ***** |
| * Version: MPL 1.1/GPL 2.0/LGPL 2.1 |
| * |
| * The contents of this file are subject to the Mozilla Public License Version |
| * 1.1 (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * http://www.mozilla.org/MPL/ |
| * |
| * Software distributed under the License is distributed on an "AS IS" basis, |
| * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License |
| * for the specific language governing rights and limitations under the |
| * License. |
| * |
| * The Original Code is mozilla.org code. |
| * |
| * The Initial Developer of the Original Code is Neil Deakin. |
| * Portions created by the Initial Developer are Copyright (C) 2005 |
| * the Initial Developer. All Rights Reserved. |
| * |
| * Contributor(s): |
| * Laurent Jouanneau <laurent.jouanneau@disruptive-innovations.com> |
| * |
| * Alternatively, the contents of this file may be used under the terms of |
| * either of the GNU General Public License Version 2 or later (the "GPL"), |
| * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), |
| * in which case the provisions of the GPL or the LGPL are applicable instead |
| * of those above. If you wish to allow use of your version of this file only |
| * under the terms of either the GPL or the LGPL, and not to allow others to |
| * use your version of this file under the terms of the MPL, indicate your |
| * decision by deleting the provisions above and replace them with the notice |
| * and other provisions required by the GPL or the LGPL. If you do not delete |
| * the provisions above, a recipient may use your version of this file under |
| * the terms of any one of the MPL, the GPL or the LGPL. |
| * |
| * ***** END LICENSE BLOCK ***** */ |
| |
| #include "domstubs.idl" |
| #include "nsISupports.idl" |
| |
| interface nsIAtom; |
| interface nsIArray; |
| interface nsISimpleEnumerator; |
| interface nsIXULTemplateResult; |
| interface nsIXULTemplateRuleFilter; |
| interface nsIXULTemplateBuilder; |
| |
| /** |
| * 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 getBindingFor and |
| * 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. |
| */ |
| [scriptable, uuid(970f1c36-5d2e-4cbc-a1cf-e3327b50df71)] |
| interface nsIXULTemplateQueryProcessor : nsISupports |
| { |
| /** |
| * 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. |
| * 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. |
| * |
| * @param aDataSources the list of nsIURI objects and/or nsIDOMNode objects |
| * @param aRootNode the root node the builder is attached to |
| * @param aIsTrusted true if the template is in a trusted document |
| * @param aBuilder the template builder |
| * @param aShouldDelayBuilding [out] whether the builder should wait to |
| * build the content or not |
| * @returns a datasource object |
| */ |
| nsISupports getDatasource(in nsIArray aDataSources, |
| in nsIDOMNode aRootNode, |
| in boolean aIsTrusted, |
| in nsIXULTemplateBuilder aBuilder, |
| out boolean aShouldDelayBuilding); |
| |
| /** |
| * 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. |
| * |
| * @param aDatasource datasource for the data |
| * @param aBuilder the template builder |
| * @param aRootNode the root node the builder is attached to |
| * |
| * @throws NS_ERROR_INVALID_ARG if the datasource is not supported or |
| * NS_ERROR_UNEXPECTED if generateResults has already been called. |
| */ |
| void initializeForBuilding(in nsISupports aDatasource, |
| in nsIXULTemplateBuilder aBuilder, |
| in nsIDOMNode aRootNode); |
| |
| /** |
| * 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(); |
| |
| /** |
| * 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. |
| * |
| * @param aBuilder the template builder |
| * @param aQuery <query> node to compile |
| * @param aRefVariable the reference variable |
| * @param aMemberVariable the member variable |
| * |
| * @returns a compiled query object |
| */ |
| nsISupports compileQuery(in nsIXULTemplateBuilder aBuilder, |
| in nsIDOMNode aQuery, |
| in nsIAtom aRefVariable, |
| in nsIAtom aMemberVariable); |
| |
| /** |
| * 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. |
| * |
| * @param aDatasource datasource for the data |
| * @param aRef context reference value used as a starting point |
| * @param aQuery the compiled query returned from query compilation |
| * |
| * @returns an enumerator of nsIXULTemplateResult objects as the results |
| * |
| * @throws NS_ERROR_INVALID_ARG if aQuery is invalid |
| */ |
| nsISimpleEnumerator generateResults(in nsISupports aDatasource, |
| in nsIXULTemplateResult aRef, |
| in nsISupports aQuery); |
| |
| /** |
| * 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. |
| * |
| * @param aRuleNode rule to add the binding to |
| * @param aVar variable that will be bound |
| * @param aRef variable that holds reference value |
| * @param aExpr expression used to compute the value to assign |
| */ |
| void addBinding(in nsIDOMNode aRuleNode, |
| in nsIAtom aVar, |
| in nsIAtom aRef, |
| in AString aExpr); |
| |
| /** |
| * 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. |
| * |
| * @param aDatasource datasource for the data |
| * @param aRefString the ref attribute string |
| * |
| * @return the translated ref |
| */ |
| nsIXULTemplateResult translateRef(in nsISupports aDatasource, |
| in AString aRefString); |
| |
| /** |
| * 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. |
| * |
| * @param aLeft the left result to compare |
| * @param aRight the right result to compare |
| * @param aVar variable to compare |
| * |
| * @param returns -1 if less, 0 if equal, or 1 if greater |
| */ |
| PRInt32 compareResults(in nsIXULTemplateResult aLeft, |
| in nsIXULTemplateResult aRight, |
| in nsIAtom aVar); |
| }; |