1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/xul/templates/public/nsIXULTemplateResult.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,116 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIAtom;
1.12 +interface nsIDOMNode;
1.13 +interface nsIRDFResource;
1.14 +
1.15 +/**
1.16 + * A single result generated from a template query. Each result is identified
1.17 + * by an id, which must be unique within the set of results produced from a
1.18 + * query. The result may optionally be identified by an RDF resource.
1.19 + *
1.20 + * Generally, the result and its id will be able to uniquely identify a node
1.21 + * in the source data, such as an RDF or XML node. In other contexts, such as
1.22 + * a database query, a result would represent a particular record.
1.23 + *
1.24 + * A result is expected to only be created by a query processor.
1.25 + *
1.26 + * Each result also contains a set of variable bindings. The value for a
1.27 + * particular variable may be retrieved using the getBindingFor and
1.28 + * getBindingObjectFor methods.
1.29 + */
1.30 +[scriptable, uuid(ebea0230-36fa-41b7-8e31-760806057965)]
1.31 +interface nsIXULTemplateResult : nsISupports
1.32 +{
1.33 + /**
1.34 + * True if the result represents a container.
1.35 + */
1.36 + readonly attribute boolean isContainer;
1.37 +
1.38 + /**
1.39 + * True if the result represents an empty container.
1.40 + */
1.41 + readonly attribute boolean isEmpty;
1.42 +
1.43 + /**
1.44 + * True if the template builder may use this result as the reference point
1.45 + * for additional recursive processing of the template. The template builder
1.46 + * will reprocess the template using this result as the reference point and
1.47 + * generate output content that is expected to be inserted as children of the
1.48 + * output generated for this result. If false, child content is not
1.49 + * processed. This property identifies only the default handling and may be
1.50 + * overriden by syntax used in the template.
1.51 + */
1.52 + readonly attribute boolean mayProcessChildren;
1.53 +
1.54 + /**
1.55 + * ID of the result. The DOM element created for this result, if any, will
1.56 + * have its id attribute set to this value. The id must be unique for a
1.57 + * query.
1.58 + */
1.59 + readonly attribute AString id;
1.60 +
1.61 + /**
1.62 + * Resource for the result, which may be null. If set, the resource uri
1.63 + * must be the same as the ID property.
1.64 + */
1.65 + readonly attribute nsIRDFResource resource;
1.66 +
1.67 + /**
1.68 + * The type of the object. The predefined value 'separator' may be used
1.69 + * for separators. Other values may be used for application specific
1.70 + * purposes.
1.71 + */
1.72 + readonly attribute AString type;
1.73 +
1.74 + /**
1.75 + * Get the string representation of the value of a variable for this
1.76 + * result. This string will be used in the action body from a template as
1.77 + * the replacement text. For instance, if the text ?name appears in an
1.78 + * attribute within the action body, it will be replaced with the result
1.79 + * of this method. The question mark is considered part of the variable
1.80 + * name, thus aVar should be ?name and not simply name.
1.81 + *
1.82 + * @param aVar the variable to look up
1.83 + *
1.84 + * @return the value for the variable or a null string if it has no value
1.85 + */
1.86 + AString getBindingFor(in nsIAtom aVar);
1.87 +
1.88 + /**
1.89 + * Get an object value for a variable such as ?name for this result.
1.90 + *
1.91 + * This method may return null for a variable, even if getBindingFor returns
1.92 + * a non-null value for the same variable. This method is provided as a
1.93 + * convenience when sorting results.
1.94 + *
1.95 + * @param aVar the variable to look up
1.96 + *
1.97 + * @return the value for the variable or null if it has no value
1.98 + */
1.99 + nsISupports getBindingObjectFor(in nsIAtom aVar);
1.100 +
1.101 + /**
1.102 + * Indicate that a particular rule of a query has matched and that output
1.103 + * will be generated for it. Both the query as compiled by the query
1.104 + * processor's compileQuery method and the XUL <rule> element are supplied.
1.105 + * The query must always be one that was compiled by the query processor
1.106 + * that created this result. The <rule> element must always be a child of
1.107 + * the <query> element that was used to compile the query.
1.108 + *
1.109 + * @param aQuery the query that matched
1.110 + * @param aRuleNode the rule node that matched
1.111 + */
1.112 + void ruleMatched(in nsISupports aQuery, in nsIDOMNode aRuleNode);
1.113 +
1.114 + /**
1.115 + * Indicate that the output for a result has beeen removed and that the
1.116 + * result is no longer being used by the builder.
1.117 + */
1.118 + void hasBeenRemoved();
1.119 +};
