1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/xul/templates/public/nsIXULTemplateBuilder.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,409 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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 "domstubs.idl"
1.10 +
1.11 +interface nsIAtom;
1.12 +interface nsIContent;
1.13 +interface nsIXULBuilderListener;
1.14 +interface nsIXULTemplateResult;
1.15 +interface nsIXULTemplateRuleFilter;
1.16 +interface nsIXULTemplateQueryProcessor;
1.17 +interface nsIRDFResource;
1.18 +interface nsIRDFCompositeDataSource;
1.19 +interface nsIDOMDataTransfer;
1.20 +
1.21 +/**
1.22 + * A template builder, given an input source of data, a template, and a
1.23 + * reference point, generates a list of results from the input, and copies
1.24 + * part of the template for each result. Templates may generate content
1.25 + * recursively, using the same template, but with the previous iteration's
1.26 + * results as the reference point. As an example, for an XML datasource the
1.27 + * initial reference point would be a specific node in the DOM tree and a
1.28 + * template might generate a list of all child nodes. For the next iteration,
1.29 + * those children would be used to generate output for their child nodes and
1.30 + * so forth.
1.31 + *
1.32 + * A template builder is attached to a single DOM node; this node is called
1.33 + * the root node and is expected to contain a XUL template element as a direct
1.34 + * child. Different template builders may be specialized in the manner in
1.35 + * which they generate and display the resulting content from the template.
1.36 + *
1.37 + * The structure of a template is as follows:
1.38 + *
1.39 + * <rootnode datasources="" ref="">
1.40 + * <template>
1.41 + * <queryset>
1.42 + * <query>
1.43 + * </query>
1.44 + * <rule>
1.45 + * <conditions>...</conditions>
1.46 + * <bindings>...</bindings>
1.47 + * <action>...</action>
1.48 + * </rule>
1.49 + * </queryset>
1.50 + * </template>
1.51 + * </rootnode>
1.52 + *
1.53 + * The datasources attribute on the root node is used to identify the source
1.54 + * of data to be used. The ref attribute is used to specify the reference
1.55 + * point for the query. Currently, the datasource will either be an
1.56 + * nsIRDFDataSource or a DOM node. In the future, other datasource types may
1.57 + * be used.
1.58 + *
1.59 + * The <queryset> element contains a single query and one or more <rule>
1.60 + * elements. There may be more than one <queryset> if multiple queries are
1.61 + * desired, and this element is optional if only one query is needed -- in
1.62 + * that case the <query> and <rule>s are allowed to be children of the
1.63 + * <template> node
1.64 + *
1.65 + * The contents of the query are processed by a separate component called a
1.66 + * query processor. This query processor is expected to use this query to
1.67 + * generate results when asked by the template builder. The template builder
1.68 + * then generates output for each result based on the <rule> elements.
1.69 + *
1.70 + * This allows the query processor to be specific to a particular kind of
1.71 + * input data or query syntax, while the template builder remains independent
1.72 + * of the kind of data being used. Due to this, the query processor will be
1.73 + * supplied with the datasource and query which the template builder handles
1.74 + * in an opaque way, while the query processor handles these more
1.75 + * specifically.
1.76 + *
1.77 + * Results implement the nsIXULTemplateResult interface and may be identified
1.78 + * by an id which must be unique within a given set of query results.
1.79 + *
1.80 + * Each query may be accompanied by one or more <rule> elements. These rules
1.81 + * are evaluated by the template builder for each result produced by the
1.82 + * query. A rule consists of conditions that cause a rule to be either
1.83 + * accepted or rejected. The condition syntax allows for common conditional
1.84 + * handling; additional filtering may be applied by adding a custom filter
1.85 + * to a rule with the builder's addRuleFilter method.
1.86 + *
1.87 + * If a result passes a rule's conditions, this is considered a match, and the
1.88 + * content within the rule's <action> body is inserted as a sibling of the
1.89 + * <template>, assuming the template builder creates real DOM content. Only
1.90 + * one rule will match a result. For a tree builder, for example, the content
1.91 + * within the action body is used to create the tree rows instead. A matching
1.92 + * result must have its ruleMatched method called. When a result no longer
1.93 + * matches, the result's hasBeenRemoved method must be called.
1.94 + *
1.95 + * Optionally, the rule may have a <bindings> section which may be used to
1.96 + * define additional variables to be used within an action body. Each of these
1.97 + * declared bindings must be supplied to the query processor via its
1.98 + * addBinding method. The bindings are evaluated after a rule has matched.
1.99 + *
1.100 + * Templates may generate content recursively, using the previous iteration's
1.101 + * results as reference point to invoke the same queries. Since the reference
1.102 + * point is different, different output will typically be generated.
1.103 + *
1.104 + * The reference point nsIXULTemplateResult object for the first iteration is
1.105 + * determined by calling the query processor's translateRef method using the
1.106 + * value of the root node's ref attribute. This object may be retrieved later
1.107 + * via the builder's rootResult property.
1.108 + *
1.109 + * For convenience, each reference point as well as all results implement the
1.110 + * nsIXULTemplateResult interface, allowing the result objects from each
1.111 + * iteration to be used directly as the reference points for the next
1.112 + * iteration.
1.113 + *
1.114 + * When using multiple queries, each may generate results with the same id.
1.115 + * More than one of these results may match one of the rules in their
1.116 + * respective queries, however only the result for the earliest matching query
1.117 + * in the template becomes the active match and generates output. The
1.118 + * addResult, removeResult, replaceResult and resultBindingChanged methods may
1.119 + * be called by the query processor to indicate that the set of valid results
1.120 + * has changed, such that a different query may match. If a different match
1.121 + * would become active, the content for the existing match is removed and the
1.122 + * content for the new match is generated. A query processor is not required
1.123 + * to provide any support for updating results after they have been generated.
1.124 + *
1.125 + * See http://wiki.mozilla.org/XUL:Templates_Plan for details about templates.
1.126 + */
1.127 +[scriptable, uuid(A583B676-5B02-4F9C-A0C9-CB850CB99818)]
1.128 +interface nsIXULTemplateBuilder : nsISupports
1.129 +{
1.130 + /**
1.131 + * The root node in the DOM to which this builder is attached.
1.132 + */
1.133 + readonly attribute nsIDOMElement root;
1.134 +
1.135 + /**
1.136 + * The opaque datasource object that is used for the template. This object
1.137 + * is created by the getDataSource method of the query processor. May be
1.138 + * null if the datasource has not been loaded yet. Set this attribute to
1.139 + * use a different datasource and rebuild the template.
1.140 + *
1.141 + * For an RDF datasource, this will be the same as the database. For XML
1.142 + * this will be the nsIDOMNode for the datasource document or node for
1.143 + * an inline reference (such as #name). Other query processors may use
1.144 + * other types for the datasource.
1.145 + */
1.146 + attribute nsISupports datasource;
1.147 +
1.148 + /**
1.149 + * The composite datasource that the template builder observes
1.150 + * and uses to create content. This is used only for RDF queries and is
1.151 + * maintained for backwards compatibility. It will be the same object as
1.152 + * the datasource property. For non-RDF queries, it will always be null.
1.153 + */
1.154 + readonly attribute nsIRDFCompositeDataSource database;
1.155 +
1.156 + /**
1.157 + * The virtual result representing the starting reference point,
1.158 + * determined by calling the query processor's translateRef method
1.159 + * with the root node's ref attribute as an argument.
1.160 + */
1.161 + readonly attribute nsIXULTemplateResult rootResult;
1.162 +
1.163 + /**
1.164 + * The query processor used to generate results.
1.165 + */
1.166 + [noscript] readonly attribute nsIXULTemplateQueryProcessor queryProcessor;
1.167 +
1.168 + /**
1.169 + * Force the template builder to rebuild its content. All existing content
1.170 + * will be removed first. The query processor's done() method will be
1.171 + * invoked during cleanup, followed by its initializeForBuilding method
1.172 + * when the content is to be regenerated.
1.173 + *
1.174 + */
1.175 + void rebuild();
1.176 +
1.177 + /**
1.178 + * Reload any of our RDF datasources that support nsIRDFRemoteDatasource.
1.179 + *
1.180 + * @note This is a temporary hack so that remote-XUL authors can
1.181 + * reload remote datasources. When RDF becomes remote-scriptable,
1.182 + * this will no longer be necessary.
1.183 + */
1.184 + void refresh();
1.185 +
1.186 + /**
1.187 + * Inform the template builder that a new result is available. The builder
1.188 + * will add this result to the set of results. The query node that the
1.189 + * new result applies to must be specified using the aQueryNode parameter.
1.190 + *
1.191 + * The builder will apply the rules associated with the query to the new
1.192 + * result, unless a result with the same id from an earlier query
1.193 + * supersedes it, and the result's RuleMatched method will be called if it
1.194 + * matches.
1.195 + *
1.196 + * @param aResult the result to add
1.197 + * @param aQueryNode the query that the result applies to
1.198 + *
1.199 + * @throws NS_ERROR_NULL_POINTER if aResult or aQueryNode are null
1.200 + */
1.201 + void addResult(in nsIXULTemplateResult aResult, in nsIDOMNode aQueryNode);
1.202 +
1.203 + /**
1.204 + * Inform the template builder that a result no longer applies. The builder
1.205 + * will call the remove content generated for the result, if any. If a different
1.206 + * query would then match instead, it will become the active match. This
1.207 + * method will have no effect if the result isn't known to the builder.
1.208 + *
1.209 + * @param aResult the result to remove
1.210 + *
1.211 + * @throws NS_ERROR_NULL_POINTER if aResult is null
1.212 + */
1.213 + void removeResult(in nsIXULTemplateResult aResult);
1.214 +
1.215 + /**
1.216 + * Inform the template builder that one result should be replaced with
1.217 + * another. Both the old result (aOldResult) and the new result
1.218 + * (aNewResult) must have the same id. The query node that the new result
1.219 + * applies to must be specified using the aQueryNode parameter.
1.220 + *
1.221 + * This method is expected to have the same effect as calling both
1.222 + * removeResult for the old result and addResult for the new result.
1.223 + *
1.224 + * @param aOldResult the old result
1.225 + * @param aNewResult the new result
1.226 + * @param aQueryNode the query that the new result applies to
1.227 + *
1.228 + * @throws NS_ERROR_NULL_POINTER if either argument is null, or
1.229 + * NS_ERROR_INVALID_ARG if the ids don't match
1.230 + */
1.231 + void replaceResult(in nsIXULTemplateResult aOldResult,
1.232 + in nsIXULTemplateResult aNewResult,
1.233 + in nsIDOMNode aQueryNode);
1.234 +
1.235 + /**
1.236 + * Inform the template builder that one or more of the optional bindings
1.237 + * for a result has changed. In this case, the rules are not reapplied as
1.238 + * it is expected that the same rule will still apply. The builder will
1.239 + * resynchronize any variables that are referenced in the action body.
1.240 + *
1.241 + * @param aResult the result to change
1.242 + *
1.243 + * @throws NS_ERROR_NULL_POINTER if aResult is null
1.244 + */
1.245 + void resultBindingChanged(in nsIXULTemplateResult aResult);
1.246 +
1.247 + /**
1.248 + * Return the result for a given id. Only one such result is returned and
1.249 + * is always the result with that id associated with the active match.
1.250 + * This method will return null is there is no result for the id.
1.251 + *
1.252 + * @param aId the id to return the result for
1.253 + */
1.254 + nsIXULTemplateResult getResultForId(in AString aId);
1.255 +
1.256 + /**
1.257 + * Retrieve the result corresponding to a generated element, or null is
1.258 + * there isn't one.
1.259 + *
1.260 + * @param aContent element to result the result of
1.261 + */
1.262 + nsIXULTemplateResult getResultForContent(in nsIDOMElement aElement);
1.263 +
1.264 + /**
1.265 + * Returns true if the node has content generated for it. This method is
1.266 + * intended to be called only by the RDF query processor. If aTag is set,
1.267 + * the content must have a tag name that matches aTag. aTag may be ignored
1.268 + * for builders that don't generate real DOM content.
1.269 + *
1.270 + * @param aNode node to check
1.271 + * @param aTag tag that must match
1.272 + */
1.273 + boolean hasGeneratedContent(in nsIRDFResource aNode, in nsIAtom aTag);
1.274 +
1.275 + /**
1.276 + * Adds a rule filter for a given rule, which may be used for specialized
1.277 + * rule filtering. Any existing filter on the rule is removed. The default
1.278 + * conditions specified inside the <rule> tag are applied before the
1.279 + * rule filter is applied, meaning that the filter may be used to further
1.280 + * filter out results but not reaccept results that have already been
1.281 + * rejected.
1.282 + *
1.283 + * @param aRule the rule to apply the filter to
1.284 + * @param aFilter the filter to add
1.285 + */
1.286 + void addRuleFilter(in nsIDOMNode aRule, in nsIXULTemplateRuleFilter aFilter);
1.287 +
1.288 + /**
1.289 + * Called to initialize a XUL content builder on a particular root
1.290 + * element. This element presumably has a ``datasources''
1.291 + * attribute, which the builder will parse to set up the template
1.292 + * builder's datasources.
1.293 + */
1.294 + [noscript] void init(in nsIContent aElement);
1.295 +
1.296 + /**
1.297 + * Invoked lazily by a XUL element that needs its child content built.
1.298 + * If aForceCreation is true, then the contents of an element will be
1.299 + * generated even if it is closed. If false, the element will only
1.300 + * generate its contents if it is open. This behaviour is used with menus.
1.301 + */
1.302 + [noscript] void createContents(in nsIContent aElement,
1.303 + in boolean aForceCreation);
1.304 +
1.305 + /**
1.306 + * Add a listener to this template builder. The template builder
1.307 + * holds a strong reference to the listener.
1.308 + */
1.309 + void addListener(in nsIXULBuilderListener aListener);
1.310 +
1.311 + /**
1.312 + * Remove a listener from this template builder.
1.313 + */
1.314 + void removeListener(in nsIXULBuilderListener aListener);
1.315 +};
1.316 +
1.317 +/**
1.318 + * nsIXULTreeBuilderObserver
1.319 + * This interface allows clients of the XULTreeBuilder to define domain
1.320 + * specific handling of specific nsITreeView methods that
1.321 + * XULTreeBuilder does not implement.
1.322 + */
1.323 +[scriptable, uuid(57CED9A7-EC0B-4A0E-8AEB-5DA32EBE951C)]
1.324 +interface nsIXULTreeBuilderObserver : nsISupports
1.325 +{
1.326 + const long DROP_BEFORE = -1;
1.327 + const long DROP_ON = 0;
1.328 + const long DROP_AFTER = 1;
1.329 + /**
1.330 + * Methods used by the drag feedback code to determine if a drag is allowable at
1.331 + * the current location. To get the behavior where drops are only allowed on
1.332 + * items, such as the mailNews folder pane, always return false whe
1.333 + * the orientation is not DROP_ON.
1.334 + */
1.335 + boolean canDrop(in long index, in long orientation, in nsIDOMDataTransfer dataTransfer);
1.336 +
1.337 + /**
1.338 + * Called when the user drops something on this view. The |orientation| param
1.339 + * specifies before/on/after the given |row|.
1.340 + */
1.341 + void onDrop(in long row, in long orientation, in nsIDOMDataTransfer dataTransfer);
1.342 +
1.343 + /**
1.344 + * Called when an item is opened or closed.
1.345 + */
1.346 + void onToggleOpenState (in long index);
1.347 +
1.348 + /**
1.349 + * Called when a header is clicked.
1.350 + */
1.351 + void onCycleHeader(in wstring colID, in nsIDOMElement elt);
1.352 +
1.353 + /**
1.354 + * Called when a cell in a non-selectable cycling column (e.g.
1.355 + * unread/flag/etc.) is clicked.
1.356 + */
1.357 + void onCycleCell(in long row, in wstring colID);
1.358 +
1.359 + /**
1.360 + * Called when selection in the tree changes
1.361 + */
1.362 + void onSelectionChanged();
1.363 +
1.364 + /**
1.365 + * A command API that can be used to invoke commands on the selection.
1.366 + * The tree will automatically invoke this method when certain keys
1.367 + * are pressed. For example, when the DEL key is pressed, performAction
1.368 + * will be called with the "delete" string.
1.369 + */
1.370 + void onPerformAction(in wstring action);
1.371 +
1.372 + /**
1.373 + * A command API that can be used to invoke commands on a specific row.
1.374 + */
1.375 + void onPerformActionOnRow(in wstring action, in long row);
1.376 +
1.377 + /**
1.378 + * A command API that can be used to invoke commands on a specific cell.
1.379 + */
1.380 + void onPerformActionOnCell(in wstring action, in long row, in wstring colID);
1.381 +};
1.382 +
1.383 +[scriptable, uuid(06b31b15-ebf5-4e74-a0e2-6bc0a18a3969)]
1.384 +interface nsIXULTreeBuilder : nsISupports
1.385 +{
1.386 + /**
1.387 + * Retrieve the RDF resource associated with the specified row.
1.388 + */
1.389 + nsIRDFResource getResourceAtIndex(in long aRowIndex);
1.390 +
1.391 + /**
1.392 + * Retrieve the index associated with specified RDF resource.
1.393 + */
1.394 + long getIndexOfResource(in nsIRDFResource resource);
1.395 +
1.396 + /**
1.397 + * Add a Tree Builder Observer to handle Tree View
1.398 + * methods that the base builder does not implement.
1.399 + */
1.400 + void addObserver(in nsIXULTreeBuilderObserver aObserver);
1.401 +
1.402 + /**
1.403 + * Remove an Tree Builder Observer.
1.404 + */
1.405 + void removeObserver(in nsIXULTreeBuilderObserver aObserver);
1.406 +
1.407 + /**
1.408 + * Sort the contents of the tree using the specified column.
1.409 + */
1.410 + void sort(in nsIDOMElement aColumnElement);
1.411 +};
1.412 +
