XBL Task Force Issue: Unmatched children

Abstract

This document is a working document within the XBL task force which discusses one of the outstanding issues in depth: what happens with children of the bound element which are not explicitly referenced by <content> elements. In particular, are the unmatched children are they excluded from the fully flattened tree (i.e., included in xblChildNodes) or auto-included within the fully flattened tree. This document describes the issues, lists the various proposals under consideration, and discusses pros and cons for the various proposals relative to particular examples. The overall goal with the document is to help the XBL task force make decisions at a particular moment in time. Once the XBL task force has discussed and made decisions about the given issue, this document may become obsolete and may not get updated to reflect the decisions that were made.

Table of contents

1 Introduction

The latest draft of sXBL (22Nov2004) includes the following request for public feedback:

Proposal 1: If an explicit child of the bound element does not match any of the content elements (or if there are no content elements in the shadow tree), then that child does not appear in the rendering tree.

Proposal 2: If an explicit child of the bound element does not match any of the content elements (or if there are no content elements in the shadow tree), then it shall be inserted at an implied content element at the end of the shadow tree (as if there was a content node with no attributes as the last child of every template element). (This ensures that the fully flattened tree is always a superset of the original DOM tree. Nodes that authors do not want in the rendering can always be explicitly inserted into a container that is marked display:none.)

2 Background

2.1 How Mozilla XBL does it

The Mozilla XBL spec does not appear to define what happens with unmatched children. However, the implemented behavior is that Mozilla XBL uses a binding only if all children of the bound element can be matched.

Neither active proposal on this issue matches Mozilla XBL behavior.

The Mozilla XBL behavior, if chosen, would be a conflict with how the SVG language has been constructed because the inclusion on non-renderable elements such as animation elements, defs tags, description tags, title tags, metadata tags, and even comments within a custom element would suddenly makes bindings no longer work because the new node would not match with the binding. This would be surprising behavior because in most (all?) other scenarios non-renderable elements in SVG have no rendering side-effects depending on whether they are included or not and non-renderable elements are allowed to appear in almost any place within an SVG document. One particularly important issue is that insertion of an <svg:desc> element as a child of a bound element purely to add descriptive text for accessibility reasons might break an XBL binding if the Mozilla matching rules were in place. In all other scenarios, adding an <svg:desc> element anywhere in the document has no effect on the rendered result.

2.2 How RCC did it

The description of RCC's <refContent> element did not explicitly define how unmatched children were treated, but Adobe's implementation and general agreement within the SVGWG is that unmatched children are excluded from the fully flattened tree and do not get rendered.

Proposal 1: Unmatched children are not auto-included in the fully flattened tree matches RCC's behavior.

3 Proposals

3.1 Proposal 1: Unmatched children are not auto-included in the fully flattened tree

3.1.1 Proposal

If an explicit child of the bound element does not match any of the content elements (or if there are no content elements in the shadow tree), then that child does not appear in the fully flattened tree (i.e., xblChildNodes) and does not get rendered.

XBL is used to define the presentation and interactive behavior of custom elements. A content developer includes a specific instruction (usually an <xbl:import>) within his content to use a particular set of XBL components. These XBL components will have a well-defined behavior which the content developer will know before he decides to references those components. Sometimes the defined behavior of an XBL component will be to render the custom element and all of its children, but other times the XBL component might render only a subset or even perhaps none of the children.

Here is one scenario: a scrollable table widget. Suppose you have a web application which displays a long dataset in the form of a table and that only a subset of rows (e.g., three) appears at any time. Your custom element might look like this:

<xbl:definition element="MyNS:ScrollingTable">
  <xbl:template>
    <table border="2">
      <content includes=""/>
      <content includes=""/>
      <content includes=""/>
    </table>
    <xforms:trigger><label>Scroll up</label></xforms:trigger>
    <xforms:trigger><label>Scroll down</label></xforms:trigger>
  </xbl:template>
  <xbl:handlerGroup>
    <!-- includes logic to handle bind events and user interface events -->
  </xbl:handlerGroup>
</xbl:definition>

And the bound document might look like this:

<MyNS:ScrollingTable">
  <tr><td>Region A1</td><td>33.000</td><td>22.55</td></tr>
  <tr><td>Region A2</td><td>23.000</td><td>47.65</td></tr>
  <tr><td>Region B1</td><td>31.000</td><td>24.21</td></tr>
  <tr><td>Region B2</td><td>35.000</td><td>83.65</td></tr>
  <tr><td>Region B3</td><td>43.000</td><td>19.43</td></tr>
  <tr><td>Region C1</td><td>53.000</td><td>95.64</td></tr>
  <tr><td>Region C1</td><td>18.000</td><td>36.44</td></tr>
  <tr><td>Region D1</td><td>38.000</td><td>22.55</td></tr>
  <tr><td>Region D2</td><td>22.000</td><td>57.43</td></tr>
</MyNS:ScrollingTable">

The component's event handlers would change the value of the 'includes' attribute as the end user activates the scroll buttons (the <xforms:trigger> elements) so that the 'includes' attributes would point to a different set of three <tr> elements.

The example above only shows 9 rows, but suppose the dataset instead consists of 90,000 rows. In some scenarios, it is feasible to allocate space in the Core DOM for such a large dataset, but allocating all of the extra internal memory within the user agent to support a 90,000 row table might exceed the capacity of many end user machines or result in horrible performance. The "trick" of creating a smaller size table only as large as the current view is a standard technique for achieving good user interface performance in scenarios with large datasets.

This example is trivial to implement if unmatched children do not get included in the fully flattened tree. However, if unmatched children are auto-placed at the end due to an implicit <content> element which matches all unmatched children, then all kinds of problems emerge, including memory explosion and incorrect content models (the <tr> elements would not be contained within a proper <table> ancestor).

Another usage scenario is when the XBL component delivers some sort of switching behavior between alternative element. For example, suppose the custom element is allowed to look like this:

<myNS:SkinnableWidget>
  <myNS:DropShadowSkin state="normal">...</myNS:DropShadowSkin>
  <myNS:DropShadowSkin state="hover">...</myNS:DropShadowSkin>
  <myNS:DropShadowSkin state="mousedown">...</myNS:DropShadowSkin>
  <myNS:BackgroundSkin state="normal">...</myNS:BackgroundSkin>
  <myNS:BackgroundSkin state="hover">...</myNS:BackgroundSkin>
  <myNS:BackgroundSkin state="mousedown">...</myNS:BackgroundSkin>
</myNS:SkinnableWidget>

The xblShadowTree might contain the following:

<xbl:shadowTree>
  <xbl:content includes="...ordinal reference to drop shadow skin..." />
  <xbl:content includes="...ordinal reference to background skin..." />
</xbl:shadowTree>

The component would respond to events and change the value of the 'includes' attribute based on the current interaction state for the given widget. This example is natural and easy to implement if unmatched children are ignored and more difficult and unnatural if you have to add an explicit "catch-all" <xbl:content> element at the end of component definition which is wrapped by a container with "display:none".

A third example shows that some XML grammars will just plain break in the presence of XBL if unmatched child elements are not ignored and instead auto-appended to the end of the flattened tree. The problem is that some XML grammars might not be able to handle any "garbage elements" in the rendering tree and sometimes exact positioning in the tree can be very important (MathML is like that). In some renderers there is no generic way to turn elements off, thus there is no reliable way to eliminate the content from affecting the rendering (SVG subgrammars from filters and gradients are like that). Thus it is important to have a _generic_ way _not_ to pass some elements in the flattened (rendering) tree. Here is an SVG example:

<MyNS:CustomGradient>
  <MyNS:Param>55</MyNS:Param>
</MyNS:CustomGradient>

SVG allows custom gradients using sXBL where the shadow tree contains a sequence of <stop> elements which are used to define the gradient. With the non-auto-include proposal, everything is fine. However, with the auto-include-at-end proposal, suddenly the SVG user agent encounters a <MyNS:Param> at the end of the gradient definition, which is an error because only <stop> elements are allowed. (And gradients do not offer a facility like <defs> for elements that can be ignored.) This is an SVG example, but it can be expected that the same sort of problem will be encountered in other XML grammars.

3.1.2 Arguments in favor

Arguments in favor of this proposal:

• The requirement that every child of a custom element must be in the flattened tree is artificial and unnecessary.
• Explicit control is a better design in general versus secret, automatic behavior. Where to place the content (if anywhere) is important design decision for every binding. Having it done automatically seems like a bad idea, especially since automatic placement can produce unintended or undesirable results in some cases.
• Some renderers might not be able to handle any "garbage elements" in the rendering tree and exact positioning in the tree can be very important (MathML is like that). In some renderers there is no generic way to turn elements off, thus there is no reliable way to eliminate the content from affecting the rendering (SVG subgrammars from filters and gradients are like that). Thus it is important to have a _generic_ way _not_ to pass some elements in the flattened (rendering) tree.
• Elements often want to use their children as structured configuration parameters and not pass them to the renderer; for instance html:select, svg:filter, smil:transition. These elements all have child elements which act as attributes and not as rendered content. This is especially true for UI widgets and other "leaf" elements that XBL is especially straightforward to use for.
• There are scenarios where inclusion of the unmatched children have major negative consequences, such as the large dataset example above.
• The only possible negative with this approach is a very minor inconvenience for some component developers who have a need to have unmatched children appended to the end of the rendered tree. For them, the inconvenience amounts to including the following element - <content/> - at the end of the <xbl:template>. This inconvenience for a subset of component developers who need auto-append is less inconvenient and less unnatural than what SVG component developers would have to do (i.e., insert a <defs><content/></defs> at the end of the component) to prevent the auto-append, but the truly serious issue is that the auto-append rule is broken in some cases.

3.1.3 Arguments against

Arguments against:

• Elements simply disappearing is unintuitive and could arguably lead to the appearence of data loss.
• Letting elements that are in the DOM simply disappear from the rendering tree is not in the spirit of our work in making XBL invisible to the markup author. It exposes the workings of the binding to that author.
• By taking nodes that are in the original DOM out of the flattened tree we will end up having to redefine event bubbling so it works whether the element is in the flattened tree or not, instead of just having one definition.

3.2 Proposal 2: Unmatched nodes are auto-included at end of shadow tree

3.2.1 Proposal

Nodes that match no insertion points should be inserted at the end of the shadow tree.

3.1.2 Arguments in favor

Arguments in favor of this proposal:

• The alternative, namely letting elements that are in the DOM simply disappear from the rendering tree, is not in the spirit of our work in making XBL invisible to the markup author. It exposes the workings of the binding to that author.
• ::before/::after and other pseudo-elements need to continue working on elements, even if the binding doesn't mention them, so that the author's styles don't get broken by him using a binding.
• By taking nodes that are in the original DOM out of the flattened tree we will end up having to redefine event bubbling so it works whether the element is in the flattened tree or not, instead of just having one definition.

3.1.3 Arguments against

Arguments against:

• See arguments for Proposal 1, which also highlight problems with Proposal 2.
• The "XBL invisibility" argument and "::before/::after" arguments do not hold water. This issue is orthogonal to how a component is implemented. With either proposal, a component could choose to not render or prevent rendering of particular child elements (e.g., by wrapping <content> elements in a container element with display:none).
• More on the "XBL invisibility" issue (rather "non-issue"): when an author includes Custom XML and then references some XBL components (e.g., via <xbl:import>) which map the Custom XML into presentation and interactive behavior. By referencing the XBL component, the author has taken specific action to incorporate the defined behavior of the given XBL component. If the component's behavior is that it somehow renders all children of the bound element, then that's what happens. If the component's behavior is that it renders only a subset or even none of the children of the bound element, then that's what happens. For the case where XBL is used "under the hood" by the user agent, such as using XBL to map HTML forms controls into low-level SVG, in this case the XBL component will be defined such it renders the HTML forms control completely because that is what the component is supposed to do.
• Regarding event bubbling, there is a non-issue relative to whether unmatched children are in the rendering tree or not. From an implementation perspective, just bubble events to xblParentNode if it is not null, end of story. Even if it were more complicated than this, there is already special stitching necessary to implement XBL due to shadow trees and <content> elements, with event stitching just one of various things that have to be stitched together. The "auto-include-at-end" approach add extra implementation to do the special DOM stitching to pull off the proposal. (Note: both proposals are readily implementable. This issue is more about what is the right thing to do from a language definition perspective.)
• Any CSS selector issues are orthogonal. CSS applies to all nodes regardless of whether they are in the rendering tree or not. Ability to resolve CSS cascaded properties for every element is a requirement, but it does not imply that all elements must go into the flattened tree.
• The requirement that every child of a custom element must be in the flattened tree is artificial and unnecessary.

4 Outside Feedback

Not yet assembled.