You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3533 lines
142 KiB
3533 lines
142 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
|
|
<html lang="en" xmlns="http://www.w3.org/1999/xhtml"><!--
|
|
|
|
NOTES FOR EDITORS
|
|
=================
|
|
|
|
To convert this file to the sXBL.html file
|
|
for publication, use the script found here:
|
|
|
|
http://www.w3.org/Style/Group/css3-src/bin/postprocess
|
|
|
|
Definitions are marked with <dfn>...</dfn>
|
|
|
|
Proposed insertions and deletions are marked with:
|
|
|
|
<div class="issue">...explanation...</div>
|
|
<del cite="...uri...">...old text...</del>
|
|
<ins cite="...uri...">...new text...</ins>
|
|
|
|
...where "uri" is the uri to the archives where the proposal was
|
|
first made.
|
|
|
|
Cross references are made with <span>...</span> where the
|
|
contents match the contents of a <dfn> element, or <span
|
|
title="...">...</span> where the title does.
|
|
|
|
For more details see:
|
|
|
|
http://www.w3.org/Style/Group/css3-src/css3-template/Overview.src.html
|
|
|
|
-->
|
|
|
|
<head>
|
|
<title>SVG's XML Binding Language (sXBL)</title>
|
|
|
|
<link href="default.css" rel="stylesheet" type="text/css" />
|
|
|
|
<link href="http://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet"
|
|
type="text/css" />
|
|
</head>
|
|
|
|
<body class="draft">
|
|
<div class="head">
|
|
<p> <a class="logo" href="http://www.w3.org/" rel="home"><img alt="W3C"
|
|
height="48" src="http://www.w3.org/Icons/w3c_home" width="72" /></a></p>
|
|
|
|
<h1 id="svgs-xml">SVG's XML Binding Language (sXBL)</h1>
|
|
|
|
<h2 class="no-num no-toc" id="w3c-working">W3C Working Draft 15 August 2005</h2>
|
|
|
|
<dl>
|
|
<dt>This version:</dt>
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2005/WD-sXBL-20050815">http://www.w3.org/TR/2005/WD-sXBL-20050815</a></dd>
|
|
|
|
<dt>Latest version:</dt>
|
|
|
|
<dd><a href="http://www.w3.org/TR/sXBL">http://www.w3.org/TR/sXBL</a></dd>
|
|
|
|
<dt>Previous version:</dt>
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2005/WD-sXBL-20050405/">http://www.w3.org/TR/2005/WD-sXBL-20050405/</a></dd>
|
|
|
|
|
|
<dt>Editors:</dt>
|
|
|
|
<dd>Jon Ferraiolo, Adobe Systems, <a
|
|
href="mailto:jon.ferraiolo@adobe.com">jon.ferraiolo@adobe.com</a></dd>
|
|
|
|
<dd>Ian Hickson, Opera Software, <a
|
|
href="mailto:ian@hixie.ch">ian@hixie.ch</a></dd>
|
|
|
|
<dd>David Hyatt, Apple, <a
|
|
href="mailto:hyatt@apple.com">hyatt@apple.com</a></dd>
|
|
</dl>
|
|
<!--begin-copyright-->
|
|
|
|
<p class="copyright"><a
|
|
href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">
|
|
Copyright</a> © 2005 <a href="http://www.w3.org/"><abbr title="World
|
|
Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a
|
|
href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of
|
|
Technology">MIT</abbr></a>, <a href="http://www.ercim.org/"><acronym
|
|
title="European Research Consortium for Informatics and
|
|
Mathematics">ERCIM</acronym></a>, <a
|
|
href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
|
|
href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
|
|
<a
|
|
href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
|
|
|
|
and <a
|
|
href="http://www.w3.org/Consortium/Legal/copyright-documents">document
|
|
use</a> rules apply.</p>
|
|
<!--end-copyright-->
|
|
<hr />
|
|
</div>
|
|
|
|
<h2 class="no-num no-toc" id="abstract">Abstract</h2>
|
|
|
|
<p>This working draft describes SVG's XML Binding Language (s<abbr
|
|
title="XBL Binding Language">XBL</abbr>). sXBL is a mechanism for defining
|
|
the presentation and interactive behavior of elements described in a
|
|
namespace other than SVG's.</p>
|
|
|
|
<p>sXBL is intended to be used to enable XML vocabularies (tag sets) to be
|
|
implemented in terms of SVG elements. For instance, a tag set describing a
|
|
flowchart could be mapped to low-level SVG path and text elements,
|
|
possibly including interactivity and animation.</p>
|
|
|
|
<p>sXBL is intended to be an SVG-specific first version of a more
|
|
general-purpose XBL specification (e.g., "XBL 2.0"). The intent is that,
|
|
in the future, a general-purpose and modularly-defined XBL specification
|
|
will be developed which will replace this specification and will define
|
|
additional features that are necessary to support scenarios beyond SVG,
|
|
such as integration into web browsers that support CSS. Once a
|
|
general-purpose XBL is defined, sXBL would just become an SVG-specific
|
|
subset (i.e., a profile) of the larger XBL specification.</p>
|
|
|
|
<h2 class="no-num" id="status">Status of this document</h2>
|
|
|
|
<p><em>This section describes the status of this document at the time of
|
|
its publication. Other documents may supersede this document. A list of
|
|
current W3C publications and the latest revision of this technical report
|
|
can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
|
|
index</a> at http://www.w3.org/TR/.</em></p>
|
|
|
|
<p>This document is the fourth public working draft of the sXBL
|
|
specification. This publication is especially intended to gather feedback
|
|
on <a href="#includes-syntax">the syntax and performance of the
|
|
<code>includes</code> attribute</a>.</p>
|
|
|
|
<p>We explicitly invite comments on this specification and that issue in
|
|
particular. Please send them to <a
|
|
href="mailto:www-svg@w3.org">www-svg@w3.org</a>, the public e-mail list
|
|
for issues related to vector graphics on the Web. This list is <a
|
|
href="http://lists.w3.org/Archives/Public/www-svg/">archived</a> and
|
|
acceptance of this archiving policy is requested automatically upon first
|
|
post. To subscribe to this list send an email to <a
|
|
href="mailto:www-svg-request@w3.org">www-svg-request@w3.org</a> with the
|
|
word subscribe in the subject line.</p>
|
|
|
|
<p>The feature set in sXBL represents a repackaging and generalization of
|
|
the <em>Rendering Custom Content</em> (RCC) feature which had been
|
|
described in previous SVG 1.2 specifications (see <a
|
|
href="http://www.w3.org/TR/2004/WD-SVG12-20040510/#rcc">RCC</a>). With
|
|
this public draft, the features that were formerly in RCC have been
|
|
factored out into a separate specification, reformulated for more general
|
|
applicability for possible future use with other markup languages and
|
|
moved into an XBL-specific namespace. The refactoring of RCC into sXBL was
|
|
partly the result of coordination efforts within the W3C across working
|
|
groups (particularly the SVG and CSS working groups) to ensure that
|
|
RCC/sXBL was forward-looking and could develop into a future
|
|
modularly-defined and general-purpose XBL specification which met the
|
|
needs of multiple XML markup languages, not just SVG.</p>
|
|
|
|
<p>As a result of the reformulation, nearly every element from RCC has been
|
|
renamed. Although there have been major changes in syntax, the resulting
|
|
sXBL feature set performs the same operations and satisfies the same
|
|
requirements as RCC. Sometimes it is possible to migrate RCC-based widget
|
|
definitions to XBL-based widget definitions after some global search and
|
|
replace string substitutions.</p>
|
|
|
|
<p>This document has been produced by the sXBL subgroup of the <a
|
|
href="http://www.w3.org/Graphics/SVG/">W3C SVG Working Group</a> as part
|
|
of the W3C <a href="http://www.w3.org/Graphics/Activity">Graphics
|
|
Activity</a>, within the <a
|
|
href="http://www.w3.org/Interaction/">Interaction Domain</a>.</p>
|
|
|
|
<p>The XBL task force considers the sXBL specification nearly ready for
|
|
Last Call. After evaluating public feedback on this draft, the next
|
|
public draft might be a Last Call working draft.</p>
|
|
|
|
<p>The patent policy for this document is the <a
|
|
href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
|
|
2004 W3C Patent Policy</a>. Patent disclosures relevant to this
|
|
specification may be found on the <a
|
|
href="http://www.w3.org/Graphics/SVG/Disclosures" rel="disclosure">SVG
|
|
Working Group's patent disclosure page</a>. An individual who has actual
|
|
knowledge of a patent which the individual believes contains Essential
|
|
Claim(s) with respect to this specification should disclose the
|
|
information in accordance with <a
|
|
href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
|
|
6 of the W3C Patent Policy</a>.</p>
|
|
|
|
<p>Publication as a Working Draft does not imply endorsement by the W3C
|
|
Membership. This is a draft document and may be updated, replaced or
|
|
obsoleted by other documents at any time. It is inappropriate to cite this
|
|
document as other than work in progress.</p>
|
|
|
|
<h2 class="no-num no-toc" id="table">Table of contents</h2>
|
|
|
|
<!--begin-toc-->
|
|
|
|
<ul class="toc">
|
|
<li class="no-num"><a href="#status">Status of this document</a></li>
|
|
|
|
<li><a href="#introduction"><span class="secno">1. </span>Introduction</a>
|
|
|
|
<ul class="toc">
|
|
<li><a href="#history"><span class="secno">1.1. </span>History</a></li>
|
|
|
|
<li><a href="#terminology"><span class="secno">1.2. </span>Terminology
|
|
and Conventions</a></li>
|
|
|
|
<li><a href="#conformance"><span class="secno">1.3.
|
|
</span>Conformance</a></li>
|
|
|
|
<li><a href="#loading"><span class="secno">1.4. </span><dfn
|
|
id="loading0">Loading External Resources</dfn></a></li>
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
<li><a href="#xbl-elements"><span class="secno">2. </span>XBL Elements</a>
|
|
|
|
<ul class="toc">
|
|
<li><a href="#the-xbl"><span class="secno">2.1. </span>The <dfn
|
|
id="xbl">xbl</dfn> Element</a></li>
|
|
|
|
<li><a href="#the-definition"><span class="secno">2.2. </span>The <dfn
|
|
id="definition">definition</dfn> Element</a></li>
|
|
|
|
<li><a href="#the-template"><span class="secno">2.3. </span>The <dfn
|
|
id="template">template</dfn> Element</a></li>
|
|
|
|
<li><a href="#the-content"><span class="secno">2.4. </span>The <dfn
|
|
id="content">content</dfn> Element</a></li>
|
|
|
|
<li><a href="#the-handlergroup"><span class="secno">2.5. </span>The <dfn
|
|
id="handlergroup">handlerGroup</dfn> Element</a></li>
|
|
|
|
<li><a href="#the-import"><span class="secno">2.6. </span>The <dfn
|
|
id="import">import</dfn> Element</a></li>
|
|
|
|
<li><a href="#the-id"><span class="secno">2.7. </span>The <dfn id="id"
|
|
title="attr-id">id</dfn> attribute of XBL elements</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#binding"><span class="secno">3. </span><dfn
|
|
id="binding3">Binding Attachment and Detachment</dfn></a>
|
|
<ul class="toc">
|
|
|
|
<li><a href="#interpretation"><span class="secno">3.1. </span><dfn
|
|
id="interpretation0">Interpretation of URIs to XBL bindings</dfn></a></li>
|
|
|
|
<li><a href="#attachment"><span class="secno">3.2. </span><dfn
|
|
id="attachment0" title="attachment using bind">Attachment using
|
|
<code>definition</code></dfn></a></li>
|
|
|
|
<li><a href="#binding0"><span class="secno">3.3. </span><dfn
|
|
id="binding4">Binding Attachment Model</dfn></a></li>
|
|
|
|
<li><a href="#binding1"><span class="secno">3.4. </span>Binding
|
|
Detachment Model</a></li>
|
|
|
|
<li><a href="#summary"><span class="secno">3.5. </span>Summary of
|
|
Events</a></li>
|
|
|
|
<li><a href="#script"><span class="secno">3.6. </span><dfn
|
|
id="script0">Script contexts</dfn></a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#shadow"><span class="secno">4. </span><dfn
|
|
id="shadow2">Shadow Content</dfn></a>
|
|
|
|
<ul class="toc">
|
|
<li><a href="#rules"><span class="secno">4.1. </span><dfn
|
|
id="rules0">Rules for Shadow Content Generation</dfn></a></li>
|
|
|
|
<li><a href="#processing"><span class="secno">4.2. </span><dfn
|
|
id="processing0">Processing <code>content</code> elements</dfn></a></li>
|
|
|
|
<li><a href="#handling"><span class="secno">4.3. </span>Handling DOM
|
|
Changes</a></li>
|
|
|
|
<li><a href="#shadow0"><span class="secno">4.4. </span>Shadow Content
|
|
and CSS</a>
|
|
<ul class="toc">
|
|
<li><a href="#terminology0"><span class="secno">4.4.1.
|
|
</span>Terminology</a></li>
|
|
|
|
<li><a href="#selectors"><span class="secno">4.4.2. </span><dfn
|
|
id="selectors0">Selectors and Shadow Scopes</dfn></a></li>
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
<li><a href="#shadow1"><span class="secno">4.5. </span>Shadow Content
|
|
and <code>xml:base</code></a></li>
|
|
|
|
<li><a href="#binding2"><span class="secno">4.6. </span><dfn
|
|
id="binding5">Binding Stylesheets</dfn></a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#event"><span class="secno">5. </span><dfn id="event2">Event
|
|
Handlers</dfn></a>
|
|
<ul class="toc">
|
|
<li><a href="#event0"><span class="secno">5.1. </span><dfn
|
|
id="event3">Event forwarding</dfn></a></li>
|
|
|
|
<li><a href="#event1"><span class="secno">5.2. </span><dfn
|
|
id="event4">Event Flow and Targeting Across Shadow Scopes</dfn></a></li>
|
|
|
|
<li><a href="#focus"><span class="secno">5.3. </span>Focus, DOMFocusIn,
|
|
Blur, and DOMFocusOut Events</a></li>
|
|
|
|
<li><a href="#mouseover"><span class="secno">5.4. </span>Mouseover and
|
|
Mouseout Events</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#dom-interfaces"><span class="secno">6. </span><dfn
|
|
id="dom-interfaces0">DOM Interfaces</dfn></a>
|
|
|
|
<ul class="toc">
|
|
<li><a href="#the-nodexbl"><span class="secno">6.1. </span>The <dfn
|
|
id="nodexbl">NodeXBL</dfn> Interface</a>
|
|
<ul class="toc">
|
|
<li><a href="#scoping"><span class="secno">6.1.1. </span>Scoping and
|
|
Access Using the DOM</a></li>
|
|
|
|
<li><a href="#dom-traversals"><span class="secno">6.1.2. </span><dfn
|
|
id="dom-traversals0">DOM Traversals in the Presence of XBL</dfn></a></li>
|
|
|
|
<li><a href="#example"><span class="secno">6.1.3. </span>Example of
|
|
XBL DOM Traversals</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#the-event"><span class="secno">6.2. </span>The
|
|
<code>Event</code> Interface</a></li>
|
|
|
|
<li><a href="#the-xblshadowtreeelement"><span class="secno">6.3.
|
|
</span>The <dfn id="xblshadowtreeelement">XBLShadowTreeElement</dfn>
|
|
Interface</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#Examples"><span class="secno">7. </span>Examples</a></li>
|
|
|
|
<li><a href="#grammar"><span class="secno">8. </span>Grammar</a></li>
|
|
|
|
<li><a href="#RCCComparison"><span class="secno">9. </span>Comparison of
|
|
sXBL to RCC</a></li>
|
|
|
|
<li><a href="#XBLComparison"><span class="secno">10. </span> Comparison of
|
|
sXBL to XBL1</a></li>
|
|
|
|
<li class="no-num"><a href="#acknowledgments">Acknowledgments</a></li>
|
|
|
|
<li class="no-num"><a href="#references">References</a></li>
|
|
</ul>
|
|
<!--end-toc-->
|
|
|
|
<hr />
|
|
|
|
<h2 id="introduction"><span class="secno">1. </span>Introduction</h2>
|
|
|
|
<p>This specification defines SVG's XML Binding Language (or XBL for short)
|
|
and some supporting DOM interfaces. sXBL is a mechanism for defining the
|
|
presentation and interactive behavior of particular elements described in
|
|
a namespace other than SVG's with a "binding". Bindings can be attached to
|
|
elements by declaring, in XBL, that a particular element in a particular
|
|
namespace is implemented by a particular binding. The element that the
|
|
binding is attached to, called the bound element, acquires the new
|
|
behavior and presentation specified by the binding.</p>
|
|
|
|
<p>XBL is currently defined as a set of new elements that can be used in
|
|
SVG document fragments and SVG resources. A future version may extend XBL
|
|
to be applicable to any markup, and the current version has been designed
|
|
with this goal in mind.</p>
|
|
|
|
<p>XBL cannot be used to give a document new semantics (except if script
|
|
invoked by XBL explicitly changes the original DOM). The meaning of a
|
|
document is not changed by any bindings that are associated with it, only
|
|
its presentation and interactive behavior.</p>
|
|
|
|
<div class="example">
|
|
<p>The following is a simple SVG example where a custom element
|
|
(<code><myNS:HelloWorld/></code>) acquires the alternate
|
|
presentation behavior defined by the <xbl:definition> element at
|
|
the top of the file. The <code><myNS:HelloWorld/></code> element
|
|
will be rendered by using the contents of the shadow tree which is
|
|
attached by the binding. The shadow tree consists of an
|
|
<code><svg:text></code> element which has the string "Hello, world,
|
|
using sXBL" inside:</p>
|
|
|
|
<pre><?xml version="1.0"?>
|
|
<svg width="10cm" height="3cm" viewBox="0 0 200 60"
|
|
xmlns="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl"
|
|
xmsns:myNS="http://www.example.com">
|
|
<title>Example xbl01.svg - "hello world" sample file</title>
|
|
<desc>A simple "Hello, world" sXBL example where the
|
|
rendering behavior of a custom element 'myNS:HelloWorld'
|
|
consists of an 'svg:text' element which has the string
|
|
"Hello, world, using sXBL" inside.</desc>
|
|
<defs>
|
|
|
|
<strong><xbl:xbl>
|
|
|
|
<!-- The following 'xbl:definition' element defines the
|
|
presentation and interactive behavior that must be used
|
|
for all 'myNS:HelloWorld' elements in this document. -->
|
|
<xbl:definition element="myNS:HelloWorld>
|
|
<xbl:template>
|
|
<text>Hello, world, using sXBL</text>
|
|
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
|
|
</xbl:xbl></strong>
|
|
</defs>
|
|
|
|
<rect x="1" y="1" width="198" height="58" fill="none" stroke="blue"/>
|
|
|
|
<g font-size="14" font-family="Verdana" transform="translate(10,35)">
|
|
|
|
<strong><!-- Here is an instance of an 'myNS:HelloWorld' element.
|
|
The above binding definition attaches a shadow tree which
|
|
defines alternative rendering and interactive behavior for this element.
|
|
Instead of the standard SVG behavior where unknown elements are not rendered,
|
|
the binding definition causes an 'svg:text' element to be rendered. -->
|
|
<myNS:HelloWorld/></strong>
|
|
|
|
</g>
|
|
|
|
</svg></pre>
|
|
|
|
<p>The above example results in equivalent rendering to the following SVG.
|
|
The highlighted sections below (i.e., the <code><g></code> and
|
|
<code><text></code> elements) represent the shadow tree which the
|
|
binding definition (i.e., the <code><xbl:definition></code> element
|
|
defined above) attaches to the custom element. The SVG user agent renders
|
|
the shadow tree in place of the custom element.</p>
|
|
|
|
<pre> <svg width="10cm" height="3cm" viewBox="0 0 200 60"
|
|
xmlns="http://www.w3.org/2000/svg" version="1.2">
|
|
|
|
<title>Example xbl01-equivalent.svg -
|
|
equivalent rendering for "hello world" sample file</title>
|
|
|
|
<rect x="1" y="1" width="198" height="58" fill="none" stroke="blue"/>
|
|
<g font-size="14" font-family="Verdana" transform="translate(10,35)">
|
|
|
|
<strong><!-- The document is rendered as if the 'myNS:HelloWorld' element
|
|
were replaced by an SVG 'g' element with a 'text' element inside. -->
|
|
<g>
|
|
|
|
<text>Hello, world, using sXBL</text>
|
|
</g></strong>
|
|
|
|
</g>
|
|
|
|
</svg></pre>
|
|
|
|
<p> <img alt="The result is as if the 'g' element simply contained the
|
|
text directly." src="images/examples/xbl01.png" /></p>
|
|
|
|
<p><a href="images/examples/xbl01.svg">View this image as SVG
|
|
(SVG/sXBL-enabled browsers only)</a></p>
|
|
</div>
|
|
|
|
<p>Other examples can be found in the <a href="#Examples">Examples</a>
|
|
section.</p>
|
|
|
|
<h3 id="history"><span class="secno">1.1. </span>History</h3>
|
|
|
|
<p>This specification is the culmination of several years of work by
|
|
several groups.</p>
|
|
|
|
<dl>
|
|
<dt><a href="http://www.w3.org/TR/NOTE-AS">Action Sheets A Modular Way of
|
|
Defining Behavior for XML and HTML</a> (AS)</dt>
|
|
|
|
<dd>Vidur Apparao, Brendan Eich, Ramanathan Guha, Nisheeth Ranjan;
|
|
Netscape Communications Corp. W3C Member Submission, June 1998.</dd>
|
|
|
|
<dt><a href="http://www.w3.org/TR/1998/NOTE-HTMLComponents-19981023">HTML
|
|
Components - Componentizing Web Applications</a> (HTCs)</dt>
|
|
|
|
<dd>Chris Wilson; Microsoft. W3C Member Submission, October 1998.</dd>
|
|
|
|
<dt><a href="http://www.w3.org/TR/1999/WD-becss-19990804">Behavioral
|
|
Extensions to CSS</a> (BECSS)</dt>
|
|
|
|
<dd>Vidur Apparao, Daniel Glazman, Chris Wilson; CSS Working Group. W3C
|
|
Working Draft, August 1999.</dd>
|
|
|
|
<dt><a href="http://www.w3.org/TR/2001/NOTE-xbl-20010223/">XBL - XML
|
|
Binding Language</a> (XBL)</dt>
|
|
|
|
<dd>David Hyatt; mozilla.org. W3C Member Submission, January 2001.</dd>
|
|
|
|
<dt><a href="http://www.w3.org/TR/2004/WD-SVG12-20040318/#rcc">Rendering
|
|
Custom Content</a> (RCC; part of some SVG 1.2 drafts)</dt>
|
|
|
|
<dd>Dean Jackson; SVG Working Group. W3C Working Draft, March 2004.</dd>
|
|
</dl>
|
|
|
|
<h3 id="terminology"><span class="secno">1.2. </span>Terminology and
|
|
Conventions</h3>
|
|
|
|
<p>A <dfn id="binding6" title="a binding">binding</dfn> is the definition
|
|
of behavior that can be applied to an element so as to define its
|
|
presentation.</p>
|
|
|
|
<p>An <dfn id="xbl-subtree">XBL subtree</dfn> is a subtree in an SVG
|
|
document fragment, the subtree having as its root
|
|
<!-- XXX better word than root? --> node an <code><a
|
|
href="#xbl0">xbl</a></code> element in the XBL namespace, which is used to
|
|
define bindings.</p>
|
|
|
|
<p>The term <dfn id="binding7">binding document</dfn> is used to mean a
|
|
document containing an SVG fragment that itself contains <span title="XBL
|
|
subtree"><a href="#xbl-subtree">XBL subtrees</a></span>.</p>
|
|
|
|
<p>A <dfn id="bound">bound element</dfn> is an element in an arbitrary XML
|
|
namespace, to which a binding has been applied.</p>
|
|
|
|
<p>A <dfn id="bound0">bound document</dfn> is a document containing an SVG
|
|
fragment with one or more bound elements.</p>
|
|
|
|
<p>The <dfn id="shadow3">shadow tree</dfn> for a bound element is the
|
|
subtree of nodes that are attached to a bound element as a result of XBL
|
|
processing. (See: <span><a href="#shadow6">shadow content</a></span>.) The
|
|
contents of the shadow tree augment the bound element's standard
|
|
presentation and interactive behavior with alternate behavior. The shadow
|
|
tree is hidden from normal DOM processing (hence the name "shadow"). The
|
|
shadow tree is attached to the bound element. Once attached, the shadow
|
|
tree can be accessed only via XBL-specific DOM extensions and therefore is
|
|
not accessible via Core DOM navigation facilities such as <code
|
|
class="dom">firstChild</code> or <code class="dom">nextSibling</code>.
|
|
(See: <span><a href="#dom-interfaces1">DOM interfaces</a></span>.)</p>
|
|
|
|
<p>The term <dfn id="shadow4">shadow content</dfn> refers to the various
|
|
nodes in the shadow tree of a bound element. Shadow content is created by
|
|
cloning a <span><a href="#shadow5">shadow content template</a></span>
|
|
during binding attachment. (See: <span><a href="#shadow6">shadow
|
|
content</a></span>.)</p>
|
|
|
|
<p>In this specification, the term <dfn id="in-error">in error</dfn>, when
|
|
used of an element or attribute, means that the element or attribute is
|
|
not conformant according to the rules of this specification.</p>
|
|
|
|
<p class="issue">JF has a <a
|
|
href="http://www.w3.org/2005/05/09-svg-irc#T16-17-14">pending action
|
|
item</a> (member only) to propose text for this section that defines the
|
|
conformance criteria for when a UA hits an error condition.</p>
|
|
|
|
<p>A <dfn id="correct" title="correct">correct element or attribute</dfn>
|
|
is one which is not <span><a href="#in-error">in error</a></span>.</p>
|
|
|
|
<p>The namespace of all the <dfn id="xbl-elements0">XBL elements</dfn> must
|
|
be: <code class="uri">http://www.w3.org/2004/xbl</code></p>
|
|
|
|
<p>XBL elements are frequently referred to by just their local name in this
|
|
specification. In real documents, they must be associated with the XBL
|
|
namespace as per the rules given in the Namespaces in XML specification <a
|
|
href="#refsXMLNS">[XMLNS]</a>.</p>
|
|
|
|
<p>For convenience, elements and attributes from specific namespaces are
|
|
sometimes referred to simply in the form <code>prefix:localname</code>,
|
|
without explicitly stating which namespace the prefix is bound to. When
|
|
this occurs, readers should assume the following prefix declarations are
|
|
in scope:</p>
|
|
|
|
<pre><!--xmlns="http://www.w3.org/2004/xbl"
|
|
-->xmlns:xbl="http://www.w3.org/2004/xbl"
|
|
xmlns:xforms="http://www.w3.org/2002/xforms"
|
|
xmlns:ev="http://www.w3.org/2001/xml-events"
|
|
xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"</pre>
|
|
|
|
<p>All element names, attribute names, and attribute values in XBL are case
|
|
sensitive.</p>
|
|
|
|
<h3 id="conformance"><span class="secno">1.3. </span>Conformance</h3>
|
|
|
|
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
|
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
|
|
document are to be interpreted as described in <a
|
|
href="#refsRFC2119">[RFC2119]</a>. For readability, these words are not
|
|
capitalised in this specification.</p>
|
|
|
|
<p>All sections of this specification including the introduction and the
|
|
schema snippets are normative unless they explicitly state otherwise.
|
|
Errata are also normative but override conflicting parts of the
|
|
specification.</p>
|
|
|
|
<h3 id="loading"><span class="secno">1.4. </span><dfn id="loading1">Loading
|
|
External Resources</dfn></h3>
|
|
|
|
<p class="issue"> JF has a pending action item to propose text for this
|
|
section (<a
|
|
href="http://lists.w3.org/Archives/Member/member-binding-tf/2004OctDec/0025.html">minutes</a>,
|
|
member only) to point to <a
|
|
href="http://www.w3.org/TR/2004/WD-SVG12-20041027/nonvisual.html#external-references">17.1
|
|
Externally referenced documents</a>.</p>
|
|
|
|
<p>Several features in XBL allow external resources to be loaded.</p>
|
|
|
|
<p>When the specification says that the resource must be loaded <em>unless
|
|
it has already been loaded</em>, then references to the same resource
|
|
(even if they are somewhat indirect, for example via HTTP redirects) must
|
|
result in the same instance being reused, or shared. To determine if two
|
|
resources are the same, their final base URIs (after all redirects) are
|
|
compared.</p>
|
|
|
|
<div class="example">
|
|
<p>Assume RX is a resource that redirects to resource X using the HTTP 301
|
|
redirection mechanism. A document contains an <code><a
|
|
href="#import0">import</a></code> element that refers to binding document
|
|
X. A new DOM <code>Document</code> instance is created to represent that
|
|
instance and the relevant bindings are used. The binding document (X)
|
|
itself then refers to resource RX. While that resource was being loaded,
|
|
the redirect to X would be discovered, and therefore instead of creating
|
|
a new <code>Document</code>, the existing one would be reused.</p>
|
|
|
|
</div>
|
|
|
|
<p>Such resource sharing is limited to resources loaded by a document, and
|
|
the resources loaded by already-loaded-shared-resources for that document.
|
|
<span class="issue">Can we phrase that better? The idea is that two
|
|
IFRAMEs whose documents use the same resource should NOT share that
|
|
resource.</span> <span class="issue">We may also want to be explicit than
|
|
resources that are currently loading count as resources that are already
|
|
loaded...</span></p>
|
|
|
|
<p>Several XBL attributes are defined to contain URIs. All URIs may be
|
|
relative. For relative URIs, the rules given in <a
|
|
href="#refsXMLBASE">[XMLBASE]</a> must be used to resolve the value to an
|
|
absolute URI.</p>
|
|
|
|
<h2 id="xbl-elements"><span class="secno">2. </span>XBL Elements</h2>
|
|
|
|
<p>The start of any XBL subtree is an <code><a href="#xbl0">xbl</a></code>
|
|
element, which is described below.</p>
|
|
|
|
<p>When an XBL subtree does not conform to the descriptions given below in
|
|
the "Expected context" and "Expected children" sections, the document is
|
|
<span><a href="#in-error">in error</a></span>.</p>
|
|
|
|
<h3 id="the-xbl"><span class="secno">2.1. </span>The <dfn
|
|
id="xbl0">xbl</dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>RelaxNG language definition:</dt>
|
|
|
|
<dd>
|
|
|
|
<pre class="schema"><element name='xbl'>
|
|
<zeroOrMore><ref name='definition'/></zeroOrMore>
|
|
<zeroOrMore><ref name='import'/></zeroOrMore>
|
|
<ref name='id.attrib'/>
|
|
</element></pre>
|
|
|
|
</dd>
|
|
|
|
<dt>Expected children (in any order):</dt>
|
|
|
|
<dd><code><a href="#definition0">definition</a></code>: zero or more.</dd>
|
|
|
|
<dd><code><a href="#import0">import</a></code>: zero or more.</dd>
|
|
|
|
<dd>Any non-XBL element.</dd>
|
|
</dl>
|
|
|
|
<p>The <code><a href="#xbl0">xbl</a></code> element is the root element of
|
|
all XBL subtrees.</p>
|
|
|
|
<div class="example">
|
|
<p>The following example shows an SVG example with an <code><a
|
|
href="#xbl0">xbl</a></code> element which contains two binding
|
|
definitions. It also shows an example of an <code>svg:defs</code>
|
|
|
|
element.</p>
|
|
|
|
<pre>
|
|
<svg:svg xmlns:svg="http://www.w3.org/2000/svg" version="1.2">
|
|
<xbl xmlns="http://www.w3.org/2004/xbl">
|
|
<svg:defs>
|
|
<!-- possible definitions of SVG gradients, filters, etc.
|
|
that might be referenced from the binding definitions. -- >
|
|
|
|
</svg:defs>
|
|
<definition id="binding1" element="example">
|
|
...
|
|
</definition>
|
|
<definition id="binding2">
|
|
...
|
|
</definition>
|
|
|
|
</xbl>
|
|
</svg:svg>
|
|
</pre>
|
|
</div>
|
|
|
|
<h4 class="no-toc no-num" id="attributes">Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id="id0" title="attr-xbl-id">id</dfn></dt>
|
|
|
|
<dd>The <span title="attr-id"><a href="#id6"><code>id</code>
|
|
attribute</a></span>.</dd>
|
|
</dl>
|
|
|
|
<p>UAs must consider any <code><a href="#xbl0">xbl</a></code> elements that
|
|
have another <code><a href="#xbl0">xbl</a></code> element as an ancestor
|
|
as being <span><a href="#in-error">in error</a></span> and must then
|
|
<span>ignore</span> them, meaning those elements must never be considered
|
|
to declare any bindings. For example, UAs must never bind elements to
|
|
bindings defined by <code><a href="#definition0">definition</a></code>
|
|
|
|
elements that have two <code><a href="#xbl0">xbl</a></code> ancestors.</p>
|
|
|
|
<h3 id="the-definition"><span class="secno">2.2. </span>The <dfn
|
|
id="definition0">definition</dfn> Element</h3>
|
|
|
|
<dl>
|
|
|
|
<dt>RelaxNG language definition:</dt>
|
|
|
|
<dd>
|
|
<pre class="schema"><element name='definition'>
|
|
<choice>
|
|
<attribute name='ref'><data type='anyURI'/></attribute>
|
|
|
|
<group>
|
|
<optional><ref name='template'/></optional>
|
|
<optional><ref name='handlerGroup'/></optional>
|
|
<attribute name='element'><data type='QName'/></attribute>
|
|
|
|
</group>
|
|
</choice>
|
|
<ref name='id.attrib'/>
|
|
</element></pre>
|
|
</dd>
|
|
|
|
<dt>Expected context:</dt>
|
|
|
|
<dd><code><a href="#xbl0">xbl</a></code></dd>
|
|
|
|
<dt>Expected children (in any order), if the <code
|
|
title="attr-definition-ref"><a href="#ref">ref</a></code> attribute is
|
|
not specified:</dt>
|
|
|
|
<dd><code><a href="#template0">template</a></code>: zero or one.</dd>
|
|
|
|
<dd><code><a href="#handlergroup0">handlerGroup</a></code>: zero or one.</dd>
|
|
|
|
<dd>Any non-XBL element</dd>
|
|
|
|
<dt>Expected children (in any order), if the <code
|
|
title="attr-definition-ref"><a href="#ref">ref</a></code> attribute
|
|
<em>is</em> specified:</dt>
|
|
|
|
<dd>None.</dd>
|
|
</dl>
|
|
|
|
<p>The <code><a href="#definition0">definition</a></code> element describes
|
|
a single XBL binding that adds presentation and interactive behavior to
|
|
non-SVG elements. Each binding has these optional components:</p>
|
|
|
|
<p><em><a href="#template0">Template</a></em>: The optional <code><a
|
|
href="#template0">template</a></code> defines the initial <em><a
|
|
href="#shadow6">shadow content</a></em> for the bound element.</p>
|
|
|
|
<p><em title="handlerGroup"><a href="#handlergroup0">Behavior</a></em>: A
|
|
binding can define event listeners for various types of events. Some
|
|
examples are: UI events (e.g., key and mouse events) on the bound element
|
|
or on elements within the shadow content; mutation events on the bound
|
|
element and its descendants; and events having to do with XBL's binding
|
|
operations (e.g., the <code class="dom"><a
|
|
href="#prebind">prebind</a></code> and <code class="dom"><a
|
|
href="#bound1">bound</a></code> events). (See: <span><a
|
|
href="#event5">event handlers</a></span>.)</p>
|
|
|
|
<p>Alternatively, a binding may reference an existing binding, with the
|
|
<code title="attr-definition-ref"><a href="#ref">ref</a></code> attribute.
|
|
In this case, the <code title="attr-definition-ref"><a
|
|
href="#ref">ref</a></code> attribute must reference a <code><a
|
|
href="#definition0">definition</a></code> element which in turn supplies
|
|
the binding definition.</p>
|
|
|
|
<p>Bindings may also act as an attachment mechanism, specifying a namespace
|
|
and local name of elements to associate with the given binding when the
|
|
binding is <span title="importing">imported</span>, using the <code
|
|
title="attr-definition-element"><a href="#element">element</a></code>
|
|
attribute.</p>
|
|
|
|
<p>In addition to the above, the <code><a
|
|
href="#definition0">definition</a></code> element may contain any element
|
|
outside the XBL namespace, for example <code>svg:defs</code>. These are
|
|
handled as they would be in any other context, and are ignored by the XBL
|
|
processing model.</p>
|
|
|
|
<h4 class="no-toc no-num" id="attributes0">Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id="id1" title="attr-definition-id">id</dfn></dt>
|
|
|
|
<dd>The <span title="attr-id"><a href="#id6"><code>id</code>
|
|
attribute</a></span>.</dd>
|
|
|
|
<dt><dfn id="ref" title="attr-definition-ref">ref</dfn></dt>
|
|
|
|
<dd>
|
|
<p>This attribute specifies a URI to use to find the binding instead of
|
|
looking inside the <code><a href="#definition0">definition</a></code>
|
|
element itself. (See: <span><a href="#interpretation1">interpretation of
|
|
URIs to XBL bindings</a></span>.)</p>
|
|
|
|
<p>When a <code><a href="#definition0">definition</a></code> element has
|
|
a <code title="attr-definition-ref"><a href="#ref">ref</a></code>
|
|
attribute, the UA must fetch the specified resource (unless it has <span
|
|
title="loading external resources"><a href="#loading1">already been
|
|
loaded</a></span>).</p>
|
|
|
|
<p>If the URI references a <code><a
|
|
href="#definition0">definition</a></code> element, and that element does
|
|
not have a <code title="attr-definition-ref"><a
|
|
href="#ref">ref</a></code> attribute, then for the purposes of the rest
|
|
of the XBL processing model, the element with the <code
|
|
title="attr-definition-ref"><a href="#ref">ref</a></code> attribute is
|
|
treated as if it had the children nodes of the element to which it
|
|
refers.</p>
|
|
|
|
<p>If the URI does not reference a <code><a
|
|
href="#definition0">definition</a></code> element, it is <span><a
|
|
href="#in-error">in error</a></span>.</p>
|
|
|
|
<p>The referenced <code><a href="#definition0">definition</a></code>
|
|
element cannot have a <code title="attr-definition-ref"><a
|
|
href="#ref">ref</a></code> attribute (i.e., only one level of
|
|
indirection is allowed); otherwise, the original <code><a
|
|
href="#definition0">definition</a></code> element is <span><a
|
|
href="#in-error">in error</a></span>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="element" title="attr-definition-element">element</dfn></dt>
|
|
|
|
<dd>This attribute specifies the qualified name (QName) of an element to
|
|
attach to the binding when the binding is <span
|
|
title="importing">imported</span>.
|
|
<p>If an <code title="attr-definition-element"><a
|
|
href="#element">element</a></code> attribute does not resolve to a valid
|
|
qualified name (QName) using the attribute QName resolving semantics and
|
|
the namespace prefix declarations in scope on the element, it is
|
|
<span><a href="#in-error">in error</a></span>. <a
|
|
href="#refsXMLNS">[XMLNS]</a></p>
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>If a <code><a href="#definition0">definition</a></code> element contains
|
|
both a <code title="attr-definition-ref"><a href="#ref">ref</a></code>
|
|
attribute and has child nodes other than comment nodes or whitespace text
|
|
nodes, then it is <span><a href="#in-error">in error</a></span>.</p>
|
|
|
|
<div class="issue">The task force believes that a sentence equivalent to
|
|
the following note needs to be somewhere in the spec, so that people don't
|
|
think XBL can be used as a justification for sending markup over the wire
|
|
without verifying that the sender and consumer both agree on the meaning
|
|
of the markup. It was generally agreed that the word "semantics" might be
|
|
better avoided while expressing this concept, however, and so this text is
|
|
not yet final.</div>
|
|
|
|
<p class="note">The <code><a href="#definition0">definition</a></code>
|
|
element defines a presentation and behavior binding. It does not define an
|
|
element's semantics. If an element has no semantics when processed alone,
|
|
then it has no semantics when processed with XBL.</p>
|
|
|
|
<h3 id="the-template"><span class="secno">2.3. </span>The <dfn
|
|
id="template0">template</dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>RelaxNG language definition:</dt>
|
|
|
|
<dd>
|
|
<pre class="schema"><element name='template'>
|
|
<ref name='id.attrib'/>
|
|
</element></pre>
|
|
|
|
</dd>
|
|
|
|
<dt>Expected context:</dt>
|
|
|
|
<dd><code><a href="#definition0">definition</a></code></dd>
|
|
|
|
<dt>Expected children:</dt>
|
|
|
|
<dd>Anything. Of particular interest, the <code><a
|
|
href="#content0">content</a></code> element may occur as descendants.</dd>
|
|
|
|
</dl>
|
|
|
|
<p>The <code><a href="#template0">template</a></code> element contains
|
|
child nodes that can be in any namespace. The subtree specified by the
|
|
<code><a href="#template0">template</a></code> element is referred to as
|
|
the <dfn id="shadow5">shadow content template</dfn>. When a binding is
|
|
attached, the <code><a href="#template0">template</a></code> element's
|
|
child nodes are cloned and attached to the bound document under the bound
|
|
element (where they are accessible via the <code class="dom"><a
|
|
href="#xblshadowtree">xblShadowTree</a></code> DOM property). Because
|
|
these cloned nodes are hidden from their parent and exist outside the
|
|
normal document tree, they are referred to as <span><a
|
|
href="#shadow6">shadow content</a></span>.</p>
|
|
|
|
<p>When the <code><a href="#template0">template</a></code> element is
|
|
cloned, it is renamed to <code><a
|
|
href="#shadowtree">shadowTree</a></code>. (See: <span><a
|
|
href="#rules1">rules for shadow content generation</a></span>.)</p>
|
|
|
|
<h4 class="no-toc no-num" id="attributes1">Attributes</h4>
|
|
|
|
<dl>
|
|
|
|
<dt><dfn id="id2" title="attr-template-id">id</dfn></dt>
|
|
|
|
<dd>The <span title="attr-id"><a href="#id6"><code>id</code>
|
|
attribute</a></span>.</dd>
|
|
</dl>
|
|
|
|
<h3 id="the-content"><span class="secno">2.4. </span>The <dfn
|
|
id="content0">content</dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>RelaxNG language definition:</dt>
|
|
|
|
<dd>
|
|
<pre class="schema"><element name='content'>
|
|
<optional><attribute name='includes'><text/></attribute></optional>
|
|
|
|
<ref name='id.attrib'/>
|
|
</element></pre>
|
|
</dd>
|
|
|
|
<dt>Expected context:</dt>
|
|
|
|
<dd>Any, but there must be a correct <code><a
|
|
href="#template0">template</a></code> element somewhere in the ancestor
|
|
chain, and there must not be any correct <code><a
|
|
href="#content0">content</a></code> elements anywhere in the ancestor
|
|
chain.</dd>
|
|
|
|
<dt>Expected children:</dt>
|
|
|
|
<dd>Anything.</dd>
|
|
</dl>
|
|
|
|
<p>The <code><a href="#content0">content</a></code> element is used inside
|
|
<span><a href="#shadow6">shadow content</a></span> to specify insertion
|
|
points for explicit content that might already exist underneath the bound
|
|
element. As far as the presentation model is concerned, any shadow content
|
|
the binding places between the bound element and the <code><a
|
|
href="#content0">content</a></code> elements is interleaved between the
|
|
bound element and its explicit children without affecting the document
|
|
model. (See: <span><a href="#processing1">processing <code
|
|
title="">content</code> elements</a></span>.)</p>
|
|
|
|
<p>If the <code>includes</code> attribute successfully matches against
|
|
children of the bound element, then those children are inserted into the
|
|
<span><a href="#final">final flattened tree</a></span> in place of the
|
|
<code><a href="#content0">content</a></code> element. If the
|
|
<code>includes</code> attribute does not match against any children, then
|
|
the child elements of the <code><a href="#content0">content</a></code>
|
|
|
|
element are inserted into the <span><a href="#final">final flattened
|
|
tree</a></span> in place of the <code><a
|
|
href="#content0">content</a></code> element instead.</p>
|
|
|
|
<h4 class="no-toc no-num" id="attributes2">Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id="id3" title="attr-content-id">id</dfn></dt>
|
|
|
|
<dd>The <span title="attr-id"><a href="#id6"><code>id</code>
|
|
attribute</a></span>.</dd>
|
|
|
|
<dt><dfn id="includes" title="attr-content-includes">includes</dfn></dt>
|
|
|
|
<dd>The <code title="attr-content-includes"><a
|
|
href="#includes">includes</a></code> attribute can be used to indicate
|
|
that only certain content should be placed at the <code><a
|
|
href="#content0">content</a></code> element. Its value is a local name
|
|
(with no namespace). (See: <span><a href="#processing1">processing <code
|
|
title="">content</code> elements</a></span>.)</dd>
|
|
|
|
</dl>
|
|
|
|
<h3 id="the-handlergroup"><span class="secno">2.5. </span>The <dfn
|
|
id="handlergroup0">handlerGroup</dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>RelaxNG language definition:</dt>
|
|
|
|
<dd>
|
|
<pre class="schema"><element name='handlerGroup'>
|
|
|
|
<!-- the content model for this element mentions ev:listener and svg:handler
|
|
but is rather unclear as to what should be included here -->
|
|
|
|
<ref name='id.attrib'/>
|
|
</element></pre>
|
|
</dd>
|
|
|
|
<dt>Expected context:</dt>
|
|
|
|
<dd><code><a href="#definition0">definition</a></code></dd>
|
|
|
|
<dt>Expected children:</dt>
|
|
|
|
<dd>Any event listening element, in particular <code>ev:listener</code>
|
|
|
|
and <code>svg:handler</code>.</dd>
|
|
</dl>
|
|
|
|
<p>The <code><a href="#handlergroup0">handlerGroup</a></code> element's
|
|
event handlers can be called for events that flow through the bound
|
|
element. During capture, target and bubbling phases, when a given event is
|
|
received by a bound element, if a corresponding event listener has been
|
|
attached to the <code><a href="#handlergroup0">handlerGroup</a></code>
|
|
element, then the event will be <span title="event forwarding"><a
|
|
href="#event6">forwarded</a></span> to that event listener. (See: <span><a
|
|
href="#event6">event forwarding</a></span>, <span><a
|
|
href="#binding8">binding attachment and detachment</a></span>.)</p>
|
|
|
|
<h4 class="no-toc no-num" id="attributes3">Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id="id4" title="attr-handlerGroup-id">id</dfn></dt>
|
|
|
|
<dd>The <span title="attr-id"><a href="#id6"><code>id</code>
|
|
attribute</a></span>.</dd>
|
|
|
|
</dl>
|
|
|
|
<h3 id="the-import"><span class="secno">2.6. </span>The <dfn
|
|
id="import0">import</dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>RelaxNG language definition:</dt>
|
|
|
|
<dd>
|
|
<pre class="schema"><element name='import'>
|
|
<optional><attribute name='bindings'><data type='anyURI'/></attribute></optional>
|
|
<ref name='id.attrib'/>
|
|
</element></pre>
|
|
|
|
</dd>
|
|
|
|
<dt>Expected contexts:</dt>
|
|
<!--
|
|
<dd>The <code>xbl</code> element.</dd>
|
|
<dd>The <code>svg:svg</code> element.</dd>
|
|
<dd>The <code>html:head</code> element.</dd>
|
|
<dd>The root element.</dd>
|
|
-->
|
|
|
|
<dd>Any, but the ancestors must all be <span><a
|
|
href="#correct">correct</a></span>.</dd>
|
|
|
|
<dt>Expected children:</dt>
|
|
|
|
<dd>None.</dd>
|
|
</dl>
|
|
|
|
<p>The <code><a href="#import0">import</a></code> element specifies a group
|
|
of bindings to use. Unless explicitly imported using an <code><a
|
|
href="#import0">import</a></code> element, binding definitions that
|
|
declare attachments using the <code title="attr-definition-element"><a
|
|
href="#element">element</a></code> attribute are only used in the document
|
|
that defines them.</p>
|
|
|
|
<p>The <code><a href="#import0">import</a></code> element may occur
|
|
anywhere, within and without <span title="XBL subtree"><a
|
|
href="#xbl-subtree">XBL subtrees</a></span>.</p>
|
|
|
|
<h4 class="no-toc no-num" id="attributes4">Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id="id5" title="attr-import-id">id</dfn></dt>
|
|
|
|
<dd>The <span title="attr-id"><a href="#id6"><code>id</code>
|
|
attribute</a></span>.</dd>
|
|
|
|
<dt><dfn id="bindings" title="attr-xbl-import-bindings">bindings</dfn></dt>
|
|
|
|
<dd>
|
|
<p>The <code title="attr-import-bindings">bindings</code> attribute
|
|
specifies the URI of the bindings to import. If it has a fragment
|
|
identifier it specifies the subpart of the specified resource to examine
|
|
for binding attachment declarations. This attribute is required. If it
|
|
is omitted, the element is <span><a href="#in-error">in
|
|
error</a></span>.</p>
|
|
|
|
<p>The URI must point to an SVG document. If the URI designated by an
|
|
<code><a href="#import0">import</a></code> element has a fragment
|
|
identifier, it must point to an <code><a href="#xbl0">xbl</a></code>
|
|
element in the specified document. If it does not, the element is in
|
|
error.</p>
|
|
|
|
<p>If the URI designated by an <code><a href="#import0">import</a></code>
|
|
element cannot be resolved, or returns an HTTP 404 error (or
|
|
equivalent), or does not point to a resource with an
|
|
<code>image/svg+xml</code> MIME type, or has any other problem that
|
|
makes it unusable, then the element is in error.</p>
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>When an <code><a href="#import0">import</a></code> element is parsed or
|
|
inserted into a document, and whenever the <code
|
|
title="attr-import-bindings">bindings</code> attribute is subseqently
|
|
changed, the URI specified by its <code
|
|
title="attr-import-bindings">bindings</code> attribute must be loaded
|
|
(unless it has <span title="loading external resources"><a
|
|
href="#loading1">already been loaded</a></span>).</p>
|
|
|
|
<p>If the URI designated by an <code><a href="#import0">import</a></code>
|
|
element cannot be resolved, or returns an HTTP 404 error, or does not
|
|
point to a resource with an XML MIME type, or has any other problem that
|
|
makes it unusable, then the element is <span><a href="#in-error">in
|
|
error</a></span>.</p>
|
|
|
|
<p>While the <code><a href="#import0">import</a></code> element remains in
|
|
the document, all the bindings that it imports and that specify an
|
|
attachment must be attached to any matching elements that have the same
|
|
<code>ownerDocument</code> as the <code><a
|
|
href="#import0">import</a></code> element. (See: <span title="binding
|
|
attachment and detachment"><a href="#binding8">binding
|
|
attachment</a></span>.)</p>
|
|
|
|
<p>If there is a fragment identifier, it imports all the <code><a
|
|
href="#definition0">definition</a></code> elements in the subtree
|
|
designated by that fragment identifier. Otherwise, it imports all the
|
|
<code><a href="#definition0">definition</a></code> elements in the
|
|
<span><a href="#binding7">binding document</a></span>.</p>
|
|
|
|
<p>An import is <em>live</em>, if new <code><a
|
|
href="#definition0">definition</a></code> elements are added to a subtree
|
|
that is being imported by a document, then the new bindings are
|
|
immediately applied to that document. Similarly, if an <code><a
|
|
href="#import0">import</a></code> element is removed, or if the <code
|
|
title="attr-import-bindings">bindings</code> attribute is changed, then
|
|
the bindings it was importing are detached from any elements they were
|
|
affecting.</p>
|
|
|
|
<p>XBL bindings are always implicitly imported into the document in which
|
|
they are defined.</p>
|
|
|
|
<div class="example">
|
|
<p>An XBL subtree that defines some bindings is automatically imported in
|
|
that document, so such mappings are always used. The following example
|
|
demonstrates this.</p>
|
|
|
|
<pre><strong>example.svg</strong>
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" ...>
|
|
|
|
<xbl xmlns="http://www.w3.org/2004/xbl" ...>
|
|
<definition element="foo">
|
|
...
|
|
<definition>
|
|
<definition element="bar">
|
|
...
|
|
<definition>
|
|
|
|
</xbl ...>
|
|
<foo xmlns=""/> <!-- this will have a binding applied -->
|
|
<bar xmlns=""/> <!-- this will have a binding applied -->
|
|
</svg>
|
|
</pre>
|
|
|
|
<p>If the binding definitions are in a separate file, then that file needs
|
|
to be imported explicitly:</p>
|
|
|
|
<pre><strong>widgets.svg</strong>
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" ...>
|
|
<xbl xmlns="http://www.w3.org/2004/xbl" ...>
|
|
<definition element="foo">
|
|
...
|
|
<definition>
|
|
|
|
<definition element="bar">
|
|
...
|
|
<definition>
|
|
</xbl ...>
|
|
</svg>
|
|
</pre>
|
|
|
|
<pre><strong>example.svg</strong>
|
|
|
|
<svg:svg ...
|
|
xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl">
|
|
<em><xbl:import bindings="widgets.svg"/></em>
|
|
<foo/> <!-- bound -->
|
|
<bar/> <!-- bound -->
|
|
</svg:svg>
|
|
|
|
</pre>
|
|
|
|
<p>If a file imports a specific binding but the file containing that
|
|
binding has its own <code><a href="#import0">import</a></code> elements,
|
|
the second import only affects nodes in that document. For example:</p>
|
|
|
|
<pre><strong>foo.svg</strong>
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" ...>
|
|
<xbl xmlns="http://www.w3.org/2004/xbl" ...>
|
|
|
|
<definition element="foo" id="foo">
|
|
<content>
|
|
<bar xmlns=""/> <!-- not bound, not even when in shadow content -->
|
|
</content>
|
|
<definition>
|
|
|
|
</xbl>
|
|
</svg>
|
|
</pre>
|
|
|
|
<pre><strong>bar.svg</strong>
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" ...>
|
|
<xbl id="bindings" xmlns="http://www.w3.org/2004/xbl" ...>
|
|
<definition element="bar" id="bar">
|
|
|
|
<content>
|
|
<foo xmlns=""/> <!-- bound: this document imports foo.svg -->
|
|
<bar xmlns=""/> <!-- bound: bar binding is defined locally -->
|
|
</content>
|
|
<definition>
|
|
|
|
</xbl>
|
|
<import bindings="foo.svg" xmlns="http://www.w3.org/2004/xbl"/>
|
|
</svg>
|
|
</pre>
|
|
|
|
<pre><strong>example.svg</strong>
|
|
|
|
<svg:svg ...
|
|
xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl">
|
|
<xbl:import bindings="bar.svg#bindings"/>
|
|
|
|
<foo/> <!-- not bound: foo.svg not imported here -->
|
|
<bar/> <!-- bound -->
|
|
</svg:svg>
|
|
</pre>
|
|
</div>
|
|
|
|
<h3 id="the-id"><span class="secno">2.7. </span>The <dfn id="id6"
|
|
title="attr-id">id</dfn> attribute of XBL elements</h3>
|
|
|
|
<dl>
|
|
<dt>RelaxNG language definition:</dt>
|
|
|
|
<dd>
|
|
<pre class="schema"><define name='id.attrib'>
|
|
<optional>
|
|
<attribute name='id'>
|
|
|
|
<data type='ID'/>
|
|
</attribute>
|
|
</optional>
|
|
</define></pre>
|
|
</dd>
|
|
|
|
<dt>Expected element:</dt>
|
|
|
|
<dd>Any element in the XBL namespace.</dd>
|
|
</dl>
|
|
|
|
<p>The <code title="attr-id"><a href="#id6">id</a></code> attribute assigns
|
|
a name to an element. This name must be unique in the document. The <code
|
|
title="attr-id"><a href="#id6">id</a></code> attribute is of type ID.
|
|
Refer to the "Extensible Markup Language (XML)" Recommendation <a
|
|
href="#refsXML">[XML]</a>.</p>
|
|
|
|
<p>An <code title="attr-id"><a href="#id6">id</a></code> attribute's value
|
|
must be valid, as defined by XML. (See XML 1.0, <a
|
|
href="http://www.w3.org/TR/REC-xml/#id">section 3.3.1</a>.)</p>
|
|
|
|
<p class="issue">What does it mean to require that the ID attribute must be
|
|
valid? Does it mean "must match XML's Name production"? What if it isn't?
|
|
Does it put it in error? If it is in error, what happens; is that covered
|
|
by our new "in error" handling text?</p>
|
|
|
|
<h2 id="binding"><span class="secno">3. </span><dfn id="binding8">Binding
|
|
Attachment and Detachment</dfn></h2>
|
|
|
|
<p>Bindings shall be attached as soon as the following conditions have been
|
|
met: (a) it is known that the element is bound to the given binding (b)
|
|
the element has been created and (c) the binding has loaded.</p>
|
|
|
|
<h3 id="interpretation"><span class="secno">3.1. </span><dfn
|
|
id="interpretation1">Interpretation of URIs to XBL bindings</dfn></h3>
|
|
|
|
<p>The sXBL attachment mechanism can use a URI to specify which binding to
|
|
attach to the designated element:</p>
|
|
|
|
<pre class="example"><definition element="my:foo"
|
|
ref="<strong>http://www.example.org/bindings.xml#fooBinding</strong>"/></pre>
|
|
|
|
<p>This section defines how URIs in the <code><a
|
|
href="#definition0">definition</a></code> element's <code
|
|
title="attr-definition-ref"><a href="#ref">ref</a></code> attribute are to
|
|
be interpreted.</p>
|
|
|
|
<p>The URI specifies a particular <span><a href="#binding7">binding
|
|
document</a></span> (a document with SVG fragments containing one or more
|
|
XBL subtrees).</p>
|
|
|
|
<p>If the URI contains a fragment identifier, it must point to a specific
|
|
<code><a href="#definition0">definition</a></code> element (by <code
|
|
title="attr-id"><a href="#id6">id</a></code>) within an XBL subtree in the
|
|
specified document, and that element must be a direct child of an <code><a
|
|
href="#xbl0">xbl</a></code> element that does not itself have an <code><a
|
|
href="#xbl0">xbl</a></code> element as an ancestor.</p>
|
|
|
|
<p>If there is no fragment identifier the URI does not point to a correct
|
|
binding and is <span><a href="#in-error">in error</a></span>.</p>
|
|
|
|
<h3 id="attachment"><span class="secno">3.2. </span><dfn id="attachment1"
|
|
title="attachment using bind">Attachment using
|
|
<code>definition</code></dfn></h3>
|
|
|
|
<p>The binding mechanism is the <code><a
|
|
href="#definition0">definition</a></code> element. It declares which
|
|
bindings should be attached to which elements.</p>
|
|
|
|
<p>While an element matches the <code title="attr-definition-element"><a
|
|
href="#element">element</a></code> attribute of one of the <code><a
|
|
href="#definition0">definition</a></code> elements that is <span
|
|
title="import"><a href="#import0">imported</a></span> into, or defined in,
|
|
the element's document, the binding defined by the first such <code><a
|
|
href="#definition0">definition</a></code> element must be bound to the
|
|
element.</p>
|
|
|
|
<p>A <code title="attr-definition-ref"><a href="#ref">ref</a></code>
|
|
attribute may be used to defer the definition of the binding to another
|
|
<code><a href="#definition0">definition</a></code> element. (See: <span
|
|
title="definition"><a href="#definition0">the definition
|
|
element</a></span>.)</p>
|
|
|
|
<h3 id="binding0"><span class="secno">3.3. </span><dfn
|
|
id="binding9">Binding Attachment Model</dfn></h3>
|
|
|
|
<p>When a new binding is attached, the UA must perform the following steps
|
|
in order (or act as if it did). Implementations may choose to suspend
|
|
redraw during this process.</p>
|
|
|
|
<ol>
|
|
<li>Events must start being routed through the binding's <code><a
|
|
href="#handlergroup0">handlerGroup</a></code> element, when there is one.
|
|
(See: <span><a href="#event6">event forwarding</a></span>.)</li>
|
|
|
|
<li> The <span><a href="#shadow5">shadow content template</a></span> is
|
|
then cloned, if needed, to create the <span><a href="#shadow3">shadow
|
|
tree</a></span>:
|
|
<ol>
|
|
|
|
<li>If the new binding has a shadow content template, then a new shadow
|
|
tree is created. The <code class="dom"><a
|
|
href="#prebind">prebind</a></code> event is fired before it is
|
|
attached. (See: <span><a href="#rules1">rules for shadow content
|
|
generation</a></span>.)</li>
|
|
|
|
<li>Otherwise, if the binding has no shadow tree, a <code class="dom"><a
|
|
href="#prebind">prebind</a></code> event in the XBL namespace that
|
|
bubbles but is not cancelable is fired on the bound element.</li>
|
|
</ol>
|
|
|
|
</li>
|
|
|
|
<li>Any bindings of descendants that are not yet attached, are then
|
|
attached.</li>
|
|
|
|
<li>Once all the bindings of any descendent elements are attached, a <code
|
|
class="dom"><a href="#bound1">bound</a></code> event in the XBL namespace
|
|
that bubbles but is not cancelable is fired on the bound element.</li>
|
|
</ol>
|
|
|
|
<p class="issue">We need to decide how to handle the case where a binding's
|
|
<code><a href="#definition0">definition</a></code> is removed while it is
|
|
being attached.</p>
|
|
|
|
<!--
|
|
What should happen if a binding is detached while it's in the middle of the
|
|
attachment process (for example, say the prebind event handling removes some
|
|
<xbl:import> nodes from the document)? Or the prebind or bound events on its
|
|
descendants cause the binding to be detached before its bound event would have
|
|
fired?
|
|
-->
|
|
|
|
<h3 id="binding1"><span class="secno">3.4. </span>Binding Detachment Model</h3>
|
|
|
|
<p>Before a binding is detached, an <code class="dom"><a
|
|
href="#unbinding">unbinding</a></code> event in the XBL namespace that
|
|
bubbles but is not cancelable is fired on the bound element.</p>
|
|
|
|
<p>The shadow content nodes, the shadow tree, any forwarding of events to
|
|
the binding, etc, are then removed from the element.</p>
|
|
|
|
<h3 id="summary"><span class="secno">3.5. </span>Summary of Events</h3>
|
|
|
|
<p>The following events are fired during attachment and detachment:</p>
|
|
|
|
<dl>
|
|
<dt>{"http://www.w3.org/2004/xbl", "<dfn id="prebind">prebind</dfn>"}</dt>
|
|
|
|
<dd>A new binding is in the process of being attached to the event target.
|
|
This event is fired after the contents of the <code><a
|
|
href="#template0">template</a></code> element, if any, have been cloned
|
|
but before attachment to the bound element's <code><a
|
|
href="#xblshadowtree">xblShadowTree</a></code> and recursive XBL
|
|
processing on shadow tree contents. (See: <span><a
|
|
href="#binding9">binding attachment model</a></span>.)</dd>
|
|
|
|
<dt>{"http://www.w3.org/2004/xbl", "<dfn id="bound1">bound</dfn>"}</dt>
|
|
|
|
<dd>A new binding has been attached to the event target, and all of its
|
|
descendants in the <span><a href="#final">final flattened tree</a></span>
|
|
for which bindings are to be applied have had the <code><a
|
|
href="#bound1">bound</a></code> event fired on them.</dd>
|
|
|
|
<dt>{"http://www.w3.org/2004/xbl", "<dfn id="unbinding">unbinding</dfn>"}</dt>
|
|
|
|
<dd>A binding is being detached from the event target. This event is fired
|
|
before the current contents of <code><a
|
|
href="#xblshadowtree">xblShadowTree</a></code> are removed before the
|
|
value of <code><a href="#xblshadowtree">xblShadowTree</a></code> is set
|
|
to null.</dd>
|
|
</dl>
|
|
|
|
<p>All of these events bubble and cannot be canceled.</p>
|
|
|
|
<p>The <code><a href="#prebind">prebind</a></code> event must use the
|
|
following interface:</p>
|
|
|
|
<pre class="idl">interface ShadowTreeEvent : Event {
|
|
readonly attribute <code>XBLTemplateElement</code> xblShadowTree;
|
|
void initShadowTreeEvent(in DOMString typeArg,
|
|
in boolean canBubbleArg,
|
|
in boolean cancelableArg,
|
|
in XBLTemplateElement xblShadowTreeArg);
|
|
void initShadowTreeEventNS(in DOMString namespaceURIArg,
|
|
in DOMString typeArg,
|
|
in boolean canBubbleArg,
|
|
in boolean cancelableArg,
|
|
in XBLTemplateElement xblShadowTreeArg);
|
|
};</pre>
|
|
|
|
<p>The two methods initialise the event in a manner analogous to other
|
|
events in DOM3 Events. <a href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>The <code title="">xblShadowTree</code> member must contain a pointer to
|
|
the shadow tree being constructed, if any, and must be null otherwise.</p>
|
|
|
|
<h3 id="script"><span class="secno">3.6. </span><dfn id="script1">Script
|
|
contexts</dfn></h3>
|
|
|
|
<p>Script must always be executed in the script context of the document
|
|
specified by the script's element's <code class="dom">ownerDocument</code>
|
|
|
|
DOM attribute. This implies that scripts from different bindings in the
|
|
same binding doucment bound to different elements in the same bound
|
|
document share the same scripting scope. If the bindings were defined in
|
|
the document itself, then the scope is the same scope as for that
|
|
document.</p>
|
|
|
|
<h2 id="shadow"><span class="secno">4. </span><dfn id="shadow6">Shadow
|
|
Content</dfn></h2>
|
|
|
|
<p>A binding can specify a <span><a href="#shadow5">shadow content
|
|
template</a></span> using the <code><a
|
|
href="#template0">template</a></code> element. This template describes a
|
|
content tree that will be generated under the bound element during binding
|
|
attachment. An element declared in a bound document using a single element
|
|
can then be constructed out of multiple child elements, and this
|
|
implementation is hidden from the bound document.</p>
|
|
|
|
<p>When the shadow content template is cloned (as described in this
|
|
section), the clone is called a <span><a href="#shadow3">shadow
|
|
tree</a></span>.</p>
|
|
|
|
<h3 id="rules"><span class="secno">4.1. </span><dfn id="rules1">Rules for
|
|
Shadow Content Generation</dfn></h3>
|
|
|
|
<p>Whenever bindings are attached to an element, shadow content will
|
|
potentially be generated or destroyed.</p>
|
|
|
|
<p>When a <code><a href="#template0">template</a></code> element is mutated
|
|
in any way, any bindings whose shadow tree was constructed from that
|
|
element must be reconstructed as described in this section.</p>
|
|
|
|
<p>If a <code><a href="#definition0">definition</a></code> element that had
|
|
no <code><a href="#template0">template</a></code> element has a <code><a
|
|
href="#template0">template</a></code> element added, then a shadow tree is
|
|
generated. If the <code><a href="#template0">template</a></code> element
|
|
is removed, then the shadow tree is destroyed.</p>
|
|
|
|
<p>Everything described in this section up to the firing of the event, and
|
|
everything described in this section after the firing of the event, must
|
|
be completed atomically — that is, the UA must not execute author
|
|
scripts during those two parts of the process. User agents may optimise
|
|
this algorithm so long as the end result is the same.</p>
|
|
|
|
<p>If the binding has a shadow content template, then its <code><a
|
|
href="#template0">template</a></code> element is deeply cloned. Otherwise,
|
|
no shadow content will be generated for the bound element, its <code
|
|
class="dom"><a href="#xblshadowtree">xblShadowTree</a></code> attribute
|
|
will be <code class="dom">null</code>, and its <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> attribute will equal its
|
|
<code class="dom">childNodes</code> attribute.</p>
|
|
|
|
<p>The <code>xml:base</code> data of the cloned nodes must be set so that
|
|
the <code class="dom">baseURI</code> of nodes in the resulting shadow tree
|
|
is the same as their pre-cloning counterparts. All shadow nodes'
|
|
<code>ownerDocument</code> pointers are left pointing at the binding
|
|
document's <code class="dom">Document</code> node.</p>
|
|
|
|
<p>The newly cloned <code><a href="#template0">template</a></code> element
|
|
is then renamed to be a <dfn id="shadowtree"
|
|
title="shadowTree"><code>shadowTree</code> element</dfn> in the XBL
|
|
namespace.</p>
|
|
|
|
<p>No mutation events must be fired during the above steps.</p>
|
|
|
|
<p>A <code class="dom"><a href="#prebind">prebind</a></code> event in the
|
|
XBL namespace that bubbles but is not cancelable is fired on the bound
|
|
element, with the <code><a href="#shadowtree">shadowTree</a></code>
|
|
|
|
element as the event data.</p>
|
|
|
|
<p>The bound element's <code class="dom"><a
|
|
href="#xblshadowtree">xblShadowTree</a></code> attribute is set to point
|
|
to the root <code><a href="#shadowtree">shadowTree</a></code> element of
|
|
this tree of clones.</p>
|
|
|
|
<p>The shadow tree is then applied to the bound element: the <code><a
|
|
href="#xbl0">xbl*</a></code> DOM attributes are updated and the CSS
|
|
cascade and inheritance should be computed.</p>
|
|
|
|
<p class="note">Some implementations might optimize this algorithm, such as
|
|
using "lazy evaluation" approaches and thereby postpone the cascade and
|
|
inheritance operations.</p>
|
|
|
|
<h3 id="processing"><span class="secno">4.2. </span><dfn
|
|
id="processing1">Processing <code>content</code> elements</dfn></h3>
|
|
|
|
<p>The shadow content template may contain <code><a
|
|
href="#content0">content</a></code> elements that define where explicit
|
|
children should be inserted in the shadow content.</p>
|
|
|
|
<p class="issue">What about nested bindings, where the inner bound element
|
|
is the parent of a <code><a href="#content0">content</a></code> element
|
|
and itself has a template with <code><a
|
|
href="#content0">content</a></code> elements? Do the inner content
|
|
elements match the repositioned explicit elements, or the inner <code><a
|
|
href="#content0">content</a></code> element? If the former, we need to
|
|
define this. The latter would mean encapsulation was broken.</p>
|
|
<!-- Note: alt="" is correct for the following image, since the
|
|
paragraph says everything the image says. -->
|
|
|
|
<p><img alt="" class="extra" src="images/xbl_image_1.png" />XBL bindings
|
|
can interleave shadow content between bound elements and their explicit
|
|
children. They do so using XBL's <code><a
|
|
href="#content0">content</a></code> element. Any number of <code><a
|
|
href="#content0">content</a></code> nodes may be used in a binding's
|
|
shadow content template.</p>
|
|
|
|
<p>Expressions specified using the <code title="attr-content-includes"><a
|
|
href="#includes">includes</a></code> attribute determine which <code><a
|
|
href="#content0">content</a></code> element a given child should be placed
|
|
under.</p>
|
|
|
|
<div class="issue" id="includes-syntax">
|
|
<p><strong>Request for public feedback</strong></p>
|
|
|
|
<p>The XBL task force has requested feedback on the syntax to use for
|
|
<code>includes</code> attribute. Almost all comments suggested that XPath
|
|
(or an XPath subset) is preferred. <a
|
|
href="http://www.w3.org/TR/xslt#patterns">XPath Patterns</a> are already
|
|
used in XSLT, so many Web authors are already familiar with them.</p>
|
|
|
|
<p>It has been suggested that XPath Patterns may be expensive to compute.
|
|
Due to the highly dynamic nature of bindings, especially in the context
|
|
of bindings for user interfaces, the expressions used in <code><a
|
|
href="#content0">content</a></code> elements need to be very fast to
|
|
resolve. Implementation feedback is explicitly requested on the
|
|
performance of CSS3 Selectors compared to equivalent XPath 1.0 Patterns.</p>
|
|
|
|
<p>One problem in deciding whether Selectors or XPath is the better
|
|
solution is that XBL is targetted at several audiences, including a
|
|
primarily HTML4- and CSS-driven audience, and a primarily XML-driven
|
|
audience (XHTML authors, SVG authors, XML developers). The former may be
|
|
more familiar with Selectors, and the latter more familiar with XPath.</p>
|
|
</div>
|
|
|
|
<p>If no <code title="attr-content-includes"><a
|
|
href="#includes">includes</a></code> attribute is specified, a <code><a
|
|
href="#content0">content</a></code> element is considered generic and will
|
|
match on all content, including text nodes, CDATA nodes, comments, and so
|
|
on.</p>
|
|
|
|
<p>The <code><a href="#content0">content</a></code> element used for a
|
|
given piece of content is the first encountered with an expression that
|
|
matches the element when doing a pre-order, depth-first walk of the shadow
|
|
content template.</p>
|
|
|
|
<p>The <code><a href="#content0">content</a></code> element itself is
|
|
present in the shadow content, but is not visible in the <code
|
|
class="dom"><a href="#xblchildnodes">xblChildNodes</a></code> list. In
|
|
that list, it is simply replaced by the elements that matched it, or, if
|
|
there were no matches, by its contents.</p>
|
|
|
|
<p>If an explicit child of the bound element does not match any of the
|
|
<code><a href="#content0">content</a></code> element in the shadow tree
|
|
(or if there are no <code><a href="#content0">content</a></code> elements
|
|
in the shadow tree), then that child does not appear in the <span><a
|
|
href="#final">final flattened tree</a></span>.</p>
|
|
|
|
<h3 id="handling"><span class="secno">4.3. </span>Handling DOM Changes</h3>
|
|
|
|
<p>All of the nodes in the shadow tree are live. Whenever an element is
|
|
inserted into, removed from, or appended to the DOM, all the children must
|
|
check that their assigned <code><a href="#content0">content</a></code>
|
|
element is still appropriate, following all the same rules that applied
|
|
when first placing explicit children during shadow content generation. If
|
|
one or more nodes stop fitting into any of the <code><a
|
|
href="#content0">content</a></code> elements then they no longer appear in
|
|
the <span><a href="#final">final flattened tree</a></span>.</p>
|
|
|
|
<p>It is possible to manipulate the shadow content contained underneath a
|
|
bound element using standard DOM APIs. If shadow content that contains a
|
|
<code><a href="#content0">content</a></code> element is removed, then any
|
|
explicit children assigned to that element are relocated to the first
|
|
<code><a href="#content0">content</a></code> elements that match them.</p>
|
|
|
|
<p>Whenever the subtree of a <code><a href="#template0">template</a></code>
|
|
element is dynamically modified, any shadow trees that were constructed by
|
|
cloning that element must be reconstructed. (As no events are fired during
|
|
this process, there is no way for such bindings to update their shadow
|
|
trees after it happens.)</p>
|
|
|
|
<h3 id="shadow0"><span class="secno">4.4. </span>Shadow Content and CSS</h3>
|
|
|
|
<p>Special care should be used when considering the interactions of CSS and
|
|
XBL.</p>
|
|
|
|
<h4 id="terminology0"><span class="secno">4.4.1. </span>Terminology</h4>
|
|
|
|
<p>Shadow content introduces the concept of <dfn id="shadow7">shadow
|
|
scope</dfn> to nodes within a document. Because shadow content elements
|
|
can also have bindings attached that generate their own shadow content,
|
|
this scoping can be taken to an arbitrary level of nesting.</p>
|
|
|
|
<p>Explicit content is said to be at the <dfn
|
|
id="document-level">document-level scope</dfn>, which is the highest, or
|
|
outermost, shadow scope. Shadow content nodes are in their own <dfn
|
|
id="binding-level">binding-level shadow scopes</dfn>. Binding scopes are
|
|
determined by the bound element that contains the binding responsible for
|
|
the generation of the shadow nodes. The bound element itself is in the
|
|
shadow scope of the content around it, and its binding's shadow content is
|
|
in a deeper shadow scope. Shadow content that contains no elements that
|
|
are themselves bound is said to be in the deepest, or innermost, shadow
|
|
scope.</p>
|
|
|
|
<p>The resulting tree, after all children have been assigned to <code><a
|
|
href="#content0">content</a></code> elements, is called the <dfn
|
|
id="final">final flattened tree</dfn>, and is the tree used by the
|
|
rendering model. (See: <span><a href="#selectors1">selectors and shadow
|
|
scopes</a></span>.)</p>
|
|
|
|
<h4 id="selectors"><span class="secno">4.4.2. </span><dfn
|
|
id="selectors1">Selectors and Shadow Scopes</dfn></h4>
|
|
|
|
<p>Bindings can interleave shadow elements between the bound element and
|
|
its explicit children. (See: <span><a href="#processing1">processing <code
|
|
title="">content</code> elements</a></span>.) In this situation, a new
|
|
tree emerges that is different from the explicit content node tree. In
|
|
addition to having a single explicit parent (the bound element) and a
|
|
single set of children (the explicit children in the DOM tree), elements
|
|
also have a set of shadow parents and and shadow children (introduced by
|
|
bindings when <code><a href="#content0">content</a></code> elements were
|
|
used). This necessarily affects the CSS model.</p>
|
|
|
|
<p><em>Combinators:</em> CSS combinators, in the presence of XBL, must act
|
|
as follows. This is intended to match the definitions of CSS in all cases
|
|
other than when a selector would involve the XBL elements.</p>
|
|
|
|
<dl>
|
|
<dt>A>B</dt>
|
|
|
|
<dd>
|
|
<p>If "<code>B.parentNode</code>" is an insertion point (a <code><a
|
|
href="#content0">content</a></code> element), let "<code>X</code>" be
|
|
"<code>B.parentNode.parentNode</code>", otherwise let "<code>X</code>"
|
|
be "<code>B.parentNode</code>".</p>
|
|
|
|
<p>Now if "<code>X</code>" is the root of a shadow tree, it doesn't match
|
|
"<code>B</code>".</p>
|
|
|
|
<p>Otherwise, it matches "<code>B</code>" if the "<code>X</code>" element
|
|
is the "<code>A</code>" element.</p>
|
|
|
|
</dd>
|
|
|
|
<dt>A B</dt>
|
|
|
|
<dd>Matches "<code>B</code>" if either "<code>A>B</code>" matches
|
|
"<code>B</code>", or "<code>C>B</code>" matches "<code>B</code>" and
|
|
"<code>A C</code>" matches "<code>C</code>".</dd>
|
|
|
|
<dt>A+B</dt>
|
|
|
|
<dd>If "<code>B.previousSibling</code>" is an insertion point (a <code><a
|
|
href="#content0">content</a></code> element), it doesn't match
|
|
"<code>B</code>", otherwise, it matches if
|
|
"<code>B.previousSibling</code>" is "<code>A</code>".</dd>
|
|
|
|
<dt>A~B</dt>
|
|
|
|
<dd>Matches "<code>B</code>" if either "<code>A+B</code>" matches
|
|
"<code>B</code>", or if "<code>C+B</code>" matches "<code>B</code>" and
|
|
"<code>A~C</code>" matches "<code>C</code>".</dd>
|
|
|
|
</dl>
|
|
|
|
<p><em>Pseudo-classes and pseudo-elements:</em> Pseudo-classes and
|
|
pseudo-elements are unchanged in the presence of XBL. They operate
|
|
exclusively on the core DOM.</p>
|
|
|
|
<div class="example">
|
|
<p>In particular, note that this means that the selector
|
|
<code>:nth-child(odd)</code> would match both the <code>A</code> and
|
|
<code>B</code> nodes in the following example:</p>
|
|
|
|
<pre><xbl:template>
|
|
<A/>
|
|
<xbl:content>
|
|
<B/>
|
|
</xbl:template></pre>
|
|
|
|
<p>...regardless of the number of nodes that are inserted at the insertion
|
|
point given by the <code><a href="#content0">content</a></code> element
|
|
(whether that be 0, 1, 2, or more nodes).</p>
|
|
</div>
|
|
|
|
<p><em>Inheritance:</em> The final modified content tree determines how CSS
|
|
properties (e.g., fonts and colors) are inherited. An element either ends
|
|
up underneath its explicit parent (just as in the content model), or it
|
|
ends up being nested through a series of <code><a
|
|
href="#content0">content</a></code> elements. When nested, it inherits
|
|
from the innermost shadow parent.</p>
|
|
|
|
<p>In DOM terms, this corresponds to inheritance using the <code
|
|
class="dom"><a href="#xblparentnode">xblParentNode</a></code> attribute.</p>
|
|
|
|
<h3 id="shadow1"><span class="secno">4.5. </span>Shadow Content and
|
|
<code>xml:base</code></h3>
|
|
|
|
<p class="note">This section is intended to re-iterate what the
|
|
<code>xml:base</code> specification already states, in case there is any
|
|
question about how <code>xml:base</code> processing should work in shadow
|
|
trees.</p>
|
|
|
|
<p>Relative <code>xml:base</code>s on nodes in shadow trees are resolved
|
|
relative to their <code>parentNode</code>, or the
|
|
<code>ownerDocument</code> if there is no <code>parentNode</code>.</p>
|
|
|
|
<h3 id="binding2"><span class="secno">4.6. </span><dfn
|
|
id="binding10">Binding Stylesheets</dfn></h3>
|
|
|
|
<p>Shadow content nodes must be styled using the stylesheets specified in
|
|
the binding document.</p>
|
|
|
|
<p>Bound elements must be styled using the sheets from their <span><a
|
|
href="#shadow7">shadow scope</a></span>, not the stylesheets from their
|
|
binding.</p>
|
|
|
|
<p>If the binding document specifies alternate stylesheets, the stylesheets
|
|
used must be those that are appropriate for the currently selected
|
|
stylesheet set in that document. This may differ from the selected
|
|
stylesheet set of the bound document.</p>
|
|
|
|
<p>User agent sheets and user sheets are always applied to all shadow
|
|
scopes.</p>
|
|
|
|
<h2 id="event"><span class="secno">5. </span><dfn id="event5">Event
|
|
Handlers</dfn></h2>
|
|
|
|
<h3 id="event0"><span class="secno">5.1. </span><dfn id="event6">Event
|
|
forwarding</dfn></h3>
|
|
|
|
<p>Often, XBL developers will want to register the same event listener on
|
|
all bound elements corresponding to a given <code><a
|
|
href="#definition0">definition</a></code> element. For example, suppose
|
|
your XBL contains the following <code><a
|
|
href="#definition0">definition</a></code>:</p>
|
|
|
|
<pre><xbl:definition element="myNS:button">
|
|
...
|
|
</xbl:definition></pre>
|
|
|
|
<p>And suppose you create three instances of "myNS:button" as follows:</p>
|
|
|
|
<pre><myNS:button id="b1">...</myNs:button>
|
|
|
|
<myNS:button id="b2">...</myNs:button>
|
|
<myNS:button id="b3">...</myNs:button></pre>
|
|
|
|
<p>And suppose you want to attach a "DOMActivate" event listener to each of
|
|
the three instances. You can certainly register three separate event
|
|
listeners using either three separate event listener registration elements
|
|
(e.g., in the case of SVG, you can use <code>svg:handler</code>) or using
|
|
three separate DOM method calls (e.g., three calls to <code
|
|
class="dom">EventTarget::addEventListener</code>). However, sometimes it
|
|
is more convenient to define the event listener once as part of the
|
|
<code><a href="#definition0">definition</a></code> element and then have
|
|
the given event listener (in effect) automatically assigned to each bound
|
|
element instance that corresponds to the given <code><a
|
|
href="#definition0">definition</a></code>.</p>
|
|
|
|
<p>In order to provide such convenience, XBL provides an automatic event
|
|
forwarding mechanism for all events listeners attached to a <code><a
|
|
href="#handlergroup0">handlerGroup</a></code> element.</p>
|
|
|
|
<p>Every time an event fires on a bound element (whether during the
|
|
capture, target, or bubbling phases), if any event listeners for the given
|
|
event exist on the corresponding <code><a
|
|
href="#handlergroup0">handlerGroup</a></code> element, then those
|
|
listeners must be invoked.</p>
|
|
|
|
<div class="example">
|
|
|
|
<p>To illustrate, if we update the above example to add <code><a
|
|
href="#handlergroup0">handlerGroup</a></code> and
|
|
<code>svg:handler</code> elements as follows:</p>
|
|
|
|
<pre><xbl:definition element="myNS:button">
|
|
<xbl:template>...</xbl:template>
|
|
|
|
<xbl:handlerGroup>
|
|
<svg:handler ev:event="DOMActivate"...>...</svg:handler>
|
|
</xbl:handlerGroup>
|
|
</xbl:definition>
|
|
...
|
|
<myNS:button id="b1">...</myNs:button>
|
|
|
|
<myNS:button id="b2">...</myNs:button>
|
|
<myNS:button id="b3">...</myNs:button></pre>
|
|
|
|
<p>The result is that the user agent must automatically attach an implicit
|
|
"DOMActivate" event listener to each <code>myNS:button</code> element. If
|
|
the DOMActivate event is fired and dispatched to any of the
|
|
<code>myNS:button</code> elements, then the user agent must invoke
|
|
DOMActivate event handlers defined by the <code>svg:handler</code>
|
|
|
|
element.</p>
|
|
</div>
|
|
|
|
<p>Event listeners attached to the <code><a
|
|
href="#handlergroup0">handlerGroup</a></code> element must always be fired
|
|
after all the appropriate event listeners on the bound element itself, in
|
|
both the capture and bubbling phase.</p>
|
|
|
|
<p>Since XBL handlers usually constitute the default actions for a widget,
|
|
this allows authors in the bound document to write event handlers that
|
|
potentially suppress the default actions taken by the XBL handlers (by
|
|
using the <code class="dom">stopImmediatePropagation()</code> method).</p>
|
|
|
|
<h4 class="no-toc no-num" id="notes">Notes</h4>
|
|
|
|
<ul>
|
|
<li>The above example shows an event listener defined in markup. The event
|
|
forwarding mechanism shall work with all event listeners attached to an
|
|
<code><a href="#handlergroup0">handlerGroup</a></code> element, no matter
|
|
whether the event listeners are defined in markup or via the DOM (i.e.,
|
|
using <code class="dom">EventTarget::addEventListener</code>).</li>
|
|
|
|
<li>The event object which is passed to the listener shall be the same
|
|
event object that would have passed to an event listener registered on
|
|
the bound element itself. Its <code class="dom">currentTarget</code>
|
|
|
|
field shall always be set to the bound element.</li>
|
|
|
|
<li>All automatically registered event listeners as described in this
|
|
section shall receive the event after all handlers corresponding to
|
|
manually defined event listeners on the bound element (e.g., event
|
|
listeners defined by XML Events in explicit markup or <code
|
|
class="dom">addEventListener</code> calls via the DOM). These event
|
|
ordering rules shall apply to all phases (i.e., capture, target and
|
|
bubbling).</li>
|
|
|
|
<li>The automatic event forwarding mechanism shall only apply to the
|
|
<code><a href="#handlergroup0">handlerGroup</a></code> element in the
|
|
<code><a href="#definition0">definition</a></code> element. It must not
|
|
be applied to other <code><a
|
|
href="#handlergroup0">handlerGroup</a></code> elements.</li>
|
|
|
|
</ul>
|
|
|
|
<h3 id="event1"><span class="secno">5.2. </span><dfn id="event7">Event Flow
|
|
and Targeting Across Shadow Scopes</dfn></h3>
|
|
|
|
<p>DOM events can fire on shadow targets just as they can on explicit
|
|
targets. As long as the event flows within the same shadow tree <span
|
|
title="shadow scope"><a href="#shadow7">scope</a></span>, it is no
|
|
different from the behavior outlined in the DOM Events specification.</p>
|
|
|
|
<p>Events must flow through the final transformed content model (the
|
|
<span><a href="#final">final flattened tree</a></span>) after all elements
|
|
have been repositioned through the usage of <code><a
|
|
href="#content0">content</a></code> elements.</p>
|
|
|
|
<p>Whenever events originating from a shadow tree flow from a shadow
|
|
element in that shadow tree to the bound element, one of two actions
|
|
occurs. Either the event is retargeted so that the bound element becomes
|
|
the target, or the event is stopped and flow proceeds to the next phase.
|
|
Whenever an event is retargeted, the event is cloned, with the clone's
|
|
<code class="dom">target</code> field set to the bound element. The
|
|
original event pointing at the shadow content responsible for the event
|
|
can be obtained from a new field of the event object, <code class="dom"><a
|
|
href="#originalevent">originalEvent</a></code>, which is set to the event
|
|
that was cloned.</p>
|
|
|
|
<p>The action taken (retarget vs. stop) is specific to the event type. In
|
|
general, UI events must be retargeted and mutation events must be stopped.
|
|
Exceptions to the rule are noted below. The goal of this retargetting or
|
|
stopping is to stop outer shadow scopes from being exposed to nodes from
|
|
inner shadow scopes, and to stop outer shadow scopes from getting
|
|
apparently meaningless events that only make sense in the context of inner
|
|
shadow scopes.</p>
|
|
|
|
<p>During the capture phase, the semantics are exactly reversed. The first
|
|
node to see the event is the node after which bubbling stops; and the
|
|
target node, when the event is passing through a node at a higher shadow
|
|
scope than the event target, is always the bound element in whose shadow
|
|
content the event target lies.</p>
|
|
|
|
<h3 id="focus"><span class="secno">5.3. </span>Focus, DOMFocusIn, Blur, and
|
|
DOMFocusOut Events</h3>
|
|
|
|
<p>If shadow content underneath a focusable bound element loses focus and
|
|
shadow content also underneath the bound element takes focus, then both
|
|
focus change events must be stopped. As far as the bound element is
|
|
concerned, it retains focus throughout the two events. (Other
|
|
specifications may go into more detail as to how to determine if an
|
|
element can be focussed.)</p>
|
|
|
|
<p>The <span class="property">'nav-index'</span> property defined in the
|
|
CSS UI module <a href="#refsCSS3UI">[CSS3UI]</a> can be used to specify
|
|
the tab order for focusable elements. This property can be specified on
|
|
shadow content. Each shadow scope has a unique tab order. The <span
|
|
class="property">'nav-index'</span> values used in one shadow scope are
|
|
ignored by other shadow scopes. The tab order is resolved in the shadow
|
|
tree first to produce a list of elements in the tab order. This list is
|
|
substituted in place of the bound element in the bound element's tree tab
|
|
order.</p>
|
|
|
|
<div class="example">
|
|
<p>This example illustrates what happens with focus if the shadow tree
|
|
contains focusable elements. The example shows a binding for an element
|
|
named <code>FirstAndLastNames</code>. The shadow tree for the binding
|
|
contains two SVG editable text fields, one for the first name and one for
|
|
the last name.</p>
|
|
|
|
<pre><svg viewBox="0 0 200 60"
|
|
xmlns="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl"
|
|
xmsns:myNS="http://www.example.com">
|
|
<defs>
|
|
<xbl:xbl>
|
|
|
|
<strong><xbl:definition element="myNS:FirstAndLastNames"></strong>
|
|
<xbl:template>
|
|
<g font-size="16">
|
|
<text x="10" y="10">First name:</text>
|
|
<text x="110" y="10" <strong>id="C" editable="true" nav-index="1"</strong>/>
|
|
|
|
<text x="10" y="30">Last name:</text>
|
|
<text x="110" y="30" <strong>id="D" editable="true" nav-index="2"</strong>/>
|
|
</g>
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
|
|
</xbl:xbl>
|
|
</defs>
|
|
<g transform="translate(20,30)">
|
|
<text x="10" y="10">Customer number:</text>
|
|
<text x="110" y="10" <strong>id="A" editable="true" nav-index="10"</strong>/>
|
|
|
|
</g>
|
|
<g id="B" transform="translate(20,50)" nav-index="20">
|
|
<strong><myNS:FirstAndLastNames/></strong>
|
|
</g>
|
|
</svg></pre>
|
|
|
|
<p>Tabbing through the document will go from A to C to D, not C to D to A.</p>
|
|
|
|
</div>
|
|
|
|
<p>Because content in multiple shadow scopes can be focused, the CSS <code
|
|
class="css">:focus</code> pseudo-element is hierarchical in the presence
|
|
of XBL, with up to one element in each shadow scope matching the
|
|
pseudo-class. Style rules can be written with the assumption that they
|
|
will match (in the above example) both the file control and the element
|
|
focused inside the file control. In other words, an arbitrary chain of
|
|
elements can be in the <code class="css">:focus</code> state at the same
|
|
time. (Further specifications may describe this in more detail.)</p>
|
|
|
|
<h3 id="mouseover"><span class="secno">5.4. </span>Mouseover and Mouseout
|
|
Events</h3>
|
|
|
|
<p>Mouseover and mouseout events must be retargeted if the pointing device
|
|
genuinely moves onto (enters) or is moved away (exits) the bound element
|
|
(in addition to entering or exiting some shadow content). If, however, the
|
|
user has simply moved the pointing device from one element in the shadow
|
|
tree to another element in the same shadow tree, without entering or
|
|
exiting the bound element itself, then the event must be stopped.</p>
|
|
|
|
<h2 id="dom-interfaces"><span class="secno">6. </span><dfn
|
|
id="dom-interfaces1">DOM Interfaces</dfn></h2>
|
|
|
|
<p>XBL introduces a few XBL-specific interfaces.</p>
|
|
|
|
<h3 id="the-nodexbl"><span class="secno">6.1. </span>The <dfn
|
|
id="nodexbl0">NodeXBL</dfn> Interface</h3>
|
|
|
|
<p>The <code class="dom"><a href="#nodexbl0">NodeXBL</a></code> interface
|
|
contains methods for accessing shadow content and for obtaining shadow
|
|
parents in the altered model. The interface is implemented by DOM nodes
|
|
(regardless of whether they are currently involved with any XBL
|
|
processing) and may be obtained using binding-specific casting methods on
|
|
a Node interface.</p>
|
|
|
|
<p>All nodes except <code>Notation</code> and <code>Attr</code> nodes must
|
|
implement NodeXBL, not just element nodes.</p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition</dt>
|
|
|
|
<dd>
|
|
<pre class="idl">
|
|
interface NodeXBL {
|
|
readonly attribute Node xblParentNode;
|
|
readonly attribute NodeList xblChildNodes;
|
|
<!-- readonly attribute NodeList xblScopedChildNodes;
|
|
--> readonly attribute Node xblFirstChild;
|
|
readonly attribute Node xblLastChild;
|
|
readonly attribute Node xblPreviousSibling;
|
|
readonly attribute Node xblNextSibling;
|
|
readonly attribute Element xblFirstElementChild;
|
|
readonly attribute Element xblLastElementChild;
|
|
readonly attribute Element xblPreviousElementSibling;
|
|
readonly attribute Element xblNextElementSibling;
|
|
|
|
readonly attribute Element xblBoundElement;
|
|
readonly attribute Element xblShadowTree;
|
|
readonly attribute NodeList xblDefinitions;
|
|
};
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>Attributes</dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn class="attribute-name" id="xblparentnode"><code
|
|
class="dom">xblParentNode</code></dfn> of type <code
|
|
class="dom">Node</code>, readonly</dt>
|
|
|
|
<dd>The <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code> attribute's value is the
|
|
element's ancestor in the <span><a href="#final">final flattened
|
|
tree</a></span> after all shadow trees have been applied.
|
|
<p>If the node was repositioned by a <code><a
|
|
href="#content0">content</a></code> element, then this attribute has
|
|
the same value as the <code class="dom">parentNode</code> attribute of
|
|
the <code><a href="#content0">content</a></code> element responsible
|
|
for the repositioning in the deepest shadow scope, except if that is
|
|
the <code><a href="#shadowtree">shadowTree</a></code> element at the
|
|
top of the shadow tree, in which case the <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code> attribute has the same
|
|
value as the <code class="dom"><a
|
|
href="#xblboundelement">xblBoundElement</a></code> attribute of that
|
|
<code><a href="#content0">content</a></code> element.</p>
|
|
|
|
<p>If the node is a node in a shadow tree that is not currently in the
|
|
<span><a href="#final">final flattened tree</a></span> (for example,
|
|
the <code><a href="#shadowtree">shadowTree</a></code> element at the
|
|
top of the shadow tree is never in the <span><a href="#final">final
|
|
flattened tree</a></span>), then this attribute returns <code
|
|
class="dom">null</code>.</p>
|
|
|
|
<p>If the node is in a shadow tree and has the <code><a
|
|
href="#shadowtree">shadowTree</a></code> element at the top of the
|
|
shadow tree as its <code class="dom">parentNode</code>, then this
|
|
attribute returns the same value as the <code class="dom"><a
|
|
href="#xblboundelement">xblBoundElement</a></code> attribute.</p>
|
|
|
|
<p>If the node is in a shadow tree and has a <code><a
|
|
href="#content0">content</a></code> element that is not in error as
|
|
its <code class="dom">parentNode</code>, then this attribute returns
|
|
the same value as the <code class="dom">parentNode</code> attribute on
|
|
the <code><a href="#content0">content</a></code> element, except if
|
|
<em>that</em> would be the <code><a
|
|
href="#shadowtree">shadowTree</a></code> element at the top of the
|
|
shadow tree, in which case it returns the same as value as the <code
|
|
class="dom"><a href="#xblboundelement">xblBoundElement</a></code>
|
|
|
|
attribute.</p>
|
|
|
|
<p>Otherwise it returns the same as the <code
|
|
class="dom">parentNode</code> attribute.</p>
|
|
</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblchildnodes"><code
|
|
class="dom">xblChildNodes</code></dfn> of type <code
|
|
class="dom">NodeList</code>, readonly</dt>
|
|
|
|
<dd>The <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> attribute is a NodeList
|
|
that represents the children of the node after <code><a
|
|
href="#content0">content</a></code> elements have been applied. This
|
|
attribute can be used to navigate the content model according to XBL
|
|
after bindings have moved explicit and shadow children using <code><a
|
|
href="#content0">content</a></code> elements. The attribute's value is
|
|
the same as <code class="dom">childNodes</code> if the node is not
|
|
bound.</dd>
|
|
<!--
|
|
<dt><dfn class="attribute-name"><code class="dom">xblScopedChildNodes</code></dfn> of type <code class="dom">NodeList</code>, readonly</dt>
|
|
|
|
<dd>The <code class="dom">xblScopedChildNodes</code>
|
|
attribute is a NodeList that represents the children of the
|
|
node after <code>content</code> elements have been applied,
|
|
ignoring any nested bindings. The attribute's value is the
|
|
same as <code class="dom">childNodes</code> if the node is
|
|
not bound, and the same as the <code
|
|
class="dom">xblChildNodes</code> attribute if there are no
|
|
nested bindings.</dd>
|
|
-->
|
|
|
|
<dt><dfn class="attribute-name" id="xblnextsibling"><code
|
|
class="dom">xblNextSibling</code></dfn> of type <code
|
|
class="dom">Node</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the node that follows the current node in the
|
|
<code class="dom"><a href="#xblparentnode">xblParentNode</a></code>'s
|
|
<code class="dom"><a href="#xblchildnodes">xblChildNodes</a></code>
|
|
list, or <code class="dom">null</code> if <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code> is <code
|
|
class="dom">null</code> or if the current node is the last node in that
|
|
<code class="dom"><a href="#xblchildnodes">xblChildNodes</a></code>
|
|
|
|
list.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblprevioussibling"><code
|
|
class="dom">xblPreviousSibling</code></dfn> of type <code
|
|
class="dom">Node</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the node that precedes the current node in
|
|
the <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code>'s <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list, or <code
|
|
class="dom">null</code> if <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code> is <code
|
|
class="dom">null</code> or if the current node is the first node in
|
|
that <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblfirstchild"><code
|
|
class="dom">xblFirstChild</code></dfn> of type <code
|
|
class="dom">Node</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the first node in the <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list, or <code
|
|
class="dom">null</code> if the list is empty.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xbllastchild"><code
|
|
class="dom">xblLastChild</code></dfn> of type <code
|
|
class="dom">Node</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the last node in the <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list, or <code
|
|
class="dom">null</code> if the list is empty.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblnextelementsibling"><code
|
|
class="dom">xblNextElementSibling</code></dfn> of type <code
|
|
class="dom">Element</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the first element to follow the current node
|
|
in the <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code>'s <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list, or <code
|
|
class="dom">null</code> if <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code> is <code
|
|
class="dom">null</code> or if there are no elements past the current
|
|
node in that <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblpreviouselementsibling"><code
|
|
class="dom">xblPreviousElementSibling</code></dfn> of type <code
|
|
class="dom">Element</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the first element to precede the current node
|
|
in the <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code>'s <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list, or <code
|
|
class="dom">null</code> if <code class="dom"><a
|
|
href="#xblparentnode">xblParentNode</a></code> is <code
|
|
class="dom">null</code> or if there are no elements before the current
|
|
node in that <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblfirstelementchild"><code
|
|
class="dom">xblFirstElementChild</code></dfn> of type <code
|
|
class="dom">Element</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the first element in the <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list, or <code
|
|
class="dom">null</code> if the list contains no elements.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xbllastelementchild"><code
|
|
class="dom">xblLastElementChild</code></dfn> of type <code
|
|
class="dom">Element</code>, readonly</dt>
|
|
|
|
<dd>This attribute returns the last element in the <code class="dom"><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list, or <code
|
|
class="dom">null</code> if the list contains no elements.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblboundelement"><code
|
|
class="dom">xblBoundElement</code></dfn> of type <code
|
|
class="dom">Element</code>, readonly</dt>
|
|
|
|
<dd>The <code class="dom"><a
|
|
href="#xblboundelement">xblBoundElement</a></code> attribute is used to
|
|
obtain the bound element with the binding attached that is responsible
|
|
for the generation of the specified shadow node. This attribute enables
|
|
an author to determine the shadow scope of any content node. For
|
|
content at the <span><a href="#document-level">document-level
|
|
scope</a></span>, the attribute's value is <code
|
|
class="dom">null</code>.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xblshadowtree"><code
|
|
class="dom">xblShadowTree</code></dfn> of type <code
|
|
class="dom">Element</code>, readonly</dt>
|
|
|
|
<dd>For bound elements with a shadow tree, the <code class="dom"><a
|
|
href="#xblshadowtree">xblShadowTree</a></code> attribute returns the
|
|
cloned copy of the <code><a href="#template0">template</a></code>
|
|
element that represents the shadow content template of the element.
|
|
(That element is renamed to <code><a
|
|
href="#shadowtree">shadowTree</a></code> during shadow content
|
|
generation.) For bound elements whose binding have no shadow content
|
|
template, and for elements that are not bound, it returns <code
|
|
class="dom">null</code>.</dd>
|
|
|
|
<dt><dfn class="attribute-name" id="xbldefinitions"><code
|
|
class="dom">xblDefinitions</code></dfn> of type <code
|
|
class="dom">NodeList</code>, readonly</dt>
|
|
|
|
<dd>For bound elements, a node list containing the <code><a
|
|
href="#definition0">definition</a></code> element for the binding. In
|
|
sXBL, this list contains at most one item.</dd>
|
|
</dl>
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4 id="scoping"><span class="secno">6.1.1. </span>Scoping and Access Using
|
|
the DOM</h4>
|
|
|
|
<p>In effect the shadow content exists in its own insulated pocket within
|
|
the document, its <span><a href="#shadow7">shadow scope</a></span>.
|
|
Explicit parents have no knowledge of their shadow children in terms of
|
|
DOM Core <a href="#refsDOM3CORE">[DOM3CORE]</a>. The shadow content is not
|
|
accessible via the <code class="dom">childNodes</code> list for the bound
|
|
element, nor is it accessible using <code
|
|
class="dom">firstChild</code>/<code class="dom">nextSibling</code> to
|
|
iterate over the children of the bound element.</p>
|
|
|
|
<p>The shadow scope of an element can be determined using the <code
|
|
class="dom"><a href="#xblboundelement">xblBoundElement</a></code> property
|
|
on the <code class="dom"><a href="#nodexbl0">NodeXBL</a></code> interface.
|
|
This returns the bound element in the enclosing shadow scope that is
|
|
responsible for the shadow node. If invoked on an element at the <span><a
|
|
href="#document-level">document-level scope</a></span>, it returns <code
|
|
class="dom">null</code>.</p>
|
|
|
|
<p>DOM methods that can be invoked on elements (e.g., <code
|
|
class="dom">getElementsByTagName</code>) will only see nodes that are in
|
|
the same shadow scope. Methods invoked on the document (e.g., <code
|
|
class="dom" title="">getElementById</code>) only see nodes that are at the
|
|
document-level scope.</p>
|
|
|
|
<p>On shadow content nodes, <code class="dom">ownerDocument</code> always
|
|
points to the document from which the nodes were cloned.</p>
|
|
|
|
<p>Elements in different shadow scopes may have clashing IDs. IDs need only
|
|
be unique within each shadow scope.</p>
|
|
|
|
<p>Elements that are the root of a shadow tree (that is, cloned <code><a
|
|
href="#shadowtree">shadowTree</a></code> elements that can be accessed by
|
|
an <code><a href="#xblshadowtree">xblShadowTree</a></code> attribute)
|
|
cannot be inserted into a document. Any attempt to do so must raise a
|
|
<code class="dom">HIERARCHY_REQUEST_ERR</code>. <!-- (This is because if
|
|
you did, you would end up having two ways to reach the nodes in the
|
|
<span>final flattened tree</span>, which would be rather bad for the xbl* traversal
|
|
attributes!.) --></p>
|
|
|
|
<h4 id="dom-traversals"><span class="secno">6.1.2. </span><dfn
|
|
id="dom-traversals1">DOM Traversals in the Presence of XBL</dfn></h4>
|
|
|
|
<p>When the DOM is navigated using the normal DOM Core attributes, starting
|
|
from the document, the UA must represent the original DOM, with no XBL
|
|
nodes and shadow content, and with children of bound elements in their
|
|
original order.</p>
|
|
|
|
<p>The <code class="dom"><a href="#xblshadowtree">xblShadowTree</a></code>
|
|
attribute on bound elements returns the element that was cloned from the
|
|
XBL <code><a href="#template0">template</a></code> element. (That element
|
|
is renamed to <code><a href="#shadowtree">shadowTree</a></code> during
|
|
shadow content generation.) Manipulating the shadow content tree must
|
|
directly affect the content under the bound element. <code><a
|
|
href="#content0">content</a></code> elements may be moved about or even
|
|
removed altogether, etc, and all these changes must be immediately
|
|
reflected in the DOM.</p>
|
|
|
|
<p>Because each bound element gets its own copy of the cloned template,
|
|
changes to a bound element's shadow content only affect that bound
|
|
element. Other bindings are unaffected.</p>
|
|
<!-- XXXX -->
|
|
|
|
<p>If an element is added to the DOM dynamically, its shadow scope is that
|
|
of its parent element. Adding an element as a child of a bound element
|
|
causes that element to be assigned to an appropriate <code><a
|
|
href="#content0">content</a></code> element (if there is one — if
|
|
there is not, the element does not appear anywhere in the <span><a
|
|
href="#final">final flattened tree</a></span>).</p>
|
|
|
|
<h4 id="example"><span class="secno">6.1.3. </span>Example of XBL DOM
|
|
Traversals</h4>
|
|
|
|
<div class="example">
|
|
<p>Imagine the following document fragment:</p>
|
|
|
|
<pre>...
|
|
<A>
|
|
<B>
|
|
|
|
<C/>
|
|
<D/>
|
|
</B>
|
|
</A>
|
|
...</pre>
|
|
|
|
<p>...is bound to the following XBL:</p>
|
|
|
|
<pre><xbl:xbl xmlns:xbl="http://www.w3.org/2004/xbl">
|
|
<xbl:definition element="B">
|
|
<xbl:template>
|
|
<P>
|
|
<Q>
|
|
<xbl:content includes="C">
|
|
|
|
<R/>
|
|
</xbl:content>
|
|
</Q>
|
|
<xbl:content includes="D">
|
|
<S/>
|
|
</xbl:content>
|
|
|
|
</P>
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
<xbl:definition element="Q">
|
|
<xbl:template>
|
|
<X>
|
|
|
|
<Y>
|
|
<xbl:content>
|
|
<Z1/>
|
|
</xbl:content>
|
|
<xbl:content>
|
|
<Z2/>
|
|
|
|
</xbl:content>
|
|
</Y>
|
|
</X>
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
</xbl:xbl></pre>
|
|
|
|
<p>The resulting DOM would look like the following. To read these
|
|
diagrams, use the following key:</p>
|
|
|
|
<pre>
|
|
| Solid/dashed lines represent normal DOM traversal attribute
|
|
---+--- relationships using childNodes, parentNode, nextSibling,
|
|
| previousSibling, firstChild, lastChild, etc.
|
|
|
|
: Dotted lines represent XBL traversal attribute relationships
|
|
...:... using xblChildNodes, xblParentNode, xblNextSibling,
|
|
: xblPreviousSibling, xblFirstChild, xblLastChild, etc.
|
|
|
|
) xblShadowTree
|
|
</pre>
|
|
|
|
<p>White-space nodes have, for sanity, been left out of these diagrams.</p>
|
|
|
|
<p>DOM view:</p>
|
|
|
|
<pre>
|
|
|
|
|
+-- A
|
|
|
|
|
+-- B
|
|
|
|
|
+-- C
|
|
|
|
|
+-- D
|
|
</pre>
|
|
|
|
<p>Clone of the shadow tree for B elements (B.xblShadowTree):</p>
|
|
|
|
<pre>
|
|
template
|
|
|
|
|
+-- P
|
|
|
|
|
+-- Q
|
|
| |
|
|
| +-- content
|
|
| |
|
|
| +-- R
|
|
|
|
|
+-- content
|
|
|
|
|
+-- S
|
|
</pre>
|
|
|
|
<p>Clone of the shadow tree for Q elements (Q.xblShadowTree):</p>
|
|
|
|
<pre>
|
|
template
|
|
|
|
|
+-- X
|
|
|
|
|
+-- Y
|
|
|
|
|
+-- content
|
|
| |
|
|
| +-- Z1
|
|
|
|
|
+-- content
|
|
|
|
|
+-- Z2
|
|
</pre>
|
|
|
|
<p>The xbl traversal for the whole thing:</p>
|
|
|
|
<pre>
|
|
:
|
|
:.. A
|
|
:
|
|
:.. B
|
|
:
|
|
:.. P
|
|
:
|
|
:.. Q
|
|
: :
|
|
: :.. X
|
|
: :
|
|
: :.. Y
|
|
: :
|
|
: :.. C
|
|
: :
|
|
: :.. Z2
|
|
:
|
|
:.. D
|
|
|
|
</pre>
|
|
|
|
<p>The combined view of the DOM and XBL traversals of the whole thing:</p>
|
|
|
|
<pre id="pretty-diagram">
|
|
:|___
|
|
:....A template
|
|
:|___ ) |
|
|
:... B |
|
|
:| |
|
|
:|... P template
|
|
| :|____ ) |
|
|
| :|... Q |
|
|
| :| :| |
|
|
| :| :|.... X
|
|
| :| | :\_______
|
|
| :| | :....... Y __
|
|
| :| | : \
|
|
| :| +-- content* : |
|
|
| :| | : |
|
|
| :| +-- R : +-- content*
|
|
| :| : | |
|
|
+---:|--------- C* ......: | `-- Z1
|
|
| :| : |
|
|
| :| : `-- content
|
|
| :| : |___
|
|
| :| :............ Z2
|
|
| :`-- content#
|
|
| : |
|
|
| : `-- S
|
|
|___:____
|
|
:... D#
|
|
</pre>
|
|
<!--
|
|
<p>In this final tree, the dashed lines show the relationships that
|
|
are described by the in <code
|
|
class="dom">xblScopedChildNodes</code> attribute, when those aren't
|
|
the same as the relationships described by the <code
|
|
class="dom">xblChildNodes</code> attribute, which are themselves
|
|
represented by the dotted lines:</p>
|
|
|
|
<pre>
|
|
:
|
|
:.. A
|
|
:
|
|
:.. B
|
|
|:
|
|
|:.. P
|
|
| :
|
|
| :.. Q
|
|
| : |:
|
|
| : |:.. X
|
|
| : | :
|
|
| : | :.. Y
|
|
| : :
|
|
|____:__|________:__
|
|
| : `- - - - : - C
|
|
| : :''
|
|
| : :
|
|
| : :.. Z2
|
|
|____:__
|
|
:.. D
|
|
</pre>
|
|
-->
|
|
</div>
|
|
|
|
<h3 id="the-event"><span class="secno">6.2. </span>The <code>Event</code>
|
|
|
|
Interface</h3>
|
|
|
|
<p>Objects that implement the <code class="dom">Event</code> interface must
|
|
also implement the <code class="dom"><a
|
|
href="#originalevent">OriginalEvent</a></code> interface:</p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition</dt>
|
|
|
|
<dd>
|
|
<pre
|
|
class="idl"> <!-- technically this is invalid OMG IDL but whatever! -->
|
|
interface OriginalEvent {
|
|
readonly attribute Event originalEvent;
|
|
};
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>The <dfn id="originalevent"><code class="dom">originalEvent</code></dfn>
|
|
|
|
attribute must point to the event that was cloned the last time the event
|
|
was retargetted, if any, and must be null if the event was never
|
|
retargetted. (See: <span><a href="#event7">event flow and targeting across
|
|
shadow scopes</a></span>.)</p>
|
|
|
|
<p>If an event is retargetted several times, a chain is formed using this
|
|
attribute, from which script can access each clone of the event, finding
|
|
the original target at each step.</p>
|
|
|
|
<h3 id="the-xblshadowtreeelement"><span class="secno">6.3. </span>The <dfn
|
|
id="xblshadowtreeelement0">XBLShadowTreeElement</dfn> Interface</h3>
|
|
|
|
<p>The <code class="dom"><a
|
|
href="#xblshadowtreeelement0">XBLShadowTreeElement</a></code> interface is
|
|
implemented by <code><a href="#shadowtree">shadowTree</a></code> elements
|
|
that are in the XBL namespace.</p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition</dt>
|
|
|
|
<dd>
|
|
<pre class="idl">
|
|
interface XBLTemplateElement : Element {
|
|
Element getElementById(in DOMString elementId);
|
|
};
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>Attributes</dt>
|
|
|
|
<dd> None.</dd>
|
|
|
|
<dt>Methods</dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn class="method-name" id="getelementbyid"><code
|
|
class="dom">getElementById</code></dfn></dt>
|
|
|
|
<dd>
|
|
<p class="note">This method is modelled after the method of the same
|
|
name defined by <a href="#refsDOM3CORE">[DOM3CORE]</a> on the <code
|
|
class="dom">Document</code> interface.</p>
|
|
|
|
<p>Returns the <code class="dom">Element</code> that has an ID
|
|
attribute with the given value. If no such element exists, this
|
|
returns <code class="dom">null</code>. If more than one element has an
|
|
ID attribute with that value, what is returned is undefined.</p>
|
|
|
|
<p>The method shall only search through the <code><a
|
|
href="#shadowtree">shadowTree</a></code> element and its descendants.</p>
|
|
|
|
<p>The DOM implementation is expected to use the attribute <code
|
|
class="dom">Attr.isId</code> to determine if an attribute is of type
|
|
ID.</p>
|
|
|
|
<p class="note">Attributes with the name "ID" or "id" are not of type
|
|
ID unless so defined. For example, elements with the name "id" on
|
|
elements that are in the XHTML, SVG and XBL namespaces are defined to
|
|
be of type ID by their respective specifications.</p>
|
|
|
|
<dl>
|
|
<dt>Parameters</dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class="parameter-name">elementId</code> of type <code
|
|
class="dom">DOMString</code></dt>
|
|
|
|
<dd>The unique <code>id</code> value for an element.</dd>
|
|
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class="dom">Element</code></dt>
|
|
|
|
<dd> The matching element or null if there is none.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>No Exceptions</dt>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2 id="Examples"><span class="secno">7. </span>Examples</h2>
|
|
|
|
<div class="issue">
|
|
<p>This entire section is new and needs to be reviewed.</p>
|
|
|
|
<p>The flowchart example should be close to correct, but it still requires
|
|
careful review.</p>
|
|
|
|
<p>The various other RCC examples (GML, XForms, UI) from the last SVG 1.2
|
|
public draft have been copied from the SVG 1.2 draft and placed into this
|
|
document (after modifications to upgrade RCC to sXBL). The examples at
|
|
the end are just as incomplete as they were when they were part of the
|
|
writeup on SVG12/RCC.</p>
|
|
</div>
|
|
|
|
<p>This section contains some examples of using sXBL with SVG 1.2.</p>
|
|
|
|
<p>In the following example, bindings are used to make three new elements
|
|
act like coloured text blocks.</p>
|
|
|
|
<pre class="example">
|
|
|
|
<svg:svg xmlns:svg="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl">
|
|
<svg:defs>
|
|
<xbl:xbl>
|
|
<xbl:definition element="red">
|
|
<xbl:template>
|
|
<svg:text fill="red"><xbl:content/></svg:text>
|
|
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
<xbl:definition element="green">
|
|
<xbl:template>
|
|
<svg:text fill="green"><xbl:content/></svg:text>
|
|
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
<xbl:definition element="blue">
|
|
<xbl:template>
|
|
<svg:text fill="blue"><xbl:content/></svg:text>
|
|
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
</xbl:xbl>
|
|
</svg:defs>
|
|
|
|
<red> Red text. </red>
|
|
|
|
<green> Green text. </green>
|
|
<blue> Blue text. </blue>
|
|
|
|
</svg:svg></pre>
|
|
|
|
<p>In the following example, an SVG file references a set of custom
|
|
elements for flowcharting from an external file using the <code
|
|
class="element"><a href="#import0">import</a></code> element, and then
|
|
uses the flowcharting custom elements to lay out and render a flowchart:</p>
|
|
|
|
<pre class="example"><svg width="12cm" height="3cm"
|
|
xmlns="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl">
|
|
<desc>Example xbl02 - simple flowchart example using sXBL</desc>
|
|
|
|
<!-- XPointer reference to the location for the flowchart extensions -->
|
|
<xbl:import bindings="xbl02-flowcharts.svg#flowcharts"/>
|
|
|
|
<!-- Define elements that use the flowchart extensions. As a result of using
|
|
the extensions, a shadow tree of low-level SVG (circle, rect, path elements)
|
|
is attached to the 'flowchart' element. The user agent renders the shadow tree. -->
|
|
<flowchart xmlns="http://example.org/flowcharts"
|
|
x="0%" y="0%" width="100%" height="100%">
|
|
<terminalNode>Start</terminalNode>
|
|
<processNode>Step 1</processNode>
|
|
<processNode>Step 2</processNode>
|
|
|
|
<terminalNode>End</terminalNode>
|
|
</flowchart>
|
|
</svg></pre>
|
|
|
|
<p><img alt="The result would have a blue circle saying 'Start' from which
|
|
a black arrow exits, pointing at a green rectangle containing the text
|
|
'Step 1', which itself has a similar arrow pointing to 'Step 2', which
|
|
itself again has an arrow, this time pointing to a final blue circle
|
|
saying 'End'." height="114" src="images/examples/xbl02.png" width="454" /></p>
|
|
|
|
<p><a href="images/examples/xbl02.svg">View this image as SVG
|
|
(SVG/sXBL-enabled browsers only)</a></p>
|
|
|
|
<p> Here is the file which defines the simple flowcharting extensions used
|
|
in the example above:</p>
|
|
|
|
<pre
|
|
class="example"><svg xmlns="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl"
|
|
xmlns:ev="http://www.w3.org/2001/xml-events"
|
|
xmlns:flow="http://example.org/flowcharts">
|
|
<desc>Supplemental file for example xbl02.svg -
|
|
contains definition of simple flowchart extension elements.</desc>
|
|
|
|
<xbl:xbl id="flowcharts">
|
|
|
|
<!-- Example needs to be upgraded to show handling of mutation events -->
|
|
|
|
<defs>
|
|
<symbol id="connectorline">
|
|
<path transform="translate(0 50)" stroke="black" stroke-width="3" fill="black"
|
|
d="M 0,0 L 90,0 L 90,-10 L 100,0 L 90,10 L 90,0"/>
|
|
</symbol>
|
|
|
|
</defs>
|
|
|
|
<xbl:definition element="flow:terminalNode">
|
|
<xbl:template>
|
|
<g>
|
|
<circle stroke="#008" stroke-width="5" fill="none" cx="50" cy="50" r="50"/>
|
|
<text x="50" y="57" font-size="25" text-anchor="middle"><xbl:content/></text>
|
|
|
|
</g>
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
|
|
<xbl:definition name="flow:processNode">
|
|
<xbl:template>
|
|
<g>
|
|
|
|
<rect stroke="#080" stroke-width="5" fill="none" width="150" height="100" rx="10"/>
|
|
<text x="75" y="57" font-size="25" text-anchor="middle"><xbl:content/></text>
|
|
</g>
|
|
</xbl:template>
|
|
</xbl:definition>
|
|
|
|
<xbl:definition name="flow:flowchart">
|
|
<!-- For this example, set up template with no extra whitespace to
|
|
simplify the sample ECMAScript. -->
|
|
<xbl:template><svg><xbl:content/></svg></xbl:template>
|
|
<xbl:handlerGroup>
|
|
|
|
<!-- Note: using the 'svg:handler' element that is new with SVG 1.2 -->
|
|
<handler ev:event="xbl:bound" type="text/ecmascript"><![CDATA[
|
|
var svgns = "http://www.w3.org/2000/svg";
|
|
var xlinkns = "http://www.w3.org/1999/xlink";
|
|
var flowchartns = "http://example.org/flowcharts";
|
|
var ELEMENT_NODE = 1;
|
|
var SIDE_INDENT = 50;
|
|
var PROCESSNODE_WIDTH = 150;
|
|
var TERMINALNODE_WIDTH = 100;
|
|
var CONNECTOR_WIDTH = 100;
|
|
var YPOS = 50;
|
|
var flowchartelement = evt.target;
|
|
var templateElement = flowchartelement.xblShadowTree;
|
|
var svgElm = templateElement.firstChild;
|
|
svgElm.setAttributeNS(null, "x", flowchartelement.getAttributeNS(null, "x"));
|
|
svgElm.setAttributeNS(null, "y", flowchartelement.getAttributeNS(null, "y"));
|
|
svgElm.setAttributeNS(null, "width", flowchartelement.getAttributeNS(null, "width"));
|
|
svgElm.setAttributeNS(null, "height", flowchartelement.getAttributeNS(null, "height"));
|
|
|
|
// Determine total width needed and set viewBox attribute appropriately.
|
|
var totalWidth = 0;
|
|
var nodeCount = 0;
|
|
for( var node = flowchartelement.firstChild ; node != null ; node = node.nextSibling )
|
|
{
|
|
// only process elements in flowchart ns
|
|
if( node.nodeType == ELEMENT_NODE && node.namespaceURI == flowchartns) {
|
|
nodeCount++;
|
|
if (node.localName == "processNode")
|
|
totalWidth += PROCESSNODE_WIDTH;
|
|
else if (node.localName == "terminalNode")
|
|
totalWidth += TERMINALNODE_WIDTH;
|
|
}
|
|
}
|
|
totalWidth += (nodeCount-1)*CONNECTOR_WIDTH + 2*SIDE_INDENT;
|
|
svgElm.setAttributeNS(null, "viewBox", "0 0 "+totalWidth+" 200");
|
|
var xtrans = 50;
|
|
|
|
// Position all of the nodes and draw the connectors.
|
|
var xpos = SIDE_INDENT;
|
|
var nodeNum = 0;
|
|
for( var node = flowchartelement.firstChild ; node != null ; node = node.nextSibling )
|
|
{
|
|
// only process elements in flowchart ns
|
|
if( node.nodeType == ELEMENT_NODE && node.namespaceURI == flowchartns) {
|
|
node.xblShadowTree.setAttributeNS(null, "transform", "translate("+xpos+" "+YPOS+")");
|
|
var nodeWidth;
|
|
if (node.localName == "processNode") {
|
|
nodeWidth = PROCESSNODE_WIDTH;
|
|
} else if (node.localName == "terminalNode") {
|
|
nodeWidth = TERMINALNODE_WIDTH;
|
|
}
|
|
xpos += nodeWidth;
|
|
// Add connector line to end of flowchart node's shadowTree.
|
|
if (nodeNum < (nodeCount-1)) {
|
|
var useElement = document.createElementNS(svgns, "use");
|
|
useElement.setAttributeNS(xlinkns, "xlink:href", "#connectorline");
|
|
useElement.setAttributeNS(null, "transform", "translate("+nodeWidth+" 0)");
|
|
node.xblShadowTree.appendChild(useElement);
|
|
xpos += CONNECTOR_WIDTH;
|
|
}
|
|
nodeNum++;
|
|
}
|
|
}
|
|
]]></handler>
|
|
</xbl:handlerGroup>
|
|
|
|
</xbl:definition>
|
|
|
|
</xbl:xbl>
|
|
|
|
</svg></pre>
|
|
|
|
<p>The next example takes sample code from section 4.6 from the <a
|
|
href="http://www.opengis.net/">Geography Markup Language (GML)
|
|
specification</a>, version 2.1.2. The 'extensionDefs' element would effect
|
|
a client-side transformation from original XML/GML into final-form SVG
|
|
rendering.</p>
|
|
|
|
<pre class="example">
|
|
<svg width="12cm" height="3cm"
|
|
xmlns="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl">
|
|
<desc>Example xbl-gml-01 - GML and XBL</desc>
|
|
|
|
<!-- XPointer reference to the location for the GML extensions -->
|
|
<xbl:import bindings="xbl-gml-01-exts.svg#gml"/>
|
|
|
|
<CityModel xmlns="http://www.opengis.net/examples"
|
|
xmlns:gml="http://www.opengis.net/gml"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://www.opengis.net/examples city.xsd">
|
|
|
|
<gml:name>Cambridge</gml:name>
|
|
<gml:boundedBy>
|
|
<gml:Box srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">
|
|
<gml:coord><gml:X>0.0</gml:X><gml:Y>0.0</gml:Y></gml:coord>
|
|
|
|
<gml:coord><gml:X>100.0</gml:X><gml:Y>100.0</gml:Y></gml:coord>
|
|
</gml:Box>
|
|
</gml:boundedBy>
|
|
|
|
<cityMember>
|
|
<River>
|
|
<gml:description>The river that runs through Cambridge.</gml:description>
|
|
<gml:name>Cam</gml:name>
|
|
<gml:centerLineOf>
|
|
|
|
<gml:LineString srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">
|
|
<gml:coord><gml:X>0</gml:X><gml:Y>50</gml:Y></gml:coord>
|
|
<gml:coord><gml:X>70</gml:X><gml:Y>60</gml:Y></gml:coord>
|
|
|
|
<gml:coord><gml:X>100</gml:X><gml:Y>50</gml:Y></gml:coord>
|
|
</gml:LineString>
|
|
</gml:centerLineOf>
|
|
</River>
|
|
|
|
</cityMember>
|
|
|
|
<dateCreated>2000-11</dateCreated>
|
|
</CityModel>
|
|
</svg> </pre>
|
|
|
|
<p>The next example takes sample code from [Appendix G of the XForms
|
|
specification | http://www.w3.org/TR/xforms/sliceG.html ] . The <code
|
|
class="element">extensionDefs</code> element would effect a client-side
|
|
transformation from original XForms elements into final-form SVG
|
|
rendering. In this example, the assumption is that the extension would
|
|
implement all or at least a large part of the XForms specification via
|
|
DOM/scripting.</p>
|
|
|
|
<pre class="example">
|
|
<svg width="12cm" height="3cm"
|
|
xmlns="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:xforms="http://www.w3.org/2002/xforms"
|
|
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:ev="http://www.w3.org/2001/xml-events"
|
|
xmlns:xbl="http://www.w3.org/2004/xbl"
|
|
xmlns:my="http://commerce.example.com/payment">
|
|
<desc>Example xbl-xforms-01 - using sXBL within a combined XForms+SVG user agent</desc>
|
|
<title xml:lang="fr">XForms en SVG</title>
|
|
|
|
<!-- XPointer reference to the location for the XForms extensions to SVG.
|
|
The extensions convert the XForms UI elements into low-level SVG
|
|
interactive graphics and also provide high-level features,
|
|
such as client-side validation and the XForms event model. -->
|
|
<xbl:import bindings="xbl-xforms-01-exts.svg#xforms"/>
|
|
|
|
<rx:renderXForms xmlns:rx="http://example.org/rcc-xforms"
|
|
xmlns="http://www.w3.org/2002/xforms">
|
|
|
|
<model schema="payschema.xsd">
|
|
<instance>
|
|
|
|
<my:payment as="credit">
|
|
<my:cc />
|
|
<my:exp />
|
|
</my:payment>
|
|
</instance>
|
|
<submission action="http://www.example.com/buy.rb" method="post" id="s00" />
|
|
|
|
<bind nodeset="my:cc" relevant="../@as='credit'" required="true()" />
|
|
<bind nodeset="my:exp" relevant="../@as='credit'" required="true()" />
|
|
</model>
|
|
|
|
<group xmlns="http://www.w3.org/2002/xforms">
|
|
<trigger>
|
|
<label>Français</label>
|
|
|
|
<toggle case="fr" ev:event="xforms-activate" />
|
|
</trigger>
|
|
<trigger>
|
|
<label>English</label>
|
|
<toggle case="en" ev:event="xforms-activate" />
|
|
|
|
</trigger>
|
|
</group>
|
|
|
|
<input ref="my:cc">
|
|
<label xml:lang="fr">Numéro de carte bancaire</label>
|
|
<alert xml:lang="fr">Saisissez un numéro de carte
|
|
bancaire valide en séparant chaque groupe de chiffres
|
|
d'un espace ou d'un trait d'union.</alert>
|
|
|
|
</input>
|
|
|
|
<input ref="my:exp">
|
|
<label xml:lang="fr">Date d'échéance</label>
|
|
</input>
|
|
|
|
<submit submission="s00">
|
|
<label xml:lang="fr">Achetez</label>
|
|
</submit>
|
|
</svg> </pre>
|
|
|
|
<p> The next example supplements the XForms example above with the
|
|
following simple example which shows a set of extension elements <code
|
|
class="element">ui:menubar</code>, <code class="element">ui:menu</code>,
|
|
<code class="element">ui:menuitem</code>) which present a menubar and a
|
|
scrolling area for graphics.</p>
|
|
|
|
<pre class="example">
|
|
<svg width="525" height="575"
|
|
xmlns="http://www.w3.org/2000/svg" version="1.2"
|
|
xmlns:ui="http://example.org/xbl-ui">
|
|
<desc>Example xbl-ui-01 - using XBL for UI elements</desc>
|
|
<title>UI in SVG</title>
|
|
|
|
<!-- XPointer reference to the location for the UI extensions to SVG.
|
|
The extensions convert the UI elements into low-level SVG. -->
|
|
|
|
<xbl:import bindings="xbl-ui-01-exts.svg#ui"/>
|
|
|
|
<ui:menubar x="25" y="25" width="500" height="20" font-size="14">
|
|
<ui:menu title=File>
|
|
<ui:menuitem title=New op="newdoc(evt)">
|
|
<ui:menuitem title=Open op="opendoc(evt)">
|
|
</ui:menu>
|
|
|
|
<ui:menu title=Edit>
|
|
<ui:menuitem title=Copy op="copy(evt)">
|
|
<ui:menuitem title=Past op="paste(evt)">
|
|
</ui:menu>
|
|
</ui:menubar>
|
|
|
|
<ui:scrollArea x="25" y="50" width="500" height="400">
|
|
|
|
<image xlink:href="..." ... />
|
|
<path d="..." ... />
|
|
<text transform="..." font-size="...">...</text>
|
|
</ui:scrollArea>
|
|
</svg> </pre>
|
|
|
|
<p> The last example shows XBL being used for custom container elements
|
|
that perform layout, in this case a magazine layout.</p>
|
|
|
|
<pre class="example">
|
|
<svg>
|
|
...
|
|
|
|
<!-- XPointer reference to the location for the widgets extensions to SVG.
|
|
The extensions convert the widget elements into low-level SVG. -->
|
|
<xbl:import bindings="xbl-dynlayout-01-exts.svg#dynlayout" />
|
|
|
|
<foo:DynamicPageLayout>
|
|
<foo:articles>
|
|
<foo:article>
|
|
<foo:title>Major war erupts</foo:title>
|
|
<foo:para>War broke out around the world today...</foo:para>
|
|
|
|
</foo:article>
|
|
<foo:article>
|
|
<foo:title>Two headed-chicken born</foo:title>
|
|
<foo:para>The sleepy town of Frostbite Falls is excited about...</foo:para>
|
|
</foo:article>
|
|
|
|
</foo:articles>
|
|
</foo:DynamicPageLayout>
|
|
...
|
|
</svg> </pre>
|
|
|
|
<h2 id="grammar"><span class="secno">8. </span>Grammar</h2>
|
|
|
|
<div class="issue">This grammar is not necessarily completely up to date.</div>
|
|
|
|
<p>The following defines the grammar for sXBL using <a
|
|
href="http://www.oasis-open.org/committees/relax-ng/spec-20011203.html">RelaxNG</a>.</p>
|
|
|
|
<pre class="schema">
|
|
<!-- ==============================================================
|
|
sXBL 1.0 ~ simplied schema
|
|
Robin Berjon <robin.berjon@expway.fr>
|
|
31/05/2004
|
|
============================================================== -->
|
|
|
|
<grammar ns='http://www.w3.org/2004/xbl'
|
|
xml:lang='en'
|
|
xmlns='http://relaxng.org/ns/structure/1.0'
|
|
xmlns:a='http://relaxng.org/ns/compatibility/annotations/1.0'
|
|
datatypeLibrary='http://www.w3.org/2001/XMLSchema-datatypes'
|
|
>
|
|
<!--
|
|
NOTES:
|
|
- this is a simplified schema in that it does not define classes and
|
|
other such constructs that would make it easier to integrate into the
|
|
rest of the SVG schema
|
|
- I seem to remember there was a bug in my RNG namespace wildcards. If
|
|
so, it has been copied here (I have no reference handy).
|
|
- I have followed the descriptions in the spec, so that if it says "zero
|
|
or more foo" and then "zero or more bar", then the foos must occur
|
|
before the bars. This can be changed.
|
|
- there are some spec issues embedded in the comments
|
|
-->
|
|
|
|
<!-- ... common definitions .............................................. -->
|
|
<define name='id.attrib'>
|
|
<optional>
|
|
<attribute name='id'>
|
|
|
|
<data type='ID'/>
|
|
</attribute>
|
|
</optional>
|
|
</define>
|
|
|
|
<!-- ... elements ........................................................ -->
|
|
<element name='xbl'>
|
|
|
|
<zeroOrMore><ref name='definition'/></zeroOrMore>
|
|
<zeroOrMore><ref name='import'/></zeroOrMore>
|
|
<ref name='id.attrib'/>
|
|
</element>
|
|
|
|
<element name='definition'>
|
|
<choice>
|
|
<attribute name='ref'><data type='anyURI'/></attribute>
|
|
<group>
|
|
<optional><ref name='template'/></optional>
|
|
|
|
<optional><ref name='handlerGroup'/></optional>
|
|
<attribute name='element'><data type='QName'/></attribute>
|
|
</group>
|
|
</choice>
|
|
<ref name='id.attrib'/>
|
|
|
|
</element>
|
|
|
|
<element name='template'>
|
|
<ref name='id.attrib'/>
|
|
</element>
|
|
|
|
<element name='content'>
|
|
<optional><attribute name='includes'><text/></attribute></optional>
|
|
|
|
<ref name='id.attrib'/>
|
|
</element>
|
|
|
|
<element name='handlerGroup'>
|
|
<!-- the content model for this element mentions ev:listener and svg:handler
|
|
but is rather unclear as to what should be included here -->
|
|
<ref name='id.attrib'/>
|
|
</element>
|
|
|
|
<element name='import'>
|
|
<!-- this should really be either of xlink:href or src -->
|
|
<optional><attribute name='bindings'><data type='anyURI'/></attribute></optional>
|
|
<ref name='id.attrib'/>
|
|
|
|
</element>
|
|
</grammar>
|
|
</pre>
|
|
|
|
<h2 id="RCCComparison"><span class="secno">9. </span>Comparison of sXBL to
|
|
RCC</h2>
|
|
|
|
<p class="note">This section will be removed before the Last Call
|
|
draft of the sXBL specification.</p>
|
|
|
|
<p>With this first public draft of sXBL, the SVG 1.2 feature formerly known
|
|
as RCC (Rendering Custom Content:
|
|
http://www.w3.org/TR/2004/WD-SVG12-20040510/#rcc) has been factored out
|
|
into its own reusable namespace and reconciled to be forward-looking for
|
|
use by other XBL grammars.</p>
|
|
|
|
<p>The following table provides a quick summary comparison of how sXBL
|
|
compares with the RCC (Rendering Custom Content) feature found in earlier
|
|
drafts of SVG 1.2:</p>
|
|
|
|
<table summary="Comparison sXBL to RCC">
|
|
<thead>
|
|
<tr>
|
|
<td>RCC</td>
|
|
|
|
<td>sXBL</td>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<p><code><svg:extensionDefs
|
|
xlink:href="<em>xpointer</em>"</code>/></p>
|
|
|
|
<p>In RCC, the svg:extensionDefs element could use an <em>xpointer</em>
|
|
to reference the binding definitions. If so, the <em>xpointer</em> had
|
|
to point to a different svg:extensionDefs element, typically in a
|
|
separate file.</p>
|
|
</td>
|
|
|
|
<td>
|
|
<p><code><xbl:import bindings="<em>xpointer</em>"/></code></p>
|
|
|
|
<p>To accomplish the same functionality in sXBL, use the xbl:import
|
|
element. In sXBL, there is more flexibility. The <em>xpointer</em> can
|
|
point to either an xbl:xbl element, typically in a separate file, or
|
|
to an SVG file which can contain any number of xbl:xbl elements, all
|
|
of which get processed.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><code><svg:extensionDefs namespace="<em>nsURI</em>"><br />
|
|
|
|
...definitions of custom elements...<br />
|
|
</svg:extensionDefs></code></p>
|
|
|
|
<p>In RCC, the 'namespace' attribute applied to all svg:elementDef
|
|
children of the svg:extensionDefs element.</p>
|
|
</td>
|
|
|
|
<td>
|
|
<p><code><xbl:xbl><br />
|
|
|
|
...definitions of custom elements...<br />
|
|
</xbl:xbl></code></p>
|
|
|
|
<p>In sXBL, the 'namespace' attribute is no longer needed. The
|
|
'element' attribute on the xbl:definition element takes a QName. The
|
|
namespace prefix on the QName identifies the namespace for the custom
|
|
element.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
<p><code><svg:elementDef name="<em>localname</em>"><br />
|
|
...binding definition...<br />
|
|
</svg:elementDef></code></p>
|
|
|
|
<p>In RCC, the 'name' attribute provided the localname of the custom
|
|
element. The namespace for the custom element came from the
|
|
'namespace' attribute on the svg:extensionDefs element.</p>
|
|
|
|
</td>
|
|
|
|
<td>
|
|
<p><code><xbl:definition element="<em>QName</em>"><br />
|
|
...binding definition...<br />
|
|
</xbl:definition></code></p>
|
|
|
|
<p>In sXBL, the 'element' attribute identifies the custom element by a
|
|
QName. The namespace prefix on the QName identifies the namespace for
|
|
the custom element. The localname part of the QName completes the
|
|
identification of the custom element.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><em>N/A in RCC</em></p>
|
|
</td>
|
|
|
|
<td>
|
|
<p><code><xbl:definition element="<em>QName</em>"
|
|
ref="<em>xpointer</em>"/></code></p>
|
|
|
|
<p>In sXBL, it is possible to have the bound document associate custom
|
|
elements with per-element bindings using the xbl:definition element
|
|
with a 'ref' attribute. This allows the bound document (i.e., the
|
|
document which contains the custom elements) to dictate how to
|
|
associate its custom elements with the binding definitions (i.e.,
|
|
xbl:definition elements) found in another document.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><code><svg:defs>, <svg:script>,
|
|
<svg:handler></code></p>
|
|
|
|
<p>In RCC, svg:defs, svg:script, and svg:handler could appear in
|
|
various locations within RCC definitions.</p>
|
|
</td>
|
|
|
|
<td>
|
|
<p><code><svg:defs>, <svg:script>,
|
|
<svg:handler></code></p>
|
|
|
|
<p>In general, sXBL has the same rules. One addition with sXBL is the
|
|
xbl:handlerGroup element, described below.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><code><svg:prototype <em>various attributes</em>><br />
|
|
...initial shadow tree...<br />
|
|
</svg:prototype></code></p>
|
|
|
|
<p>In RCC, the svg:prototype contained an initial template for the
|
|
elements which were cloned into the shadow tree for the custom
|
|
element. The svg:prototype element was the root node of the set of
|
|
elements which were rendered and received events. Because
|
|
svg:prototype was part of the rendering and event pipelines, you were
|
|
able to attach styling properties, transforms, and event attributes
|
|
(the <em>various attributes</em> listed above) to the svg:prototype
|
|
element.</p>
|
|
|
|
</td>
|
|
|
|
<td>
|
|
<p><code><xbl:template><br />
|
|
...initial shadow tree...<br />
|
|
</xbl:template></code></p>
|
|
|
|
<p>sXBL is nearly the same. Just like svg:prototype, xbl:template
|
|
contained an initial template for the elements which are cloned into
|
|
the shadow tree for the custom element. xbl:template is the root node
|
|
of the xblShadowTree, in much the same way that svg:prototype element
|
|
was the root node of the shadow tree. However, one distinction is that
|
|
for rendering the xbl:template is flattened out of the rendering
|
|
pipeline. Therefore, it is not possible to attach styling properties,
|
|
transforms, and event attributes to an xbl:template; instead, you need
|
|
to include a container element such as an <svg:g> element in the
|
|
shadow tree if you need to attach styling properties, transforms, and
|
|
event attributes.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><code><svg:transformer>, <svg:param></code></p>
|
|
|
|
<p>The latest public draft of RCC described these two elements
|
|
(http://www.w3.org/TR/2004/WD-SVG12-20040510/#transformer-element),
|
|
but warned the community that there features are "...likely to be
|
|
removed from the next draft of SVG 1.2, due to the high burden on
|
|
implementation and the difficulty in optimization."</p>
|
|
|
|
</td>
|
|
|
|
<td>
|
|
<p><em>Not available</em></p>
|
|
|
|
<p>In the transition from RCC to sXBL, <svg:transformer>,
|
|
<svg:param> have been removed.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><code><svg:refContent [select="<em>xpath</em>"] <em>various
|
|
attributes</em>/></code></p>
|
|
|
|
<p>In RCC, the svg:refContent allowed the shadow content to
|
|
include-by-reference child elements of the custom element. The
|
|
svg:refContent element was a container node for the referenced
|
|
elements and was part of the rendering and event pipelines. Because
|
|
svg:refContent was part of the rendering and event pipelines, you were
|
|
able to attach styling properties, transforms, and event attributes
|
|
(the <em>various attributes</em> listed above) to the svg:refContent
|
|
element.</p>
|
|
</td>
|
|
|
|
<td>
|
|
<p><code><xbl:content [includes="<em>???</em>"]><br />
|
|
...backup content...<br />
|
|
|
|
</xbl:xbl:content></code></p>
|
|
|
|
<p>The most important aspects of sXBL are the same. Just like
|
|
svg:prototype, xbl:content does an include-by-reference to the child
|
|
elements of the custom element. The exact name of the attribute (e.g.,
|
|
'select' versus 'includes' is still under debate and the syntax of
|
|
this attribute (xpath? tagnames? CSS selector syntax?) is also still
|
|
under debate. The rules for what happens if there is a mismatch
|
|
between the bound element's content and the set of xbl:content
|
|
elements is also under debate. Finally, sXBL might include a backup
|
|
content feature that was not available in RCC.</p>
|
|
|
|
<p>One distinction with sXBL is that the xbl:content is flattened out
|
|
of the rendering pipeline. Therefore, it is not possible to attach
|
|
styling properties, transforms, and event attributes to an
|
|
xbl:content; instead, you need to include a parent container element
|
|
such as an <svg:g> element in the shadow tree if you need to
|
|
attach styling properties, transforms, and event attributes.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><code><svg:traitDef></code></p>
|
|
|
|
<p>In RCC, told the user agent about custom attributes to enable
|
|
animation of custom attributes and attachment of mutation event
|
|
listeners.</p>
|
|
</td>
|
|
|
|
<td>
|
|
|
|
<p><em>Moved out of RCC into SVG 1.2.</em></p>
|
|
|
|
<p>These features will be defined within the SVG 1.2 specification and
|
|
will not be part of the sXBL specification.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><code>SVGBindBegin, SVGBindEnd</code></p>
|
|
|
|
<p>In RCC, the SVGBindBegin event was raised just after cloning the
|
|
svg:prototype but before recursively applying RCC bindings to the
|
|
contents of the shadow tree. The SVGBindEnd event is raised after
|
|
recursively applying RCC bindings to the elements which were cloned
|
|
onto the shadow tree.</p>
|
|
</td>
|
|
|
|
<td>
|
|
<p><code>xbl:prebind, xbl:bound, xbl:unbinding</code></p>
|
|
|
|
<p>In sXBL, the binding events are in the XBL namespace
|
|
(http://www.w3.org/2004/xbl). xbl:prebind matches SVGBindBegin, and
|
|
xbl:bound matches SVGBindEnd. sXBL adds an xbl:unbinding event so that
|
|
script can be told when a binding is about to be unattached from a
|
|
custom element.</p>
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<p><em>RCC detailed processing model</em></p>
|
|
|
|
<p>The SVG 1.2 drafts were incomplete in various ways in describing the
|
|
complete details of the RCC processing model. Some aspects were
|
|
well-specified. Other aspects were designed but had not been committed
|
|
to the public specifications yet. Some aspects of the processing model
|
|
were not yet resolved.</p>
|
|
</td>
|
|
|
|
<td>
|
|
<p><em>sXBL detailed processing model</em></p>
|
|
|
|
<p>The sXBL specification is still under development. In general, the
|
|
detailed processing model for sXBL is highly consistent with the
|
|
detailed processing model for the parts of RCC that were described in
|
|
early SVG 1.2 drafts. Some aspects of the sXBL processing model are
|
|
still under discussion.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2 id="XBLComparison"><span class="secno">10. </span> Comparison of sXBL
|
|
to XBL1</h2>
|
|
|
|
<div class="issue"><!-- @@XXX -->
|
|
<p>Nigel McFarlane has kindly offered to write an appendix describing the
|
|
differences between Mozilla's XBL and the sXBL language defined by this
|
|
specification.</p>
|
|
</div>
|
|
|
|
<h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
|
|
|
|
<p>The membership of the XBL task force was drawn from the SVG and CSS
|
|
working groups, and consisted of L. David Baron, Robin Berjon, Alex
|
|
Danilo, Jon Ferraiolo, Darryl Fuller, Ian Hickson, David Hyatt, Dean
|
|
Jackson, Christophe Jolif, Chris Lilley, Antoine Quint, Peter Sorotokin.</p>
|
|
|
|
<h2 class="no-num" id="references">References</h2>
|
|
|
|
<dl>
|
|
<dt class="normref" id="refsCSS3UI"><strong>[CSS3UI]</strong></dt>
|
|
|
|
<dd>"CSS3 Basic User Interface Module", T. Çelik, editor, 11 May 2004.
|
|
Available at <a
|
|
href="http://www.w3.org/TR/css3-ui">http://www.w3.org/TR/css3-ui</a>.</dd>
|
|
|
|
<dt class="normref" id="refsDOM3CORE"><strong>[DOM3CORE]</strong></dt>
|
|
|
|
<dd>"Document Object Model (DOM) Level 3 Core Specification", A. Le Hors,
|
|
P. Le Hégaret <i>et. al.</i>, editors, 07 April 2004. Available at <a
|
|
href="http://www.w3.org/TR/DOM-Level-3-Core">http://www.w3.org/TR/DOM-Level-3-Core</a>.</dd>
|
|
|
|
<dt class="normref" id="refsDOM3EVENTS"><strong>[DOM3EVENTS]</strong></dt>
|
|
|
|
<dd>"Document Object Model (DOM) Level 3 Events Specification", P. Le
|
|
Hégaret, T. Pixley, editors, 07 November 2003. Available at <a
|
|
href="http://www.w3.org/TR/DOM-Level-3-Events">http://www.w3.org/TR/DOM-Level-3-Events</a>.</dd>
|
|
|
|
<dt class="normref" id="refsRFC2119"><strong>[RFC2119]</strong></dt>
|
|
|
|
<dd>"Key words for use in RFCs to Indicate Requirement Levels", S.
|
|
Bradner, March 1997. Available at <a
|
|
href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>.</dd>
|
|
|
|
<dt class="normref" id="refsSVG"><strong>[SVG11]</strong></dt>
|
|
|
|
<dd>"Scalable Vector Graphics (SVG) 1.1 Specification", J. Ferraiolo,
|
|
藤沢 淳, D. Jackson, editors, 14 January 2003.
|
|
Available at <a
|
|
href="http://www.w3.org/TR/SVG11/">http://www.w3.org/TR/SVG11/</a>.</dd>
|
|
|
|
<dt class="normref" id="refsXML"><strong>[XML10]</strong></dt>
|
|
|
|
<dd>"Extensible Markup Language (XML) 1.0 (Third Edition)", T. Bray, J.
|
|
Paoli, C.M. Sperberg-McQueen, E. Maler, F. Yergeau editors, 04 February
|
|
2004. Available at <a
|
|
href="http://www.w3.org/TR/REC-xml">http://www.w3.org/TR/REC-xml</a>.</dd>
|
|
|
|
<dt class="normref" id="refsXMLBASE"><strong>[XMLBASE]</strong></dt>
|
|
|
|
<dd>"XML Base", J. Marsh , editor, 20 December 2000. Available at <a
|
|
href="http://www.w3.org/TR/xmlbase/">http://www.w3.org/TR/xmlbase/</a>.</dd>
|
|
|
|
<dt class="normref" id="refsXMLNS"><strong>[XMLNS]</strong></dt>
|
|
|
|
<dd>"Namespaces in XML", T. Bray, D. Hollander, A. Layman, editors, 14
|
|
January 1999. Available at <a
|
|
href="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a>.</dd>
|
|
|
|
</dl>
|
|
</body>
|
|
</html>
|