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.
8408 lines
354 KiB
8408 lines
354 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
|
|
|
|
<html lang=en-US>
|
|
<head>
|
|
<title>XML Binding Language (XBL) 2.0</title>
|
|
|
|
<style type="text/css">
|
|
dt, dfn { font-weight: bold; font-style: normal; }
|
|
.main h4 { margin: 1.5em 0 0.75em 0; }
|
|
.main p { margin: 1em 0; }
|
|
.main dl, .main dd { margin-top: 0; margin-bottom: 0; }
|
|
.main dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
|
|
.main dd dt { margin-top: 0.25em; margin-bottom: 0; }
|
|
.main dd p { margin-top: 0; }
|
|
.main p + * > li, .main dd li { margin: 1em 0; }
|
|
img.extra { float: right; }
|
|
body ins, body del { display: block; }
|
|
body * ins, body * del { display: inline; }
|
|
pre, code { color: black; background: transparent; font-size: inherit; font-family: monospace; }
|
|
pre strong { color: purple; background: transparent; font: inherit; font-weight: bold; }
|
|
pre em { color: teal; background: transparent; font-weight: bolder; font-style: normal; }
|
|
pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
|
|
pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em; }
|
|
table { border-collapse: collapse; border-style: hidden hidden none hidden; }
|
|
table thead { border-bottom: solid; }
|
|
table tbody th:first-child { border-left: solid; }
|
|
table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
|
|
table td > ul:first-child:last-child { margin: 0; padding: 0; }
|
|
table td > ul:first-child:last-child li { margin: 0; padding: 0; list-style-position: inside; }
|
|
ul.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
|
|
ul.toc li ul { margin-bottom: 0.75em; }
|
|
ul.toc li ul li ul { margin-bottom: 0.25em; }
|
|
var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
|
|
@media screen { code { color: rgb(255, 69, 0); background: transparent; } }
|
|
code :link, code :visited { color: inherit; background: transparent; }
|
|
.example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin: 1em 0 1em 1em; padding-left: 1em; }
|
|
.issue, .big-issue { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
|
|
.issue > :first-child, .big-issue > :first-child { margin-top: 0; }
|
|
p .big-issue { line-height: 3em; }
|
|
.note { color: green; background: transparent; }
|
|
.note { font-family: sans-serif; }
|
|
p.note:before { content: 'Note: '; }
|
|
.warning { color: red; background: transparent; }
|
|
.warning:before { font-style: normal; }
|
|
p.warning:before { content: '\26A0 Warning! '; }
|
|
.note, .warning { font-weight: bolder; font-style: italic; padding: 0.5em 2em; }
|
|
.copyright { margin: 0.25em 0; }
|
|
</style>
|
|
<link href="http://www.w3.org/StyleSheets/TR/W3C-CR" rel=stylesheet
|
|
type="text/css">
|
|
|
|
<body>
|
|
<div class=head>
|
|
<p><a href="http://www.w3.org/"><img alt=W3C height=48
|
|
src="http://www.w3.org/Icons/w3c_home" width=72></a></p>
|
|
|
|
<h1 id=xml-binding>XML Binding Language (XBL) 2.0</h1>
|
|
|
|
<h2 class="no-num no-toc" id=w3c-candidate>W3C Candidate Recommendation 16
|
|
March 2007</h2>
|
|
|
|
<dl>
|
|
<dt>This Version:
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2007/CR-xbl-20070316/">http://www.w3.org/TR/2007/CR-xbl-20070316/</a>
|
|
|
|
<dt>Latest Version:
|
|
|
|
<dd><a href="http://www.w3.org/TR/xbl/">http://www.w3.org/TR/xbl/</a>
|
|
|
|
<dt>Previous Versions:
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2007/WD-xbl-20070117/">http://www.w3.org/TR/2007/WD-xbl-20070117/</a>
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2006/WD-xbl-20060907/">http://www.w3.org/TR/2006/WD-xbl-20060907/</a>
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2006/WD-xbl-20060619/">http://www.w3.org/TR/2006/WD-xbl-20060619/</a>
|
|
|
|
<dd><a
|
|
href="http://www.mozilla.org/projects/xbl/xbl.html">http://www.mozilla.org/projects/xbl/xbl.html</a>
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2001/NOTE-xbl-20010223/">http://www.w3.org/TR/2001/NOTE-xbl-20010223/</a>
|
|
|
|
<dt>Editor:
|
|
|
|
<dd><a href="mailto:ian@hixie.ch">Ian Hickson</a>, Google, Inc.
|
|
</dl>
|
|
|
|
<p class=copyright><a
|
|
href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
|
|
© 2006, 2007 <a href="http://www.w3.org/"><acronym title="World Wide
|
|
Web Consortium">W3C</acronym></a><sup>®</sup> (<a
|
|
href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute
|
|
of Technology">MIT</acronym></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>
|
|
|
|
<p class="alt copyright">The <a
|
|
href="http://www.mozilla.org/projects/xbl/xbl2.html">Mozilla version</a>
|
|
of this specification is available under a Creative Commons Attribution
|
|
Share-alike license.</p>
|
|
</div>
|
|
|
|
<hr>
|
|
|
|
<div class=main>
|
|
<h2 class="no-num no-toc" id=abstract>Abstract</h2>
|
|
|
|
<p>The XML Binding Language (XBL) describes the ability to associate
|
|
elements in a document with script, event handlers, CSS, and more complex
|
|
content models, which can be stored in another document. This can be used
|
|
to re-order and wrap content so that, for instance, simple HTML or XHTML
|
|
markup can have complex CSS styles applied without requiring that the
|
|
markup be polluted with multiple semantically neutral <code
|
|
title="">div</code> elements.</p>
|
|
|
|
<p>It can also be used to implement new DOM interfaces, and, in
|
|
conjunction with other specifications, enables arbitrary tag sets to be
|
|
implemented as widgets. For example, XBL could be used to implement the
|
|
form controls in XForms or HTML.</p>
|
|
|
|
<h2 class="no-num no-toc" 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>
|
|
<!-- required boilerplate -->
|
|
<!-- next few paragraphs give three required items: what this spec
|
|
is, where to send comments, whether the spec is unstable, and the
|
|
list of changes; wording is flexible -->
|
|
<!-- LC:
|
|
<p>This is the 15 March 2007 Last Call Working Draft of XBL 2.0. The last
|
|
call for comments resulted in a number of process clarifications,
|
|
and changes to various method and attribute names. This working
|
|
draft is intended to allow commentors on the previous draft to
|
|
verify their changes were correctly made before the specification
|
|
advances to Candidate Recommendation. The deadline for Last Call
|
|
comments is the 7 February 2007, after which time this draft
|
|
will progress to Candidate Recommendation stage unless major issues
|
|
have been found.</p>
|
|
-->
|
|
<!-- CR: -->
|
|
<p>This is the 16 March 2007 Candidate Recommendation of XBL 2.0.
|
|
Implementations are encouraged. This specification will remain at the
|
|
Candidate Recommendation stage until two complete and interoperable
|
|
implementations exist (and not before 1 September 2007). An
|
|
implementation will only be considered if it is publicly downloadable or
|
|
available through some other public point of sale mechanism, and is
|
|
intended for a wide audience and could be used on a daily basis. To be
|
|
"complete and interoperable", an implementation must pass every test in a
|
|
comprehensive test suite of every normative requirement of this
|
|
specification.</p>
|
|
|
|
<p>Publication as a Candidate Recommendation does not imply endorsement by
|
|
the W3C Membership. At the time of publication, there was no
|
|
implementation report. A future version of this specification, which will
|
|
include fixes based on implementation feedback, will include a link to a
|
|
test suite and an implementation report.</p>
|
|
|
|
<p>If you wish to make comments regarding this document, please send them
|
|
to <a href="mailto:dev-tech-xbl@mozilla.org">dev-tech-xbl@mozilla.org</a>
|
|
(<a href="https://lists.mozilla.org/listinfo/dev-tech-xbl">subscribe</a>,
|
|
<a
|
|
href="http://groups.google.com/group/mozilla.dev.tech.xbl">archives</a>)
|
|
or <a href="mailto:public-appformats@w3.org">public-appformats@w3.org</a>
|
|
(<a
|
|
href="mailto:public-appformats-request@w3.org?subject=subscribe">subscribe</a>,
|
|
<a
|
|
href="http://lists.w3.org/Archives/Public/public-appformats/">archives</a>).
|
|
All feedback is welcome. The editor guarantees that all feedback sent to
|
|
the above lists will receive responses before this specification advances
|
|
to the next stage of the W3C process.</p>
|
|
|
|
<p>The editor's copy of this specification is <a
|
|
href="http://dev.w3.org/cvsweb/~checkout~/2006/xbl2/Overview.html?content-type=text/html">available
|
|
in W3C CVS</a>. A <a href="http://dev.w3.org/cvsweb/2006/xbl2/">detailed
|
|
list of changes</a> is available from the CVS server.</p>
|
|
<!-- next four paragraphs describe the history; optional -->
|
|
<p>This specification is a (non-backwards-compatible) revision of
|
|
Mozilla's XBL 1.0 language, originally developed at Netscape in 2000, and
|
|
originally implemented in the Gecko rendering engine. <a
|
|
href="#refsXBL10">[XBL10]</a></p>
|
|
|
|
<p>This specification was developed by the Mozilla Foundation and its
|
|
contributors, in conjunction with individuals from Opera Software ASA,
|
|
Google, Inc, and Apple Computer, Inc, to address problems found in the
|
|
original language and to allow for implementation in a broader range of
|
|
Web browsers.</p>
|
|
|
|
<p>This document is also based, in part, on work done in the W3C's
|
|
Bindings Task Force. However, no text from that collaboration, other than
|
|
that written by the aforementioned contributors, remains in this
|
|
specification. Inspiration was similarly taken from other efforts, such
|
|
as HTML Components. <a href="#refsHTC">[HTC]</a></p>
|
|
|
|
<p>Although they have had related histories, this specification is
|
|
separate from the W3C's "sXBL" drafts, and is not compatible with them.
|
|
(The two efforts use different namespaces, for one.)</p>
|
|
<!-- next two paragraphs are legal things and w3c process -->
|
|
<p>While the body of this specification was created outside the W3C, the
|
|
W3C <a href="http://www.w3.org/2006/appformats/">Web Application Formats
|
|
Working Group</a> is now guiding this specification along the W3C
|
|
Recommendation track.</p>
|
|
<!-- this statement is required
|
|
but the wording doesn't matter -->
|
|
<p>This document was produced by a group operating under the <a
|
|
href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
|
|
2004 W3C Patent Policy</a>. W3C maintains a <a
|
|
href="http://www.w3.org/2004/01/pp-impl/38483/status"
|
|
rel=disclosure>public list of any patent disclosures</a> made in
|
|
connection with the deliverables of the group; that page also includes
|
|
instructions for disclosing a patent. An individual who has actual
|
|
knowledge of a patent which the individual believes contains <a
|
|
href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
|
|
Claim(s)</a> must 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>
|
|
<!-- required boilerplate -->
|
|
<h3 class="no-num no-toc" id=feedback>Feedback requests</h3>
|
|
|
|
<p>While feedback is welcomed on all aspects of this specification,
|
|
especially from implementors and authors using XBL on the Web, feedback
|
|
is especially requested on two contentious issues.</p>
|
|
|
|
<p>The first concerns ID attributes. This specification defines an
|
|
attribute <code title=attr-id><a href="#id13">id</a></code> for uniquely
|
|
identifying elements in XBL. There exists a specification for a global <a
|
|
href="http://www.w3.org/TR/xml-id/"><code title="">xml:id</code></a>
|
|
attribute, which can also be used with XBL. Feedback is requested from
|
|
implementors and authors using XBL on the Web regarding whether XBL
|
|
should instead require that authors use the <code title="">xml:id</code>
|
|
attribute, and forbid the use of the <code title=attr-id><a
|
|
href="#id13">id</a></code> attribute on XBL elements.</p>
|
|
|
|
<p>The second contentious issue regards an intentional limitation: unless
|
|
an element is explicitly bound to a binding that provides access to its
|
|
shadow tree or its bound element, there is no easy way to get access to
|
|
them from script running outside the element's bindings. This is a
|
|
feature that may be introduced in a future version, but it is not clear
|
|
how much need there is for it.</p>
|
|
|
|
<p>If you have any opinions or experience regarding these issues or any
|
|
others, please send them to <a
|
|
href="mailto:dev-tech-xbl@mozilla.org">dev-tech-xbl@mozilla.org</a> (<a
|
|
href="https://lists.mozilla.org/listinfo/dev-tech-xbl">subscribe</a>, <a
|
|
href="http://groups.google.com/group/mozilla.dev.tech.xbl">archives</a>)
|
|
or <a href="mailto:public-appformats@w3.org">public-appformats@w3.org</a>
|
|
(<a
|
|
href="mailto:public-appformats-request@w3.org?subject=subscribe">subscribe</a>,
|
|
<a
|
|
href="http://lists.w3.org/Archives/Public/public-appformats/">archives</a>).</p>
|
|
|
|
<h2 class="no-num no-toc" id=table>Table of Contents</h2>
|
|
<!--begin-toc-->
|
|
<ul class=toc>
|
|
<li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
|
|
<ul class=toc>
|
|
<li><a href="#relationship"><span class=secno>1.1. </span>Relationship
|
|
to XBL1</a>
|
|
|
|
<li><a href="#relationship0"><span class=secno>1.2. </span>Relationship
|
|
to XSLT</a>
|
|
|
|
<li><a href="#terminology"><span class=secno>1.3. </span>Terminology
|
|
and Conventions</a>
|
|
|
|
<li><a href="#conformance"><span class=secno>1.4.
|
|
</span>Conformance</a>
|
|
<ul class=toc>
|
|
<li><a href="#error"><span class=secno>1.4.1. </span>Error
|
|
Handling</a>
|
|
|
|
<li><a href="#attributes"><span class=secno>1.4.2. </span><dfn
|
|
id=attributes17 title=selector>Attributes Containing
|
|
Selectors</dfn></a>
|
|
|
|
<li><a href="#attributes0"><span class=secno>1.4.3. </span><dfn
|
|
id=attributes18 title=space-separated>Attributes Containing
|
|
Space-Separated Values</dfn></a>
|
|
|
|
<li><a href="#attributes1"><span class=secno>1.4.4. </span><dfn
|
|
id=attributes19 title="valid MIME type">Attributes Containing MIME
|
|
Types</dfn></a>
|
|
|
|
<li><a href="#attributes2"><span class=secno>1.4.5. </span><dfn
|
|
id=attributes20 title=URI>Attributes Containing URIs</dfn></a>
|
|
|
|
<li><a href="#attributes3"><span class=secno>1.4.6. </span>Attributes
|
|
Containing Keywords</a>
|
|
|
|
<li><a href="#extension"><span class=secno>1.4.7. </span>Extension
|
|
Mechanisms</a>
|
|
|
|
<li><a href="#feature"><span class=secno>1.4.8. </span>Feature
|
|
Strings for the DOM and SVG</a>
|
|
</ul>
|
|
|
|
<li><a href="#security"><span class=secno>1.5. </span>Security
|
|
Concerns</a>
|
|
</ul>
|
|
|
|
<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><code>xbl</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-binding"><span class=secno>2.2. </span>The <dfn
|
|
id=binding7><code>binding</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-implementation"><span class=secno>2.3. </span>The
|
|
<dfn id=implementation><code>implementation</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-template"><span class=secno>2.4. </span>The <dfn
|
|
id=template><code>template</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-content"><span class=secno>2.5. </span>The <dfn
|
|
id=content><code>content</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-inherited"><span class=secno>2.6. </span>The <dfn
|
|
id=inherited><code>inherited</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-xblattr"><span class=secno>2.7. </span>The <dfn
|
|
id=xblattr title=attr-attr><code>xbl:attr</code></dfn> Attribute</a>
|
|
|
|
<li><a href="#the-xblpseudo"><span class=secno>2.8. </span>The <dfn
|
|
id=xblpseudo title=attr-pseudo><code>xbl:pseudo</code></dfn>
|
|
Attribute</a>
|
|
|
|
<li><a href="#the-div"><span class=secno>2.9. </span>The <dfn
|
|
id=div><code>div</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-handlers"><span class=secno>2.10. </span>The <dfn
|
|
id=handlers><code>handlers</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-handler"><span class=secno>2.11. </span>The <dfn
|
|
id=handler><code>handler</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-resources"><span class=secno>2.12. </span>The <dfn
|
|
id=resources0><code>resources</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-style"><span class=secno>2.13. </span>The <dfn
|
|
id=style0><code>style</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-prefetch"><span class=secno>2.14. </span>The <dfn
|
|
id=prefetch><code>prefetch</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-script"><span class=secno>2.15. </span>The <dfn
|
|
id=script0><code>script</code></dfn> Element</a>
|
|
|
|
<li><a href="#the-id"><span class=secno>2.16. </span>The <dfn id=id
|
|
title=attr-id><code>id</code></dfn> Attribute of XBL Elements</a>
|
|
</ul>
|
|
|
|
<li><a href="#binding"><span class=secno>3. </span><dfn
|
|
id=binding8>Binding Attachment and Detachment</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#the-bindings-are-ready"><span class=secno>3.1.
|
|
</span><dfn id=the-bindings-are-ready0>The Bindings-Are-Ready
|
|
State</dfn></a>
|
|
|
|
<li><a href="#attachment"><span class=secno>3.2. </span><dfn
|
|
id=attachment3 title="attachment using binding">Attachment using <code
|
|
title=binding><binding element=""></code></dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#importing"><span class=secno>3.2.1. </span><dfn
|
|
id=importing0 title=import>Importing Binding Documents</dfn></a>
|
|
</ul>
|
|
|
|
<li><a href="#attachment0"><span class=secno>3.3. </span>Attachment
|
|
using CSS</a>
|
|
<ul class=toc>
|
|
<li><a href="#the-binding0"><span class=secno>3.3.1. </span>The
|
|
'<code title="binding property">binding</code>' Property</a>
|
|
|
|
<li><a href="#processing"><span class=secno>3.3.2. </span>Processing
|
|
Model</a>
|
|
|
|
<li><a href="#examples"><span class=secno>3.3.3. </span>Examples</a>
|
|
</ul>
|
|
|
|
<li><a href="#attachment1"><span class=secno>3.4. </span>Attachment
|
|
using the DOM</a>
|
|
|
|
<li><a href="#binding0"><span class=secno>3.5. </span><dfn
|
|
id=binding9>Binding Attachment Model</dfn></a>
|
|
|
|
<li><a href="#handling"><span class=secno>3.6. </span><dfn
|
|
id=handling1>Handling Insertion and Removal from the
|
|
Document</dfn></a>
|
|
|
|
<li><a href="#binding1"><span class=secno>3.7. </span><dfn
|
|
id=binding10>Binding Inheritance</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#explicit"><span class=secno>3.7.1. </span><dfn
|
|
id=explicit0>Explicit Inheritance</dfn></a>
|
|
|
|
<li><a href="#implicit"><span class=secno>3.7.2. </span><dfn
|
|
id=implicit0>Implicit Inheritance</dfn></a>
|
|
|
|
<li><a href="#mixing"><span class=secno>3.7.3. </span>Mixing Implicit
|
|
and Explicit Inheritance</a>
|
|
</ul>
|
|
|
|
<li><a href="#views"><span class=secno>3.8. </span>Views and
|
|
Attachment</a>
|
|
|
|
<li><a href="#attachment2"><span class=secno>3.9. </span>Attachment
|
|
During Document Load</a>
|
|
|
|
<li><a href="#binding2"><span class=secno>3.10. </span><dfn
|
|
id=binding11>Binding Detachment Model</dfn></a>
|
|
</ul>
|
|
|
|
<li><a href="#shadow"><span class=secno>4. </span><dfn id=shadow3>Shadow
|
|
Content</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#rules"><span class=secno>4.1. </span><dfn id=rules1>Rules
|
|
for Shadow Content Generation</dfn></a>
|
|
|
|
<li><a href="#rules0"><span class=secno>4.2. </span><dfn
|
|
id=rules2>Rules for Shadow Content Destruction</dfn></a>
|
|
|
|
<li><a href="#attribute"><span class=secno>4.3. </span><dfn
|
|
id=attribute0>Attribute Forwarding</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#forwarding"><span class=secno>4.3.1. </span>Forwarding
|
|
to and from text nodes</a>
|
|
|
|
<li><a href="#forwarding0"><span class=secno>4.3.2. </span>Forwarding
|
|
language metadata</a>
|
|
|
|
<li><a href="#error0"><span class=secno>4.3.3. </span>Error
|
|
handling</a>
|
|
|
|
<li><a href="#type-specifiers"><span class=secno>4.3.4. </span>Type
|
|
specifiers</a>
|
|
|
|
<li><a href="#dynamic"><span class=secno>4.3.5. </span>Dynamic
|
|
changes</a>
|
|
|
|
<li><a href="#how-attribute"><span class=secno>4.3.6. </span>How
|
|
Attribute Forwarding Affects the Shadow Tree</a>
|
|
</ul>
|
|
|
|
<li><a href="#processing0"><span class=secno>4.4. </span><dfn
|
|
id=processing1>Processing <code>content</code> Elements</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#how-nodes"><span class=secno>4.4.1. </span>How Nodes
|
|
are Distributed</a>
|
|
|
|
<li><a href="#when-nodes"><span class=secno>4.4.2. </span>When Nodes
|
|
Are Redistributed</a>
|
|
</ul>
|
|
|
|
<li><a href="#the-final"><span class=secno>4.5. </span>The <dfn
|
|
id=final>Final Flattened Tree</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#terminology0"><span class=secno>4.5.1.
|
|
</span>Terminology</a>
|
|
</ul>
|
|
|
|
<li><a href="#handling0"><span class=secno>4.6. </span><dfn
|
|
id=handling2>Handling DOM Changes</dfn></a>
|
|
|
|
<li><a href="#shadow0"><span class=secno>4.7. </span>Shadow Content and
|
|
CSS</a>
|
|
<ul class=toc>
|
|
<li><a href="#selectors"><span class=secno>4.7.1. </span><dfn
|
|
id=selectors0>Selectors and Shadow Scopes</dfn></a>
|
|
|
|
<li><a href="#css-property"><span class=secno>4.7.2. </span><dfn
|
|
id=css-property0>CSS Property Inheritance and Rendering</dfn></a>
|
|
|
|
<li><a href="#the-bound-element"><span class=secno>4.7.3. </span>The
|
|
<code>:bound-element</code> Pseudo-Class</a>
|
|
|
|
<li><a href="#matching"><span class=secno>4.7.4. </span><dfn
|
|
id=matching0>Matching Pseudo-Elements</dfn></a>
|
|
</ul>
|
|
|
|
<li><a href="#shadow1"><span class=secno>4.8. </span>Shadow Content and
|
|
<code>xml:base</code></a>
|
|
|
|
<li><a href="#shadow2"><span class=secno>4.9. </span><dfn id=shadow4
|
|
title="Semantics of non-XBL elements in XBL contexts">Shadow Content
|
|
and Other Things</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#general"><span class=secno>4.9.1. </span>General
|
|
Rules</a>
|
|
|
|
<li><a href="#style"><span class=secno>4.9.2. </span><dfn
|
|
id=style1>Style Blocks</dfn></a>
|
|
|
|
<li><a href="#script"><span class=secno>4.9.3. </span><dfn
|
|
id=script1>Script Blocks</dfn></a>
|
|
|
|
<li><a href="#event"><span class=secno>4.9.4. </span><dfn
|
|
id=event4>Event Handler Blocks</dfn></a>
|
|
|
|
<li><a href="#html-forms"><span class=secno>4.9.5. </span>HTML
|
|
Forms</a>
|
|
|
|
<li><a href="#svg"><span class=secno>4.9.6. </span>SVG</a>
|
|
</ul>
|
|
|
|
<li><a href="#binding3"><span class=secno>4.10. </span><dfn
|
|
id=binding12>Binding Style Sheets</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#styleSummary"><span class=secno>4.10.1. </span>Summary
|
|
of styling rules</a>
|
|
</ul>
|
|
</ul>
|
|
|
|
<li><a href="#binding4"><span class=secno>5. </span><dfn
|
|
id=binding13>Binding Implementations</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#the-xblimplementation"><span class=secno>5.1. </span>The
|
|
<code>XBLImplementation</code> Interface</a>
|
|
|
|
<li><a href="#the-xblimplementationlist"><span class=secno>5.2.
|
|
</span>The <code>XBLImplementationList</code> Interface</a>
|
|
|
|
<li><a href="#accessing"><span class=secno>5.3. </span>Accessing
|
|
Binding Implementations</a>
|
|
|
|
<li><a href="#ecmascript"><span class=secno>5.4. </span><dfn
|
|
id=ecmascript0>ECMAScript Bindings</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#compiling"><span class=secno>5.4.1. </span><dfn
|
|
id=compiling0>Compiling ECMAScript Bindings</dfn></a>
|
|
|
|
<li><a href="#invoking"><span class=secno>5.4.2. </span>Invoking
|
|
Methods on an ECMAScript Implementation Object</a>
|
|
</ul>
|
|
</ul>
|
|
|
|
<li><a href="#event0"><span class=secno>6. </span><dfn id=event5>Event
|
|
Handlers</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#event1"><span class=secno>6.1. </span><dfn
|
|
id=event6>Event Forwarding</dfn></a>
|
|
|
|
<li><a href="#registering"><span class=secno>6.2. </span><dfn
|
|
id=registering0>Registering Event Handlers with the
|
|
<code>handler</code> Element</dfn></a>
|
|
|
|
<li><a href="#mouse"><span class=secno>6.3. </span><dfn id=mouse0>Mouse
|
|
Event Handler Filters</dfn></a>
|
|
|
|
<li><a href="#key-event"><span class=secno>6.4. </span><dfn
|
|
id=key-event0>Key Event Handler Filters</dfn></a>
|
|
|
|
<li><a href="#text-input"><span class=secno>6.5. </span><dfn
|
|
id=text-input0>Text Input Event Handler Filters</dfn></a>
|
|
|
|
<li><a href="#mutation"><span class=secno>6.6. </span><dfn
|
|
id=mutation0>Mutation Event Handler Filters</dfn></a>
|
|
|
|
<li><a href="#modifiers"><span class=secno>6.7. </span><dfn
|
|
id=modifiers0>Modifiers</dfn></a>
|
|
|
|
<li><a href="#event2"><span class=secno>6.8. </span><dfn
|
|
id=event7>Event Flow and Targeting Across Shadow Scopes</dfn></a>
|
|
|
|
<li><a href="#the-default"><span class=secno>6.9. </span><dfn
|
|
id=the-default0 title="default phase">The Default Phase</dfn></a>
|
|
|
|
<li><a href="#the-focus"><span class=secno>6.10. </span>The
|
|
<code>focus</code>, <code>DOMFocusIn</code>, <code>blur</code>, and
|
|
<code>DOMFocusOut</code> Events</a>
|
|
|
|
<li><a href="#the-mouseover"><span class=secno>6.11. </span>The
|
|
<code>mouseover</code> and <code>mouseout</code> Events</a>
|
|
|
|
<li><a href="#event3"><span class=secno>6.12. </span><dfn
|
|
id=event8>Event Handlers Implemented in ECMAScript</dfn></a>
|
|
</ul>
|
|
|
|
<li><a href="#dom-interfaces"><span class=secno>7. </span><dfn
|
|
id=dom-interfaces0>DOM Interfaces</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#the-documentxbl"><span class=secno>7.1. </span>The
|
|
<code>DocumentXBL</code> Interface</a>
|
|
|
|
<li><a href="#the-elementxbl"><span class=secno>7.2. </span>The
|
|
<code>ElementXBL</code> Interface</a>
|
|
<ul class=toc>
|
|
<li><a href="#scoping"><span class=secno>7.2.1. </span>Scoping and
|
|
Access Using the DOM</a>
|
|
</ul>
|
|
|
|
<li><a href="#the-xblcontentelement"><span class=secno>7.3. </span>The
|
|
<code>XBLContentElement</code> Interface</a>
|
|
|
|
<li><a href="#the-xbltemplateelement"><span class=secno>7.4. </span>The
|
|
<code>XBLTemplateElement</code> Interface</a>
|
|
|
|
<li><a href="#the-eventxbl"><span class=secno>7.5. </span>The
|
|
<code>EventXBL</code> Interface</a>
|
|
</ul>
|
|
|
|
<li><a href="#resources"><span class=secno>8. </span>Resources</a>
|
|
<ul class=toc>
|
|
<li><a href="#loading"><span class=secno>8.1. </span><dfn
|
|
id=loading2>Loading External Resources</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#binding5"><span class=secno>8.1.1. </span>Binding
|
|
Documents</a>
|
|
|
|
<li><a href="#external"><span class=secno>8.1.2. </span>External
|
|
Resources</a>
|
|
</ul>
|
|
|
|
<li><a href="#loading0"><span class=secno>8.2. </span><dfn
|
|
id=loading3>Loading and Running Scripts</dfn></a>
|
|
<ul class=toc>
|
|
<li><a href="#xforms"><span class=secno>8.2.1. </span>XForms
|
|
Actions</a>
|
|
|
|
<li><a href="#scripting"><span class=secno>8.2.2. </span>Scripting
|
|
Model</a>
|
|
</ul>
|
|
|
|
<li><a href="#loading1"><span class=secno>8.3. </span><dfn
|
|
id=loading4>Loading Style Sheets</dfn></a>
|
|
|
|
<li><a href="#interpretation"><span class=secno>8.4. </span><dfn
|
|
id=interpretation0>Interpretation of URIs to XBL bindings</dfn></a>
|
|
</ul>
|
|
|
|
<li><a href="#summaries"><span class=secno>9. </span>Summaries of
|
|
Elements, Attributes, and Events</a>
|
|
<ul class=toc>
|
|
<li><a href="#elements"><span class=secno>9.1. </span>Elements and
|
|
Attributes</a>
|
|
|
|
<li><a href="#events"><span class=secno>9.2. </span>Events</a>
|
|
|
|
<li><a href="#implementations"><span class=secno>9.3.
|
|
</span>Implementations</a>
|
|
</ul>
|
|
|
|
<li class=no-num><a href="#acknowledgments">Acknowledgments</a>
|
|
|
|
<li class=no-num><a href="#references">References</a>
|
|
</ul>
|
|
<!--end-toc-->
|
|
<hr>
|
|
|
|
<h2 id=introduction><span class=secno>1. </span>Introduction</h2>
|
|
|
|
<p>This specification defines the XML Binding Language and some supporting
|
|
DOM interfaces and CSS features. XBL is a mechanism for overriding the
|
|
standard presentation and interactive behavior of particular elements by
|
|
attaching those elements to appropriate definitions, called <a
|
|
href="#binding16" title=binding>bindings</a>. Bindings can be attached to
|
|
elements using either CSS, the DOM, or by declaring, in XBL, that
|
|
elements matching a specific selector are implemented by a particular
|
|
binding. The element that the binding is attached to, called the <a
|
|
href="#bound">bound element</a>, acquires the new behavior and
|
|
presentation specified by the binding.</p>
|
|
|
|
<p>Bindings can contain <a href="#handlers0" title=handlers>event
|
|
handlers</a> that watch for events on the bound element, an <a
|
|
href="#implementation0">implementation</a> of new methods and properties
|
|
that become accessible from the bound element, <a href="#shadow5">shadow
|
|
content</a> that is inserted underneath the bound element, and associated
|
|
<a href="#resources1">resources</a> such as scoped style sheets and
|
|
precached images, sounds, or videos.</p>
|
|
|
|
<p><span title="Except if script invoked by XBL explicitly changes the
|
|
original DOM.">XBL cannot be used to give a document new
|
|
semantics.</span> 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 id=intro-example>
|
|
<p>To help readers understand how certain features can be used, this
|
|
specification includes some examples.</p>
|
|
|
|
<p>In these examples, a long ellipsis ("...") is used to indicate elided
|
|
content that would be present in a full example but has been removed for
|
|
clarity.</p>
|
|
|
|
<p>Here we see a simple binding being used to reorder content in an HTML
|
|
page, so that the element with <code>class="nav"</code> is positioned
|
|
before the element with <code>class="main"</code>. CSS associated with
|
|
the binding is then used to position the two elements.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="nav-then-main">
|
|
<template>
|
|
<div id="wrapper">
|
|
<div id="col2"><content includes=".nav"/></div>
|
|
<div id="col1"><content includes=".main"/></div>
|
|
</div>
|
|
</template>
|
|
<resources>
|
|
<style>
|
|
#wrapper { display: table-row; }
|
|
#col1, #col2 { display: table-cell; }
|
|
</style>
|
|
</resources>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>The HTML page associated with such a binding might look like:</p>
|
|
|
|
<pre><!DOCTYPE HTML>
|
|
<html>
|
|
<head>
|
|
<title>Demo</title>
|
|
<link rel="stylesheet" href="example.css">
|
|
</head>
|
|
<body>
|
|
<div class="main">
|
|
<h1>Demo</h1>
|
|
...
|
|
</div>
|
|
<div class="nav">
|
|
<p><a href="http://example.com/">Home</a></p>
|
|
...
|
|
</div>
|
|
</body>
|
|
</html></pre>
|
|
|
|
<p>The CSS stylesheet referred to from that document would include
|
|
various stylistic rules, and would in particular contain a link to the
|
|
XBL file, making it apply to the <code>body</code> element so as to
|
|
reorder the two child elements:</p>
|
|
|
|
<pre>/* Colors and Fonts */
|
|
h1 { font: 2em sans-serif; color: green; background: white; }
|
|
...
|
|
|
|
/* Reorder content */
|
|
body { binding: url(example.xml#nav-then-main); }</pre>
|
|
|
|
<p>The result of all the above is equivalent to the result one would get
|
|
if one simply placed the <code title="">div</code> element with
|
|
<code>class="nav"</code> before the <code title="">div</code> element
|
|
with <code>class="main"</code>. However, the effect is achieved without
|
|
needing any changes to the markup. This allows the same markup to be
|
|
given different presentations dynamically. It also allows changes to be
|
|
applied across entire sites by merely changing global stylesheet and
|
|
binding files, much as CSS can be used to change the layout and
|
|
presentation of a site even without XBL.</p>
|
|
</div>
|
|
|
|
<div class=example id=simple-shadow-example>
|
|
<p>Here is another example, this time of an inaccessible implementation
|
|
of the proposed HTML5 <code title="">details</code> disclosure element:
|
|
it opens and closes when clicked, and reflects its current state in the
|
|
element's "<code>open</code>" attribute.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding element="details">
|
|
<template>
|
|
<div>
|
|
<div><content includes="legend:first-child">Details...</content></div>
|
|
<div state="hidden" id="container"><content/></div>
|
|
</div>
|
|
</template>
|
|
<handlers>
|
|
<handler event="click" phase="default-action">
|
|
this.open = !this.open;
|
|
</handler>
|
|
<handler event="DOMAttrModified" attr-name="open" attr-change="addition" phase="target">
|
|
this.shadowTree.getElementById('container').setAttribute('state', 'visible');
|
|
</handler>
|
|
<handler event="DOMAttrModified" attr-name="open" attr-change="removal" phase="target">
|
|
this.shadowTree.getElementById('container').setAttribute('state', 'hidden');
|
|
</handler>
|
|
</handlers>
|
|
<implementation>
|
|
({
|
|
get open() { return this.boundElement.hasAttribute('open'); },
|
|
set open(val) {
|
|
if (val)
|
|
this.boundElement.setAttribute('open', 'open');
|
|
else
|
|
this.boundElement.removeAttribute('open');
|
|
return this.open;
|
|
},
|
|
})
|
|
</implementation>
|
|
<resources>
|
|
<style>
|
|
#container[state=hidden] { display: none; }
|
|
</style>
|
|
</resources>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<p class=note>Since the examples are all untested (there are no XBL2
|
|
implementations at the time of writing), it is quite possible that they
|
|
have errors. Please report any errors you think you see, so that we can
|
|
correct the examples.</p>
|
|
|
|
<h3 id=relationship><span class=secno>1.1. </span>Relationship to XBL1</h3>
|
|
|
|
<p>This specification is not backwards compatible with XBL1.</p>
|
|
|
|
<p>There are numerous changes. However, of particular importance to
|
|
readers familiar with XBL1, there have been some changes to the element
|
|
names. In particular, the XBL1 element <code title="">content</code> is
|
|
now called <code><a href="#template0">template</a></code>, and the XBL1
|
|
element <code title="">children</code> is now called <code><a
|
|
href="#content0">content</a></code>.</p>
|
|
|
|
<h3 id=relationship0><span class=secno>1.2. </span>Relationship to XSLT</h3>
|
|
|
|
<p>This specification has a similar scope to XSLT. The main differences
|
|
are:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>XSLT operates on a static DOM, permanently replacing that DOM for
|
|
rendering. XBL, on the other hand, transparently transforms the DOM for
|
|
rendering while leaving the underlying structure intact, and
|
|
dynamically reflects changes to the underlying DOM in the transformed
|
|
rendering.
|
|
|
|
<li>
|
|
<p>XSLT allows any arbitrary transformation to be performed. XBL shadow
|
|
trees, on the other hand, only support reordering of the bound
|
|
element's child nodes and interleaving of those explicit children with
|
|
shadow content. Arbitrary transformations are not possible in XBL while
|
|
retaining the transparent nature of XBL's shadow tree processing.
|
|
</ul>
|
|
|
|
<p>In addition, XBL can be used for component creation, which is not
|
|
covered by XSLT.</p>
|
|
|
|
<h3 id=terminology><span class=secno>1.3. </span>Terminology and
|
|
Conventions</h3>
|
|
|
|
<p>An <dfn id=xbl-user title="XBL user agents">XBL user agent</dfn> is an
|
|
implementation that attempts to support this specification.</p>
|
|
|
|
<p>A <dfn id=binding14 title="">binding</dfn> is the definition of
|
|
behavior that can be applied to an element so as to augment its
|
|
presentation.</p>
|
|
|
|
<p>The namespace of all the <dfn id=xbl-elements0>XBL elements</dfn> and
|
|
<dfn id=xbl-global>XBL global attributes</dfn> must be: <code
|
|
class=uri>http://www.w3.org/ns/xbl</code>
|
|
|
|
<p>An <dfn id=xbl-document>XBL document</dfn> is an XML document that has
|
|
the <code><a href="#xbl0">xbl</a></code> element at its root.</p>
|
|
|
|
<p>A <dfn id=non-xbl>non-XBL document</dfn> is an XML document whose root
|
|
element is from a namespace other than XBL (e.g. XHTML). A non-XBL
|
|
document can include XBL, if the other languages involved allow it.</p>
|
|
|
|
<p>An <dfn id=xbl-subtree title="XBL subtrees">XBL subtree</dfn> is a
|
|
subtree in an XML document, 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. XBL subtrees can stand alone in <a
|
|
href="#xbl-document" title="XBL document">XBL documents</a>, or can be
|
|
included in <a href="#non-xbl" title="non-XBL document">non-XBL
|
|
documents</a>.</p>
|
|
|
|
<p>The term <dfn id=binding15>binding document</dfn> is used to mean
|
|
either an <a href="#xbl-document">XBL document</a> or a <a
|
|
href="#non-xbl">non-XBL document</a> containing one or more <span
|
|
title="XBL subtree">XBL subtrees</span>.</p>
|
|
|
|
<div class=example id=date-example>
|
|
<p>In the following XHTML example, the XBL subtree is the portion of the
|
|
markup that is emphasized. It is in a non-XBL document, since the root
|
|
element is an XHTML element.</p>
|
|
|
|
<pre><html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Demo</title>
|
|
<strong><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<script><![CDATA[
|
|
function fmt(n) {
|
|
if (n < 10)
|
|
return "0" + n;
|
|
else
|
|
return n;
|
|
}
|
|
]]></script>
|
|
<binding element=".date">
|
|
<implementation>
|
|
({
|
|
xblBindingAttached: function() {
|
|
var tm = /(\d\d\d\d)-(\d\d)-(\d\d) (\d\d):(\d\d) UTC$/.exec(this.boundElement.textContent);
|
|
var date = new Date();
|
|
date.setUTCFullYear(parseInt(tm[1], 10));
|
|
date.setUTCMonth(parseInt(tm[2], 10) - 1);
|
|
date.setUTCDate(parseInt(tm[3], 10));
|
|
date.setUTCHours(parseInt(tm[4], 10));
|
|
date.setUTCMinutes(parseInt(tm[5], 10));
|
|
date.setUTCSeconds(0);
|
|
this.boundElement.textContent = date.getFullYear() + "-" +
|
|
fmt(date.getMonth() + 1) + "-" +
|
|
fmt(date.getDate()) + " " +
|
|
fmt(date.getHours()) + ":" +
|
|
fmt(date.getMinutes()) + " LT";
|
|
this.boundElement.title = "Adjusted to local time zone"
|
|
},
|
|
})
|
|
</implementation>
|
|
</binding>
|
|
</xbl></strong>
|
|
</head>
|
|
<body>
|
|
<h1>Demo</h1>
|
|
<p class="date">2006-08-10 18:40 UTC</p>
|
|
<p>...</p>
|
|
</body>
|
|
</html></pre>
|
|
|
|
<p>(As an aside, the binding defined in this example causes elements with
|
|
<code>class="date"</code> to have their content parsed into a UTC date
|
|
and converted into a local time. The binding mutates the original DOM to
|
|
do this, and it doesn't reflect any dynamic changes made to the
|
|
element's content; there are better, albeit slightly more involved, ways
|
|
of achieving the same effect that don't have these problems.)</p>
|
|
</div>
|
|
|
|
<p>A <dfn id=bound>bound element</dfn> is an XML or HTML element to which
|
|
a binding has been applied.</p>
|
|
|
|
<p class=example>In the <a href="#date-example">example above</a>, the
|
|
first <code>p</code> element is the <em><a href="#bound">bound
|
|
element</a></em>.</p>
|
|
|
|
<p>A <dfn id=bound0>bound document</dfn> is an XML or HTML document
|
|
containing one or more <a href="#bound" title="bound element">bound
|
|
elements</a>.</p>
|
|
|
|
<p class=example>In the <a href="#date-example">example at the top of this
|
|
section</a>, the document is both the <em><a href="#binding15">binding
|
|
document</a></em> (because it contains the definition of the binding),
|
|
and the <em><a href="#bound0">bound document</a></em> (because it
|
|
contains the affected <em><a href="#bound">bound element</a></em>). In
|
|
the <a href="#intro-example">example in the introduction section</a>, the
|
|
HTML file is the <em><a href="#bound0">bound document</a></em>, and the
|
|
XBL file is the <em><a href="#binding15">binding document</a></em>.</p>
|
|
|
|
<p>In this specification, the term <dfn id=in-error>in error</dfn>,
|
|
typically used of an element or attribute, means that the element,
|
|
attribute, or other construct is not conformant according to the rules of
|
|
this specification. Rules for exactly how the construct must be treated
|
|
when it is in error are always given when the term is used. Typically
|
|
this will involve <dfn id=ignoring title=ignore>ignoring</dfn> the
|
|
erroneous nodes, meaning the UA must, <em>for the purposes of XBL
|
|
processing</em>, act as if those nodes were absent. UAs must not,
|
|
however, remove such nodes from the DOM in order to ignore them, nor
|
|
should it change what DOM interfaces those nodes implement. The nodes
|
|
retain all their non-XBL semantics.</p>
|
|
|
|
<p>UAs should report all errors to users, although they may do this in an
|
|
unobtrusive way, for example in an error console.</p>
|
|
|
|
<p>In addition to the error handling rules given in this specification,
|
|
UAs may abort all processing when encountering an error.</p>
|
|
|
|
<p class=note>Aborting is only likely to be a viable error handling
|
|
mechanism in controlled environments, e.g. in conformance checkers. Web
|
|
browsers are expected to use the error recovery mechanisms described in
|
|
this specification, not abort.</p>
|
|
|
|
<p>A <dfn id=correct title=correct>correct</dfn> element, attribute,
|
|
value, or binding is one which is not <a href="#in-error">in error</a>.</p>
|
|
|
|
<div class=example id=correct-vs-error-example>
|
|
<p>The following sample XBL document is <a href="#in-error">in error</a>
|
|
because the <code><a href="#script2">script</a></code> element in XBL is
|
|
only allowed as a child of the <code><a href="#xbl0">xbl</a></code>
|
|
element:</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="demo">
|
|
<strong><script>
|
|
// This example is <em><a href="#in-error">in error</a></em>.
|
|
// You are not allowed to put a <code><a href="#script2">script</a></code> element inside
|
|
// a <code><a href="#binding16">binding</a></code> element, only inside an <code><a href="#xbl0">xbl</a></code> element.
|
|
// This is because scripts evaluate in the scope of the
|
|
// entire XBL document, and are therefore not associated
|
|
// with a particular binding.
|
|
function life() {
|
|
return 42;
|
|
}
|
|
</script></strong>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>The correct way of doing this would be:</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<script>
|
|
// This example is <a href="#correct">correct</a>.
|
|
function life() {
|
|
return 42;
|
|
}
|
|
</script>
|
|
<binding id="demo">
|
|
<!-- Now you can see that this binding actually does nothing. -->
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<p>The term "<dfn id=semantics>semantics</dfn>" is used to refer to the
|
|
<em>intrinsic meaning</em> or processing model of elements, attributes,
|
|
events, and DOM interface members. Semantics are defined by
|
|
specifications; for example, this specification defines the semantics of
|
|
XBL elements.</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/ns/xbl"
|
|
-->xmlns:xbl="http://www.w3.org/ns/xbl"
|
|
xmlns:xforms="http://www.w3.org/2002/xforms"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:html="http://www.w3.org/1999/xhtml"</pre>
|
|
|
|
<p>When this specification refers to <em>elements in a namespace</em>, it
|
|
does not exclude elements in <em>no</em> namespace; the null namespace is
|
|
considered a namespace like any other for the purposes of XBL processing.</p>
|
|
|
|
<p>All element names, attribute names, and attribute values in XBL are
|
|
case sensitive, with the exception of attribute values defined by other
|
|
specifications (those have the sensitivity defined by those other
|
|
specifications).</p>
|
|
|
|
<p>An <dfn id=xml-mime>XML MIME type</dfn> is <code>text/xml</code>,
|
|
<code>application/xml</code>, or any MIME type ending with the string
|
|
<code>+xml</code> (ignoring any MIME parameters).</p>
|
|
|
|
<p>The terms "<dfn id=author>author style sheets</dfn>", "<dfn
|
|
id=user-style>user style sheets</dfn>", "<dfn id=user-agent>user agent
|
|
style sheets</dfn>", and "<dfn id=pseudo-element>pseudo-element</dfn>"
|
|
are used as defined by the CSS specifications. <a
|
|
href="#refsCSS21">[CSS21]</a></p>
|
|
|
|
<p>The term "<dfn id=qname>QName</dfn>" is used as defined by the
|
|
Namespaces in XML specification. <a href="#refsXMLNS">[XMLNS]</a></p>
|
|
|
|
<p>The term "<dfn id=view>view</dfn>" is used as defined by the DOM2 Views
|
|
specification. <a href="#refsDOM2VIEWS">[DOM2VIEWS]</a></p>
|
|
|
|
<h3 id=conformance><span class=secno>1.4. </span>Conformance</h3>
|
|
|
|
<p>As well as sections marked as non-normative, all diagrams, examples,
|
|
and notes in this specification are non-normative. Everything else in
|
|
this specification is normative.</p>
|
|
|
|
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
|
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the
|
|
normative parts of this document are to be interpreted as described in
|
|
RFC2119. For readability, these words do not appear in all uppercase
|
|
letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
|
|
|
|
<p>There are two classes of products that can claim conformance to this
|
|
implementation: <a href="#xbl-subtree">XBL subtrees</a>, and <a
|
|
href="#xbl-user">XBL user agents</a>.</p>
|
|
|
|
<p><a href="#xbl-subtree">XBL subtrees</a> must satisfy the constraints
|
|
described in this specification in order to be considered conformant.</p>
|
|
|
|
<p>Products that generate XBL subtrees cannot claim conformance to this
|
|
specification, though they can claim to only produce XBL subtrees that
|
|
themselves are conformant to this specification.</p>
|
|
|
|
<p><a href="#xbl-user">XBL user agents</a> must behave as described by
|
|
this specification in order to be considered conformant, even when faced
|
|
with non-conformant XBL subtrees.</p>
|
|
|
|
<p>User agents may optimize any algorithm given in this specification, so
|
|
long as the end result is indistinguishable from the result that would be
|
|
obtained by the specification's algorithms. (The algorithms in this
|
|
specification are generally written with more concern for clarity than
|
|
over efficiency.)</p>
|
|
|
|
<p id=dom-basis>This specification is defined in terms of the DOM. The
|
|
language in this specification assumes that the user agent expands all
|
|
entity references, and therefore does not include entity reference nodes
|
|
in the DOM. If user agents do include entity reference nodes in the DOM,
|
|
then user agents must handle them as if they were replaced by their DOM
|
|
replacement values when implementing this specification.</p>
|
|
|
|
<p class=example>For example, if a requirement talks about an element's
|
|
child text nodes, then any text nodes that are children of an entity
|
|
reference that is a child of that element would be used as well.</p>
|
|
|
|
<h4 id=error><span class=secno>1.4.1. </span>Error Handling</h4>
|
|
|
|
<p>This specification describes the rules for processing of XBL elements
|
|
and related features, whether they are used in a conformant manner or
|
|
not. Conformant implementations, therefore, will interoperably handle any
|
|
content, whether valid or not.</p>
|
|
|
|
<h4 id=attributes><span class=secno>1.4.2. </span><dfn id=attributes21
|
|
title=selector>Attributes Containing Selectors</dfn></h4>
|
|
|
|
<p>The <code title=attr-binding-element><a
|
|
href="#element">element</a></code> attribute of the <code><a
|
|
href="#binding16">binding</a></code> element and the <code
|
|
title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute of the <code><a href="#content0">content</a></code> element, if
|
|
specified, must have their values parsed according to the rules in the
|
|
Selectors specification. <a href="#refsSELECTORS">[SELECTORS]</a></p>
|
|
|
|
<p class=note>This specification does not specify what level of Selectors
|
|
support is required.</p>
|
|
|
|
<p>Namespace prefixes can be used with selectors. In XBL attributes that
|
|
take selectors, the namespace prefixes that may be used are the prefixes
|
|
that are in scope using the <code>xmlns:*</code> syntax. User agents must
|
|
use the XML namespace prefixes in scope on the attribute's element when
|
|
parsing selectors with namespace prefixes. The default namespace in
|
|
selectors in XBL attributes is always unbound. <a
|
|
href="#refsXMLNS">[XMLNS]</a></p>
|
|
|
|
<p class=note>The "xml" prefix is defined to always be declared (and bound
|
|
to the <code>http://www.w3.org/XML/1998/namespace</code> namespace), as
|
|
is the "xmlns" prefix (which is bound to
|
|
<code>http://www.w3.org/2000/xmlns/</code>).</p>
|
|
|
|
<p>Selectors are case-insensitive, but namespace prefixes are
|
|
case-sensitive. Thus, there could be multiple namespace prefixes declared
|
|
that match a particular namespace prefix as used in a selector. User
|
|
agents must act as if all namespace prefixes in scope were lexically
|
|
sorted by Unicode codepoint, with the first namespace prefix of each
|
|
group of namespace prefixes differing only by case (using case folding as
|
|
defined by Unicode) being the one assumed to be in scope for the purposes
|
|
of selector matching. <a href="#refsUNICODE">[UNICODE]</a></p>
|
|
|
|
<div class=example id=selectors-example>
|
|
<p>The following excerpt from an XBL document defines a binding that is
|
|
bound to elements declaring links (e.g. the <code title="">a</code>
|
|
element in HTML).</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding element=":link, :visited">
|
|
...
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>The following excerpt defines a binding bound to any element in the
|
|
<code>http://example.com/</code> namespace that is the child of an
|
|
element in the <code>http://www.example.net/</code> namespace with the
|
|
name <code>parent</code>. (Note that the <code>></code> character
|
|
does not have to be escaped.)</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl"
|
|
xmlns:eg1="http://www.example.net/"
|
|
xmlns:eg2="http://example.com/">
|
|
<binding element="eg1|parent > eg2|*">
|
|
...
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>Finally this third example defines a binding that matches elements
|
|
with the name <code>blockquote</code>, regardless of what namespace they
|
|
are in. If it is known that the binding document is only ever going to
|
|
be used from documents that use one namespace, for example if the
|
|
bindings are always to be imported into HTML documents, then it is
|
|
easier to just specify the local name (as in this example) and ignore
|
|
the namespaces.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding element="blockquote">
|
|
...
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h4 id=attributes0><span class=secno>1.4.3. </span><dfn id=attributes22
|
|
title=space-separated>Attributes Containing Space-Separated Values</dfn></h4>
|
|
|
|
<p>Some attributes are defined as taking space-separated values. The list
|
|
of values for such attributes must be obtained by taking the attribute's
|
|
value, replacing any sequences of U+0009, U+000A, U+000D, and U+0020
|
|
characters (in any order) with a single U+0020 SPACE character, dropping
|
|
any leading or trailing U+0020 SPACE character, and then chopping the
|
|
resulting string at each occurrence of a U+0020 character, dropping that
|
|
character in the process.</p>
|
|
|
|
<p>A space-separated attribute whose value is the empty string, or which
|
|
consists of only U+0009, U+000A, U+000D, and U+0020 characters, has no
|
|
values.</p>
|
|
|
|
<div class=example id=space-separated-example>
|
|
<p>In the attribute <code>button="1 2"</code>, the values are "1" and
|
|
"2".</p>
|
|
|
|
<p>In the attribute
|
|
<code>class=" key - note - rocks"</code>,
|
|
there are five keywords: "key", "note", "rocks", and two occurrences of
|
|
the single-character keyword "-".</p>
|
|
</div>
|
|
|
|
<h4 id=attributes1><span class=secno>1.4.4. </span><dfn id=attributes23
|
|
title="valid MIME type">Attributes Containing MIME Types</dfn></h4>
|
|
|
|
<p>Some attributes are defined as containing MIME types. A valid MIME type
|
|
is one that matches the production for <code
|
|
title="">valid-MIME-type</code> in the following EBNF:</p>
|
|
|
|
<pre>valid-MIME-type := type "/" subtype *(";" parameter)</pre>
|
|
|
|
<p>...where the <code title="">type</code>, <code title="">subtype</code>,
|
|
and <code title="">parameter</code> tokens are those defined in RFC 2045.
|
|
<a href="#refsRFC2045">[RFC2045]</a></p>
|
|
|
|
<h4 id=attributes2><span class=secno>1.4.5. </span><dfn id=attributes24
|
|
title=URI>Attributes Containing URIs</dfn></h4>
|
|
|
|
<p>Some attributes, pseudo-attributes, and method arguments are defined as
|
|
specifying URIs. Such attributes must have values that match the <code
|
|
title="">URI</code> token of RFC 3986 or the <code title="">IRI</code>
|
|
token of RFC 3987. If they do not, they are <a href="#in-error">in
|
|
error</a> (though the processing of erroneous URIs varies depending on
|
|
the context). <a href="#refsRFC3986">[RFC3986]</a> <a
|
|
href="#refsRFC3987">[RFC3987]</a></p>
|
|
|
|
<h4 id=attributes3><span class=secno>1.4.6. </span>Attributes Containing
|
|
Keywords</h4>
|
|
|
|
<p>Certain attributes are defined as requiring certain values, e.g. <code
|
|
title="">true</code> or <code title="">false</code>. For such attributes,
|
|
the values must be specified exactly, in the case given in this
|
|
specification, and with no leading or trailing whitespace.
|
|
Implementations must only perform literal comparisons, and must not use
|
|
case-insensitive comparisons nor trim attribute values before comparison.</p>
|
|
|
|
<h4 id=extension><span class=secno>1.4.7. </span>Extension Mechanisms</h4>
|
|
|
|
<p>XBL2 does not have an extension mechanism; implementations that
|
|
recognize elements in the XBL namespace that aren't part of this
|
|
specification, or who recognise attributes that have no namespace, that
|
|
are on elements in the XBL namespace, and that aren't part of this
|
|
specification, are non-conforming. If UAs support features in other
|
|
namespaces that affect the XBL processing model in a way that contradicts
|
|
this specification, then they are not conforming either.</p>
|
|
|
|
<h4 id=feature><span class=secno>1.4.8. </span>Feature Strings for the DOM
|
|
and SVG</h4>
|
|
|
|
<p>XBL2 user agents must recognize the string "XBL" as being a DOM feature
|
|
corresponding to support of XBL2 and its corresponding DOM APIs. Support
|
|
for this specification must be treated as support for versions "1.0" and
|
|
"2.0" of the "XBL" feature in terms of versions for the <code
|
|
title="">hasFeature()</code> DOM Core method.</p>
|
|
|
|
<p>XBL2 user agents that also implement SVG must recognize the following
|
|
string as being a language extension URI for the purposes of SVG <code
|
|
title="">requiredExtensions</code> evaluation:
|
|
<code>http://www.w3.org/ns/xbl#v2</code></p>
|
|
|
|
<h3 id=security><span class=secno>1.5. </span>Security Concerns</h3>
|
|
|
|
<p><em>This section is non-normative.</em></p>
|
|
|
|
<p>XBL raises a number of security concerns.</p>
|
|
|
|
<p><strong>Data theft</strong>: A naïve implementation of XBL would
|
|
allow any document to bind to bindings defined in any other document, and
|
|
(since referencing a binding allows full access to that binding
|
|
document's DOM) thereby allow access to any remote file, including those
|
|
on intranet sites or on authenticated extranet sites.</p>
|
|
|
|
<p>XBL itself does not do anything to prevent this. However, it is
|
|
strongly suggested that an access control mechanism (such as that
|
|
described in <a href="#refsACCESSCONTROL">[ACCESSCONTROL]</a>) be used to
|
|
prevent such cross-domain accesses unless the remote site has allowed
|
|
accesses.</p>
|
|
|
|
<p><strong>Privilege escalation</strong>: In conjunction with data theft,
|
|
there is the concern that a page could bind to a binding document on a
|
|
remote site, and then use the privileges of that site to obtain further
|
|
information. XBL prevents this by requiring that the bindings all run in
|
|
the security context of the <em><a href="#bound0">bound
|
|
document</a></em>, so that accessing a remote binding document does not
|
|
provide the bound document with any extra privileges on the remote
|
|
domain.</p>
|
|
|
|
<p><strong>Cookie theft</strong>: Related to privilege escalation is the
|
|
risk that once an access-controlled binding document hosted on a remote
|
|
site has been loaded, authentication information stored in cookies for
|
|
that domain would become accessible to the bound document. XBL prevents
|
|
this by requiring that the <code>cookie</code> attribute on the
|
|
<code>DocumentWindow</code> interface be set to null.</p>
|
|
|
|
<p><strong>Secure bindings</strong>: Using XBL for bindings that need
|
|
access to the local filesystem, e.g. for implementing File Upload form
|
|
controls, is not yet handled by this specification. However, a future
|
|
version will provide a secure way to define an XBL binding that can be
|
|
used to implement privileged mechanisms that can then be used by other
|
|
bindings to provide such controls.</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 element is found inside an element other than those listed
|
|
under the "Expected contexts" list in the definitions below, it is <a
|
|
href="#in-error">in error</a>. When an XBL element has a child node that
|
|
does not satisfy the "Expected children" list in its definition (for
|
|
instance because it is the wrong node type, wrong element type, or
|
|
because too many elements of its type preceded it), the <em>child</em> is
|
|
<a href="#in-error">in error</a>. In both cases, being <a
|
|
href="#in-error">in error</a> means that the UA must, for the purposes of
|
|
XBL evaluation, treat the XBL subtree as it would if the erroneous node
|
|
and all its descendants were not present in the DOM.</p>
|
|
|
|
<p>However, non-XBL elements retain their semantics, even when considered
|
|
to be <a href="#in-error">in error</a> for the purposes of XBL.</p>
|
|
|
|
<p>Regardless of the requirements of the last few paragraphs and of the
|
|
"expected children" lines, comment nodes, and text and CDATA nodes
|
|
containing only whitespace characters, may always be given as children of
|
|
XBL elements.</p>
|
|
|
|
<p>For cases where attributes on XBL elements do not conform to this
|
|
specification or (for namespaced attributes) to another specification,
|
|
and for cases where attributes in the XBL namespace are found on elements
|
|
other than those listed as their "Expected element" in the definitions
|
|
below, the error handling is similar: the attributes must be considered
|
|
to be <a href="#in-error">in error</a> and the UA must <a
|
|
href="#ignoring">ignore</a> them, meaning that the presence of these
|
|
non-conforming attributes in no way affects the XBL processing.</p>
|
|
|
|
<p>Further error handling rules for more specific cases are given where
|
|
appropriate.</p>
|
|
|
|
<p>XBL user agents that support CSS should act as if they had the
|
|
following rules in their UA style sheet:</p>
|
|
|
|
<pre>@namespace xbl url(http://www.w3.org/ns/xbl);
|
|
xbl|* { display: none; }
|
|
xbl|div { display: block; }
|
|
</pre>
|
|
|
|
<p>XBL user agents that do not support CSS should not render the XBL
|
|
elements other than the <code><a href="#div0">div</a></code> element,
|
|
which they should render as a paragraph-like element.</p>
|
|
|
|
<p class=note>The following sections describe the <em>content model</em>
|
|
of XBL elements, but not their actual processing model. The processing
|
|
model for XBL is described in later sections.</p>
|
|
|
|
<h3 id=the-xbl><span class=secno>2.1. </span>The <dfn
|
|
id=xbl0><code>xbl</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected contexts:
|
|
|
|
<dd>In an <a href="#xbl-document">XBL document</a>, none (this is the
|
|
root element).
|
|
|
|
<dd>In a <a href="#non-xbl">non-XBL document</a>, any non-XBL element
|
|
whose specification allows the <code><a href="#xbl0">xbl</a></code>
|
|
element as a child.
|
|
|
|
<dt>Expected children (in any order):
|
|
|
|
<dd><code><a href="#binding16">binding</a></code>: zero or more.
|
|
|
|
<dd><code><a href="#script2">script</a></code>: zero or more.
|
|
|
|
<dd>Any non-XBL element.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#xbl0">xbl</a></code> element is the root
|
|
element of all XBL subtrees.</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes4>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id0 title=attr-xbl-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=script-type title=attr-xbl-script-type>script-type</dfn>
|
|
|
|
<dd>The <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute specifies the MIME
|
|
type of the scripting language used by all bindings and XBL script
|
|
blocks in the XBL subtree. The value must be a <a
|
|
href="#attributes23">valid MIME type</a>. If the attribute is not
|
|
specified, the default language is ECMAScript<!-- XXX MIME type?
|
|
-->.
|
|
<a href="#refsECMA262">[ECMA262]</a>
|
|
|
|
<dt><dfn id=style-type title=attr-xbl-style-type>style-type</dfn>
|
|
|
|
<dd>The <code title=attr-xbl-style-type><a
|
|
href="#style-type">style-type</a></code> attribute specifies the MIME
|
|
type of the styling language used by all bindings and XBL style blocks
|
|
in the XBL subtree. The value must be a <a href="#attributes23">valid
|
|
MIME type</a>. If the attribute is not specified, the default language
|
|
is CSS (<code class=mimetype>text/css</code>).
|
|
</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 <a href="#in-error">in error</a> and must then <a
|
|
href="#ignoring">ignore</a> them, meaning those elements must never be
|
|
considered to declare any bindings.</p>
|
|
|
|
<p class=example>For example, conforming UAs will never bind elements to
|
|
bindings defined by <code><a href="#binding16">binding</a></code>
|
|
elements that have two <code><a href="#xbl0">xbl</a></code> ancestors.</p>
|
|
|
|
<p>Similarly, XBL elements (other than the <code><a
|
|
href="#xbl0">xbl</a></code> element itself) that do not have a <a
|
|
href="#correct">correct</a> <code><a href="#xbl0">xbl</a></code> element
|
|
as an ancestor are <a href="#in-error">in error</a> too, and UAs must <a
|
|
href="#ignoring">ignore</a> them.</p>
|
|
|
|
<p class=example>For example, conformant UAs will never bind elements to
|
|
bindings defined by <code><a href="#binding16">binding</a></code>
|
|
elements that have no <code><a href="#xbl0">xbl</a></code> ancestors at
|
|
all.</p>
|
|
|
|
<p>The same does not apply to the <code title=attr-xbl-style-type><a
|
|
href="#style-type">style-type</a></code> and <code
|
|
title=attr-xbl-script-type><a href="#script-type">script-type</a></code>
|
|
attributes. If the UA does not support the specified styling language (or
|
|
has styling disabled), it must still apply bindings as appropriate; only
|
|
<code><a href="#style2">style</a></code> blocks must be ignored.
|
|
Similarly, if the UA does not support the specified scripting language
|
|
(or has scripting disabled), it must still apply bindings as appropriate;
|
|
only <code><a href="#script2">script</a></code>, <code><a
|
|
href="#handler0">handler</a></code> and <code><a
|
|
href="#implementation0">implementation</a></code> sections must be
|
|
ignored.</p>
|
|
|
|
<p class=note>The empty string is not a special value for these
|
|
attributes. Setting the <code title=attr-xbl-style-type><a
|
|
href="#style-type">style-type</a></code> attribute to the empty string,
|
|
e.g., will result in all <code><a href="#style2">style</a></code> blocks
|
|
being ignored, since the empty string is not a valid MIME type that the
|
|
UA supports.</p>
|
|
|
|
<div class=example id=xbl-element-example>
|
|
<p>The following document defines two bindings, one using Perl as the
|
|
scripting language and the other using JavaScript. The second one
|
|
extends the first one. (This example assumes that
|
|
<code>text/x-perl</code> refers to Perl. Note that this specification
|
|
doesn't actually define how Perl-based bindings are to be supported by
|
|
the UA; the code below assumes that an <code><a
|
|
href="#implementation0">implementation</a></code> element takes an
|
|
anonymous Perl package and blesses a hash to that package for each
|
|
binding, but this is nothing but conjecture.)</p>
|
|
|
|
<pre><root>
|
|
<xbl xmlns="http://www.w3.org/ns/xbl"
|
|
script-type="text/x-perl">
|
|
<binding id="validityImplementor">
|
|
<implementation>
|
|
use strict;
|
|
use vars qw(@ISA);
|
|
@ISA = qw(XBLImplementation);
|
|
sub validate {
|
|
my $self = shift;
|
|
my $data = $self->{boundElement}->getAttribute('value');
|
|
my $pattern = $self->{boundElement}->getAttribute('pattern');
|
|
return $data =~ m/^(?:$pattern)$/s;
|
|
}
|
|
</implementation>
|
|
</binding>
|
|
</xbl>
|
|
<xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="validityClassifier" extends="#validityImplementor">
|
|
<handlers>
|
|
<handler event="change">
|
|
if (this.baseBinding.validate())
|
|
this.boundElement.className = 'valid';
|
|
else
|
|
this.boundElement.className = 'invalid';
|
|
</handler>
|
|
</handlers>
|
|
</binding>
|
|
</xbl>
|
|
</root></pre>
|
|
|
|
<p>(What these bindings do is somewhat boring. The first does nothing
|
|
except expose a "validate()" method that returns true if the contents of
|
|
the element's <code title="">value</code> attribute matches the regular
|
|
expression in the element's <code title="">pattern</code> attribute. The
|
|
second makes the binding call this method every time the <code
|
|
title="">change</code> event bubbles through the element, and changes
|
|
the element's <code title="">class</code> attribute based on the return
|
|
value.)</p>
|
|
</div>
|
|
|
|
<h3 id=the-binding><span class=secno>2.2. </span>The <dfn
|
|
id=binding16><code>binding</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#xbl0">xbl</a></code>
|
|
|
|
<dt>Expected children (in any order):
|
|
|
|
<dd><code><a href="#implementation0">implementation</a></code>: zero or
|
|
one.
|
|
|
|
<dd><code><a href="#template0">template</a></code>: zero or one.
|
|
|
|
<dd><code><a href="#handlers0">handlers</a></code>: zero or one.
|
|
|
|
<dd><code><a href="#resources1">resources</a></code>: zero or one.
|
|
|
|
<dd>Any non-XBL element
|
|
</dl>
|
|
|
|
<div class=note>
|
|
<p>The <code><a href="#binding16">binding</a></code> element describes a
|
|
single XBL binding that adds presentation and interactive behavior to
|
|
XML or HTML elements. Each binding has these optional components:</p>
|
|
|
|
<p><em title=implementation><a href="#implementation0">Methods,
|
|
Properties, and Fields</a></em>: A binding can specify additional
|
|
methods that can be invoked on the element. It can also specify
|
|
additional properties and fields that can be retrieved or set on the
|
|
element. In this way the functionality of the bound element becomes
|
|
extensible. (See: <a href="#binding23">binding implementations</a>.)</p>
|
|
|
|
<p><em><a href="#template0">Template</a></em>: The optional <code><a
|
|
href="#template0">template</a></code> defines the initial <em><a
|
|
href="#shadow5">shadow content</a></em> for the bound element.</p>
|
|
|
|
<p><em title=handlers><a href="#handlers0">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, and mutation events on the bound
|
|
element and its descendants. (See: <a href="#event11">event
|
|
handlers</a>.)</p>
|
|
|
|
<p><em><a href="#resources1">Resources</a></em>: A binding can list style
|
|
sheets that are scoped to the bound element, and images, sounds, videos,
|
|
or other files that a user agent can pre-cache in order to improve
|
|
performance. (See: <a href="#binding22">binding style sheets</a>,
|
|
<span>prefetching resources</span>.)</p>
|
|
|
|
<p>Bindings can 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-binding-element><a href="#element">element</a></code>
|
|
attribute.</p>
|
|
</div>
|
|
|
|
<p>In addition to the above, the <code><a
|
|
href="#binding16">binding</a></code> element's child nodes may include
|
|
any element outside the XBL namespace. These are handled as they would be
|
|
in any other context, and are <a href="#ignoring"
|
|
title=ignore>ignored</a> by the XBL processing model.</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes5>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id1 title=attr-binding-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=extends title=attr-binding-extends>extends</dfn>
|
|
|
|
<dd>The <code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code> attribute is used to specify the <a
|
|
href="#attributes24">URI</a> of a binding that this binding inherits
|
|
from. (See: <a href="#interpretation1">interpretation of URIs to XBL
|
|
bindings</a>.) If the URI is <a href="#in-error">in error</a> or does
|
|
not refer to another binding, the UA must <a href="#ignoring">ignore</a>
|
|
it, meaning that this binding does not explicitly inherit from another
|
|
binding. (See: <a href="#explicit2">explicit inheritance</a>.) Only one
|
|
URI can be specified.
|
|
|
|
<dt><dfn id=element title=attr-binding-element>element</dfn>
|
|
|
|
<dd>
|
|
<p>This attribute, if specified, must contain a <a
|
|
href="#attributes21">selector</a>. All elements in the binding
|
|
document, and in any documents that <span title=importing>import</span>
|
|
the binding document, that <a href="#selectors1" title="selectors and
|
|
shadow scopes">match the given selector</a>, must be bound to the
|
|
binding defined by this <code><a href="#binding16">binding</a></code>
|
|
element. (The element's own shadow tree, if any, must not be taken into
|
|
account when determining if it matches a selector for the purposes of
|
|
this attribute.)</p>
|
|
|
|
<p>If an <code title=attr-binding-element><a
|
|
href="#element">element</a></code> attribute contains an invalid
|
|
selector, it is <a href="#in-error">in error</a> and must be <a
|
|
href="#ignoring" title=ignore>ignored</a>, meaning that while the
|
|
binding is still parsed and may be referenced using other attachment
|
|
mechanisms, the binding is not attached to any element by its <code
|
|
title=attr-binding-element><a href="#element">element</a></code>
|
|
attribute, as if the attribute had simply been omitted.</p>
|
|
</dd>
|
|
<!--
|
|
|
|
"secure" - for secure bindings. These have no generated content,
|
|
no event handlers. Only an implementation. They execute in a
|
|
different scope.
|
|
|
|
-->
|
|
</dl>
|
|
|
|
<div class=note>
|
|
<p>The <code><a href="#binding16">binding</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>
|
|
|
|
<p>Sending markup that does not have well-defined semantics over the
|
|
network is bad practice. XBL is intended to be used to augment the user
|
|
experience, for instance by providing better quality widgets or
|
|
enhancing aesthetics. If the document being sent is <em>unusable</em>
|
|
without XBL, then XBL is being abused.</p>
|
|
</div>
|
|
|
|
<div class=example id=binding-element-example>
|
|
<p>This binding extends a binding defined in an external file. The
|
|
binding in the other file defines a <code title="">value</code>
|
|
property, and fires events when that property is changed. <em>This</em>
|
|
binding just implements a check box that all <code>checkbox</code>
|
|
elements in the <code>http://ui.example.com/</code> namespace will be
|
|
bound to.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl"
|
|
xmlns:ui="http://ui.example.com/">
|
|
<binding element="ui|checkbox" id="checkbox"
|
|
extends="http://www.example.org/resources/ui-core.xml#valuedControl">
|
|
<template>
|
|
<div id="wrapper">
|
|
<div id="control"/>
|
|
<div id="label"><content/></div>
|
|
</div>
|
|
</template>
|
|
<resources>
|
|
<style>
|
|
#wrapper > div { display: inline-block; }
|
|
</style>
|
|
</resources>
|
|
<handlers>
|
|
<handler event="click" phase="default-action">
|
|
if (this.baseBinding.value == 'on')
|
|
this.baseBinding.value = 'off';
|
|
else
|
|
this.baseBinding.value = 'on';
|
|
</handler>
|
|
<handler event="change" phase="target">
|
|
if (this.baseBinding.value == 'on')
|
|
this.shadowTree.getElementById('control').textContent = '☑';
|
|
else
|
|
this.shadowTree.getElementById('control').textContent = '☐';
|
|
</handler>
|
|
</handlers>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-implementation><span class=secno>2.3. </span>The <dfn
|
|
id=implementation0><code>implementation</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#binding16">binding</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>If the element has no <code title=attr-implementation-src><a
|
|
href="#src">src</a></code> attribute: depends on the scripting language.
|
|
|
|
<dd>If the element does have a <code title=attr-implementation-src><a
|
|
href="#src">src</a></code> attribute: none.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a
|
|
href="#implementation0">implementation</a></code> element describes a set
|
|
of methods, properties, and fields that are attached to the bound
|
|
element. Once the binding is attached, these methods, properties, and
|
|
fields can be invoked directly from the bound element.</p>
|
|
|
|
<p>The <code><a href="#implementation0">implementation</a></code> element,
|
|
if present, must either contain code in the language specified by the XBL
|
|
subtree's <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute, or have a <code
|
|
title=attr-implementation-src><a href="#src">src</a></code> attribute
|
|
that points to a resource containing code in the language specified by
|
|
the <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute. The syntax and
|
|
semantics of this code depend on the specific language. This
|
|
specification defines the semantics for <span title="ECMAScript binding
|
|
for XBL">ECMAScript implementations</span>. (See: <a
|
|
href="#binding23">binding implementations</a>.)</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes6>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id2 title=attr-implementation-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=src title=attr-implementation-src>src</dfn>
|
|
|
|
<dd>The <code title=attr-implementation-src><a href="#src">src</a></code>
|
|
attribute specifies the <a href="#attributes24">URI</a> to a resource of
|
|
the type given by the XBL subtree's <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute. If the attribute
|
|
is specified, the contents of the element must be ignored (even if the
|
|
resource could not be fetched or was of the wrong type). (See: <a
|
|
href="#binding23">binding implementations</a>.)
|
|
</dl>
|
|
|
|
<p>If an <code><a href="#implementation0">implementation</a></code>
|
|
element is marked (via the <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute of the <code><a
|
|
href="#xbl0">xbl</a></code> element) as being in a language that the UA
|
|
does not support, then the UA must <a href="#ignoring">ignore</a> it.
|
|
Similarly, if the <code><a
|
|
href="#implementation0">implementation</a></code> element points (using
|
|
the <code title=attr-implementation-src><a href="#src">src</a></code>
|
|
attribute) to a resource that is either unavailable, or not of the type
|
|
specified by the <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute of the <code><a
|
|
href="#xbl0">xbl</a></code> element (or implied by its absence), then it
|
|
is <a href="#in-error">in error</a> and the UA must <a
|
|
href="#ignoring">ignore</a> it. In both cases, "ignoring it" means it
|
|
must not be used as an implementation definition for any binding.</p>
|
|
|
|
<p>How UAs must handle nodes inside <code><a
|
|
href="#implementation0">implementation</a></code> elements depends on the
|
|
language used. (See: <a href="#loading6">loading and running scripts</a>,
|
|
<a href="#binding23">binding implementations</a>.)</p>
|
|
|
|
<p><code><a href="#implementation0">implementation</a></code> blocks are
|
|
evaluated once, on first use. Changes to an <code><a
|
|
href="#implementation0">implementation</a></code> element or its contents
|
|
have no effect once the element has been evaluated. (See: <a
|
|
href="#binding23">binding implementations</a>.)</p>
|
|
<!--
|
|
<p>User agents may support an additional attribute with a name of
|
|
the form <code><var>vendor</var>-binary</code>
|
|
(e.g. <code>moz-binary=""</code> or <code>khtml-binary=""</code>)
|
|
that contains information on native code implementations of the
|
|
binding, if necessary. Content using such an attribute is
|
|
non-conforming. (This feature is expected to be used in
|
|
vendor-specific environments, not on the Web, and guidance for the
|
|
name is provided only as an aid in preventing conflicts with future
|
|
versions of this specification.)</p>
|
|
-->
|
|
|
|
<div class=example id=implementation-element-example>
|
|
<p>The following example shows a binding that defines a new method, two
|
|
new properties (one with a custom getter and setter, one without), an
|
|
internal field (used to back the property), and some hooks to initialize
|
|
the binding and to handle the bound element being inserted and removed
|
|
from the document. The binding applies to any element with the class
|
|
"demo" (in the files into which it is imported, that is).</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding element=".demo">
|
|
<implementation>
|
|
({
|
|
add: function (op1, op2) {
|
|
return op1+op2;
|
|
},
|
|
get memory() {
|
|
return this._memory.toString();
|
|
},
|
|
set memory(value) {
|
|
this._memory = parseInt(value, 10);
|
|
},
|
|
xblBindingAttached: function() {
|
|
this._memory = 0; // internal property to back "memory" external property
|
|
this.external.state = 'initialized'; // external property
|
|
},
|
|
xblEnteredDocument: function() {
|
|
this.external.state = 'in document';
|
|
},
|
|
xblLeftDocument: function() {
|
|
this.external.state = 'out of document';
|
|
},
|
|
})
|
|
</implementation>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p class=note>The <code>get field() {}</code> and
|
|
<code>set field(syntax) {}</code> features are <a
|
|
href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Creating_New_Objects:Defining_Getters_and_Setters">part
|
|
of JavaScript 1.5</a> and will probably be in ECMAScript 4. The examples
|
|
in this specification assume an implementation that supports ECMAScript
|
|
4, but any language could be supported in real implementations.</p>
|
|
|
|
<p>The following example shows how to refer to an external file for the
|
|
implementation of a binding. In this example, the handlers simply defer
|
|
to methods defined in that implementation, so that all the code is in
|
|
that file.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="demo">
|
|
<implementation src="demo.js"/>
|
|
<handlers>
|
|
<handler event="click"> this.clicked(event); </handler>
|
|
<handler event="focus"> this.focused(event); </handler>
|
|
<handler event="blur"> this.blurred(event); </handler>
|
|
</handlers>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>The <code>demo.js</code> file for this might look like this, to ensure
|
|
that the methods defined are in fact internal methods, not exposed on
|
|
the <a href="#external0">external object</a>:</p>
|
|
|
|
<pre>({
|
|
xblBindingAttached: function () {
|
|
this.clicked = function (event) { ... };
|
|
this.focused = function (event) { ... };
|
|
this.blurred = function (event) { ... };
|
|
},
|
|
// ... other methods and fields ...
|
|
})</pre>
|
|
</div>
|
|
|
|
<h3 id=the-template><span class=secno>2.4. </span>The <dfn
|
|
id=template0><code>template</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#binding16">binding</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>Anything. Of particular interest, the <code><a
|
|
href="#content0">content</a></code> and <code><a
|
|
href="#inherited0">inherited</a></code> elements may occur as
|
|
descendants, and non-XBL descendant elements may host <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> and <code
|
|
title=attr-pseudo><a href="#xblpseudo0">xbl:pseudo</a></code>
|
|
attributes.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#template0">template</a></code> element
|
|
contains child nodes that can be in any namespace. 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. Dynamic changes to the descendants of <code><a
|
|
href="#template0">template</a></code> elements are reflected in bindings.
|
|
(See: <a href="#shadow5">shadow content</a>.)</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes7>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id3 title=attr-template-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=apply-author-sheets
|
|
title=attr-template-apply-author-sheets>apply-author-sheets</dfn>
|
|
|
|
<dd>The <code title=attr-template-apply-author-sheets><a
|
|
href="#apply-author-sheets">apply-author-sheets</a></code> attribute
|
|
indicates whether or not rules in <a href="#author">author style
|
|
sheets</a> associated with the bound element's document apply to the
|
|
shadow content generated by the binding. Its value must be either
|
|
<code>true</code> (indicating that they do) or <code>false</code>
|
|
(indicating that they do not). The default behavior, which is used when
|
|
the attribute is omitted or has a value other than the two allowed
|
|
values, is to not apply the bound document's <a href="#author">author
|
|
style sheets</a> (same as <code>false</code>). (See: <a
|
|
href="#binding22">binding style sheets</a>.)
|
|
|
|
<dt><dfn id=allow-selectors-through
|
|
title=attr-template-allow-selectors-through>allow-selectors-through</dfn>
|
|
|
|
<dd>The <code title=attr-template-allow-selectors-through><a
|
|
href="#allow-selectors-through">allow-selectors-through</a></code>
|
|
attribute indicates whether or not rules in CSS can <a
|
|
href="#selectors1" title="selectors and shadow scopes">cross scopes</a>.
|
|
Its value must be either <code>true</code> (indicating that they can) or
|
|
<code>false</code> (indicating that they cannot). The default behavior,
|
|
which is used when the attribute is omitted or has a value other than
|
|
the two allowed values, is to not let selectors cross scopes (same as
|
|
<code>false</code>). (See: <a href="#selectors1">selectors and shadow
|
|
scopes</a>.)
|
|
</dl>
|
|
|
|
<p class=note>The semantics of non-XBL elements inside this element are
|
|
untouched, which can lead to unintuitive results. (See: <a
|
|
href="#shadow10">semantics of non-XBL elements in XBL contexts</a>.)</p>
|
|
|
|
<div class=example id=template-element-example>
|
|
<p>The following binding defines a shadow tree that wraps the contents of
|
|
the bound element in four blocks. It uses the <code
|
|
title=attr-template-apply-author-sheets><a
|
|
href="#apply-author-sheets">apply-author-sheets</a></code> attribute to
|
|
allow the bound document to style the nodes directly, and uses the <code
|
|
title=attr-template-allow-selectors-through><a
|
|
href="#allow-selectors-through">allow-selectors-through</a></code>
|
|
attribute to allow the bound document to pretend (for the purposes of
|
|
selector matching) that the shadow tree actually is descended from the
|
|
bound element.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="wrapBy4">
|
|
<template apply-author-sheets="true" allow-selectors-through="true">
|
|
<div class="wrap1">
|
|
<div class="wrap2">
|
|
<div class="wrap3">
|
|
<div class="wrap4">
|
|
<content/>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</template>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>Using this binding could take the following document:</p>
|
|
|
|
<pre><html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Pretty Title</title>
|
|
<style>
|
|
h1 span { display: block; }
|
|
h1 { border: solid red; }
|
|
h1 .wrap1 { border: solid orange; }
|
|
h1 .wrap2 { border: solid yellow; }
|
|
h1 .wrap3 { border: solid green; }
|
|
h1 .wrap4 { border: solid blue; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>
|
|
<span class="wrap1">
|
|
<span class="wrap2">
|
|
<span class="wrap3">
|
|
<span class="wrap4">
|
|
Pretty Title
|
|
</span>
|
|
</span>
|
|
</span>
|
|
</span>
|
|
</h1>
|
|
...
|
|
</body>
|
|
</html></pre>
|
|
|
|
<p>...and shrink it to this:</p>
|
|
|
|
<pre><html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Pretty Title</title>
|
|
<style>
|
|
h1 { binding: url(cool.xml#wrapBy4); }
|
|
h1 { border: solid red; }
|
|
h1 .wrap1 { border: solid orange; }
|
|
h1 .wrap2 { border: solid yellow; }
|
|
h1 .wrap3 { border: solid green; }
|
|
h1 .wrap4 { border: solid blue; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>Pretty Title</h1>
|
|
...
|
|
</body>
|
|
</html></pre>
|
|
|
|
<p>...which removes the semantic-free elements used as presentation hooks
|
|
from the content markup layer, and places them in the presentation layer
|
|
where they belong.</p>
|
|
</div>
|
|
|
|
<h3 id=the-content><span class=secno>2.5. </span>The <dfn
|
|
id=content0><code>content</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd>Any, but there must be a <a href="#correct">correct</a> <code><a
|
|
href="#template0">template</a></code> element somewhere in the ancestor
|
|
chain, and there must not be any <code><a
|
|
href="#content0">content</a></code> elements anywhere in the ancestor
|
|
chain.
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>Anything.
|
|
</dl>
|
|
|
|
<div class=note>
|
|
<p>The <code><a href="#content0">content</a></code> element is used
|
|
inside <a href="#shadow5">shadow content</a> to specify where <a
|
|
href="#explicit3">explicit children</a> that might already exist
|
|
underneath the bound element are inserted into the <a
|
|
href="#shadow7">shadow tree</a>. 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 <a
|
|
href="#explicit3">explicit children</a> without affecting the document
|
|
model.</p>
|
|
|
|
<p>If the <code title=attr-content-includes><a
|
|
href="#includes">includes</a></code> attribute has children of the bound
|
|
element assigned to it, then those children are inserted into the <a
|
|
href="#final0">final flattened tree</a> in place of the <code><a
|
|
href="#content0">content</a></code> element. Otherwise, the child
|
|
elements of the <code><a href="#content0">content</a></code> element are
|
|
inserted into the <a href="#final0">final flattened tree</a> in place of
|
|
the <code><a href="#content0">content</a></code> element instead. (See:
|
|
<a href="#processing2">processing <code title="">content</code>
|
|
elements</a>.)</p>
|
|
</div>
|
|
|
|
<h4 class="no-toc no-num" id=attributes8>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id4 title=attr-content-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=includes title=attr-content-includes>includes</dfn>
|
|
|
|
<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 must be a valid
|
|
<a href="#attributes21">selector</a>. (See: <a
|
|
href="#processing2">processing <code title="">content</code>
|
|
elements</a>.)
|
|
|
|
<dt><dfn id=apply-binding-sheets
|
|
title=attr-content-apply-binding-sheets>apply-binding-sheets</dfn>
|
|
|
|
<dd>The <code title=attr-content-apply-binding-sheets><a
|
|
href="#apply-binding-sheets">apply-binding-sheets</a></code> attribute
|
|
indicates whether or not scoped style sheets loaded for an XBL binding
|
|
are applied to a bound element's <a href="#explicit3">explicit
|
|
children</a> (in addition to the bound element itself) that are inserted
|
|
below this <code><a href="#content0">content</a></code> element when it
|
|
is processed. Its value must be either <code>true</code> (indicating
|
|
that they are) or <code>false</code> (indicating that they are not). The
|
|
default behavior, which is used when the attribute is omitted or has a
|
|
value other than the two allowed values, is that they are not applied
|
|
(same as <code>false</code>). (See: <a href="#binding22">binding style
|
|
sheets</a>.)
|
|
|
|
<dt><dfn id=locked title=attr-content-locked>locked</dfn>
|
|
|
|
<dd>The <code title=attr-content-locked><a
|
|
href="#locked">locked</a></code> attribute indicates whether or not new
|
|
children may be inserted below this <code><a
|
|
href="#content0">content</a></code> element when it is processed. Its
|
|
value must be either <code>true</code> (indicating that they may not) or
|
|
<code>false</code> (indicating that they may). The default behavior,
|
|
which is used when the attribute is omitted or has a value other than
|
|
the two allowed values, is that they may be inserted (same as
|
|
<code>false</code>). Elements already assigned to a <code><a
|
|
href="#content0">content</a></code> element whose <code
|
|
title=attr-content-locked><a href="#locked">locked</a></code> attribute
|
|
is dynamically changed are not removed from that element. (See: <a
|
|
href="#processing2">processing <code title="">content</code>
|
|
elements</a>.)
|
|
</dl>
|
|
|
|
<div class=example id=content-element-example>
|
|
<p>This sample extract from a binding document shows how to use the <code
|
|
title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute to distribute children to different parts of a shadow content
|
|
template.</p>
|
|
|
|
<pre><xbl:xbl xmlns:xbl="http://www.w3.org/ns/xbl"
|
|
xmlns:data="http://example.com/data-language">
|
|
<xbl:binding element="data|grid">
|
|
<xbl:template>
|
|
<xbl:div class="caption" xbl:attr="xbl:text=title"/>
|
|
<xbl:div class="outer-table">
|
|
<xbl:div class="columns">
|
|
<xbl:content includes="data|column">
|
|
<!-- default to have just one column if none are declared -->
|
|
<data:column/>
|
|
</xbl:content>
|
|
</xbl:div>
|
|
<xbl:div class="rows">
|
|
<xbl:content includes="data|heading"/>
|
|
<xbl:div class="body">
|
|
<xbl:content includes="data|row:not([hidden])"/>
|
|
</xbl:div>
|
|
</xbl:div>
|
|
</xbl:div>
|
|
</xbl:template>
|
|
...
|
|
</xbl:binding>
|
|
...
|
|
</xbl:xbl></pre>
|
|
|
|
<p>The above template would be used with markup such as the following:</p>
|
|
|
|
<pre><data xmlns="http://example.com/data-language">
|
|
...
|
|
<grid title="The Lesser of Two Evils">
|
|
<column id="product" sort="alphabetic primary"/>
|
|
<column id="catchphrase" sort="alphabetic secondary"/>
|
|
<heading>
|
|
<item>Product</item>
|
|
<item>Catchphrase</item>
|
|
</heading>
|
|
<row>
|
|
<item>Arachno Spores</item>
|
|
<item>The fatal spore with the funny name</item>
|
|
</row>
|
|
<row>
|
|
<item>Pastorama</item>
|
|
<item>Located on the former site of Brooklyn</item>
|
|
</row>
|
|
</grid>
|
|
...
|
|
</data></pre>
|
|
|
|
<p>The following illustrates how the above markup would get
|
|
redistributed.</p>
|
|
|
|
<p><img alt="The two column elements would get put under the div with
|
|
class columns; the heading element and its descendants would end up at
|
|
the start of the div with class rows, and the two row elements would end
|
|
up under the div with class rows."
|
|
src="images/content-element-example-explanation.png"></p>
|
|
</div>
|
|
|
|
<div class=example id=content-element-example-2>
|
|
<p>In this example, the binding uses the <code
|
|
title=attr-content-apply-binding-sheets><a
|
|
href="#apply-binding-sheets">apply-binding-sheets</a></code> attribute
|
|
to let its stylesheet affect the <a href="#explicit3">explicit
|
|
children</a> of the bound element.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl"
|
|
xmlns:ui="http://example.org/ui-language/">
|
|
<binding element="ui|listbox">
|
|
<template allow-selectors-through="true">
|
|
<div id="listbox-focus">
|
|
<content includes="ui|listitem" apply-binding-sheets="true"/>
|
|
</div>
|
|
</template>
|
|
<resources>
|
|
<style>
|
|
@namespace xbl url(http://www.w3.org/ns/xbl);
|
|
@namespace uil url(http://example.org/ui-language/);
|
|
uil|listbox { display: block; background: white; color: black; }
|
|
uil|listbox > xbl|div#listbox-focus { border: ridge silver; }
|
|
uil|listbox:focus > xbl|div#listbox-focus { border: inset silver; }
|
|
uil|listitem { display: block; background: white; color: black; }
|
|
uil|listitem[selected] { display: block; background: navy; color: white;}
|
|
</style>
|
|
</resources>
|
|
...
|
|
</binding></xbl></pre>
|
|
</div>
|
|
|
|
<div class=example id=content-element-example-locked>
|
|
<p>In the following example, the <code title=attr-content-locked><a
|
|
href="#locked">locked</a></code> attribute is used to keep the children
|
|
of the bound element in the location that the user has selected. By
|
|
default, the <code title="">listitem</code> elements would be placed in
|
|
the first <code><a href="#content0">content</a></code> element, but
|
|
because it is locked, they will instead go into the second one.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl"
|
|
xmlns:ui="http://example.org/ui-language/">
|
|
<binding element="ui|duallist">
|
|
<template>
|
|
<div>
|
|
<ui:listbox id="left" title="Selected Items">
|
|
<content includes="ui|listitem" locked="true" id="leftList"/>
|
|
</ui:listbox>
|
|
</div>
|
|
<div id="buttons">
|
|
<ui:button id="move-right"> Move Right </ui:button>
|
|
<ui:button id="move-left"> Move Left </ui:button>
|
|
</div>
|
|
<div>
|
|
<ui:listbox id="right" title="Available Items">
|
|
<content includes="ui|listitem" id="rightList"/>
|
|
</ui:listbox>
|
|
</div>
|
|
</template>
|
|
<implementation>
|
|
({
|
|
xblBindingAttached: function() {
|
|
this.shadowTree.getElementById('move-right').addEventListener(
|
|
'click', this.moveRight, false
|
|
);
|
|
this.shadowTree.getElementById('move-left').addEventListener(
|
|
'click', this.moveLeft, false
|
|
);
|
|
},
|
|
moveRight: function(event) {
|
|
this.shadowTree.getElementById('rightList').setInsertionPoint(
|
|
this.shadowTree.getElementById('left').selectedElement
|
|
);
|
|
},
|
|
moveLeft: function(event) {
|
|
this.shadowTree.getElementById('leftList').setInsertionPoint(
|
|
this.shadowTree.getElementById('right').selectedElement
|
|
);
|
|
},
|
|
})
|
|
</implementation>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-inherited><span class=secno>2.6. </span>The <dfn
|
|
id=inherited0><code>inherited</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd>Any, but there must be a <a href="#correct">correct</a> <code><a
|
|
href="#template0">template</a></code> element somewhere in the ancestor
|
|
chain.
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>Anything.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#inherited0">inherited</a></code> element
|
|
represents where the next inherited shadow tree is to be inserted. If the
|
|
binding is the base binding (and thus has no inherited bindings) or if
|
|
none of the bindings it inherits from have shadow trees, or if this is
|
|
not the first <code><a href="#inherited0">inherited</a></code> element in
|
|
the binding's shadow tree, then the contents of the <code><a
|
|
href="#inherited0">inherited</a></code> element (if any) will be used
|
|
instead. (See: <a href="#final0" title="final flattened tree">the final
|
|
flattened tree</a>.)</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes9>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id5 title=attr-element-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
</dl>
|
|
|
|
<p class=note>While it is legal to nest <code><a
|
|
href="#inherited0">inherited</a></code> elements, it is pointless, since
|
|
if one <code><a href="#inherited0">inherited</a></code> element used its
|
|
fallback content, any subsequent such elements will too.</p>
|
|
|
|
<div class=example id=inherited-element-example>
|
|
<p>The following binding wraps the bound element's children in a set of
|
|
<code><a href="#div0">div</a></code>s for extra styling. By using the
|
|
<code><a href="#inherited0">inherited</a></code> element, it has been
|
|
designed such that it must be used in conjunction with other bindings:
|
|
it will (if applied after the others) wrap the shadow trees of those
|
|
templates. Contrast this with <a href="#template-element-example">the
|
|
example in the <code>template</code> section</a>, which would not
|
|
interact with other bindings. However, if this binding is not applied in
|
|
conjunction with a binding that has a <code><a
|
|
href="#content0">content</a></code> element giving a place for the
|
|
element's explicit children, then those children will not be in the
|
|
final flattened tree.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="wrapBy4">
|
|
<template apply-author-sheets="true" allow-selectors-through="true">
|
|
<div class="wrap1">
|
|
<div class="wrap2">
|
|
<div class="wrap3">
|
|
<div class="wrap4">
|
|
<inherited/>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</template>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-xblattr><span class=secno>2.7. </span>The <dfn id=xblattr0
|
|
title=attr-attr><code>xbl:attr</code></dfn> Attribute</h3>
|
|
|
|
<dl>
|
|
<dt>Expected element:
|
|
|
|
<dd>Any, but there must be a <a href="#correct">correct</a> <code><a
|
|
href="#template0">template</a></code> element somewhere in the ancestor
|
|
chain.
|
|
</dl>
|
|
|
|
<p class=note>The <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> attribute is a global attribute in
|
|
the XBL namespace that specifies which attributes on the bound element
|
|
should be forwarded to the element on which the attribute is found when
|
|
the shadow content template is cloned. It is a <a
|
|
href="#attributes22">space-separated</a> list of <a href="#qname"
|
|
title=QName>QNames</a> or <a href="#qname">QName</a> pairs separated by
|
|
equal signs, each possibly suffixed by a hash character ("#") and a type
|
|
designation. (See: <a href="#attribute1">attribute forwarding</a>.)</p>
|
|
|
|
<p>The value of the <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> attribute must be a <a
|
|
href="#attributes22">space-separated</a> value of items that match the
|
|
pattern given in the <a href="#attribute1">attribute forwarding</a>
|
|
section.</p>
|
|
|
|
<div class=example id=inherits-attribute-example>
|
|
<p>One of the major uses of the <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> attribute is to implement one
|
|
element in terms of another element which already has special behavior
|
|
in user agents. This example shows how a <code>ui:text</code> element
|
|
can be implemented in terms of an <code>html:input</code> element, with
|
|
certain attributes being forwarded to that element directly.</p>
|
|
|
|
<pre><xbl:xbl xmlns:xbl="http://www.w3.org/ns/xbl"
|
|
xmlns:ui="http://example.com/ui-language/"
|
|
xmlns:html="http://www.w3.org/1999/xhtml">
|
|
<xbl:binding element="ui|text">
|
|
<xbl:template>
|
|
<html:label>
|
|
<html:span xbl:attr="xbl:text=label"/>
|
|
<html:input xbl:attr="value=default disabled readonly" id="input"/>
|
|
</html:label>
|
|
</xbl:template>
|
|
<xbl:implementation>
|
|
({
|
|
get value () { return this.shadowTree.getElementById('input').value; },
|
|
set value (val) { this.shadowTree.getElementById('input').value = val; },
|
|
})
|
|
</xbl:implementation>
|
|
</xbl:binding>
|
|
</xbl:xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-xblpseudo><span class=secno>2.8. </span>The <dfn id=xblpseudo0
|
|
title=attr-pseudo><code>xbl:pseudo</code></dfn> Attribute</h3>
|
|
|
|
<dl>
|
|
<dt>Expected element:
|
|
|
|
<dd>Any, but there must be a <a href="#correct">correct</a> <code><a
|
|
href="#template0">template</a></code> element somewhere in the ancestor
|
|
chain.
|
|
</dl>
|
|
|
|
<p class=note>The <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attribute is a global attribute
|
|
in the XBL namespace that specifies the <a
|
|
href="#pseudo-element">pseudo-element</a> that, when used on the bound
|
|
element, must be mapped to the element on which the attribute is found.</p>
|
|
|
|
<p>The value of the <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attribute must be a valid <a
|
|
href="#pseudo-element">pseudo-element</a> name, in lowercase, without the
|
|
leading "::". The valid pseudo-elements are defined by the CSS
|
|
specifications, and are "value", "choices", "label", "repeat-item", and
|
|
"icon". Future versions of CSS might introduce new values. (See: <a
|
|
href="#matching1">matching pseudo-elements</a>.)</p>
|
|
|
|
<div class=example id=pseudo-attribute-example>
|
|
<p>The <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attribute is useful as a way to
|
|
let <a href="#author" title="author style sheets">author styles</a>
|
|
affect the insides of a shadow tree without exposing the exact
|
|
construction of the tree. Here, the binding represents a composite
|
|
widget with an icon, a label, a text field, and some buttons.
|
|
Pseudo-elements are used for each part allowing the author to style each
|
|
part separately.</p>
|
|
|
|
<pre><xbl:xbl xmlns:xbl="http://www.w3.org/ns/xbl"
|
|
xmlns:html="http://www.w3.org/1999/xhtml">
|
|
<xbl:binding id="input-dialog">
|
|
<xbl:template>
|
|
<xbl:div class="root">
|
|
<xbl:div class="icon-block">
|
|
<html:img xbl:pseudo="icon" xbl:attr="src=icon alt=alt"/>
|
|
</xbl:div>
|
|
<xbl:div xbl:pseudo="label" xbl:attr="xbl:text=label"/>
|
|
<xbl:div class="field-block">
|
|
<html:input xbl:pseudo="value" xbl:attr="value" id="field"/>
|
|
</xbl:div>
|
|
<xbl:div class="buttons-block">
|
|
<html:button xbl:pseudo="choices" id="ok"> OK </html:button>
|
|
<html:button xbl:pseudo="choices" id="cancel"> Cancel </html:button>
|
|
</xbl:div>
|
|
</xbl:div>
|
|
</xbl:template>
|
|
...
|
|
</xbl:binding>
|
|
</xbl:xbl></pre>
|
|
|
|
<p>An author-level stylesheet for a document using the binding might look
|
|
like:</p>
|
|
|
|
<pre>textDialog { binding: url(dialogs.xml#input-dialog); }
|
|
textDialog::value { background: white; color: black; }
|
|
textDialog::choices { border: outset; }</pre>
|
|
</div>
|
|
|
|
<h3 id=the-div><span class=secno>2.9. </span>The <dfn
|
|
id=div0><code>div</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected contexts:
|
|
|
|
<dd><code><a href="#template0">template</a></code>
|
|
|
|
<dd><code><a href="#content0">content</a></code>
|
|
|
|
<dd><code><a href="#inherited0">inherited</a></code>
|
|
|
|
<dd><code><a href="#div0">div</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>Anything. Of particular interest, the <code><a
|
|
href="#content0">content</a></code> and <code><a
|
|
href="#inherited0">inherited</a></code> elements may occur as
|
|
descendants, and non-XBL descendant elements may host <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> and <code
|
|
title=attr-pseudo><a href="#xblpseudo0">xbl:pseudo</a></code>
|
|
attributes.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#div0">div</a></code> element has no
|
|
intrinsic meaning. It is intended to be used as a styling hook for
|
|
presentational bindings.</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes10>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id6 title=attr-div-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=class title=attr-div-class>class</dfn>
|
|
|
|
<dd>A <a href="#attributes22">space-separated</a> list of keywords
|
|
relevant to the element that could be useful as stylistic hooks. This is
|
|
a "class" attribute (which means, for example, that the CSS "."
|
|
shorthand can be used to match <code><a href="#div0">div</a></code>
|
|
elements based on their <code>class</code> attribute). <span
|
|
class=note>The <code title=attr-div-class><a
|
|
href="#class">class</a></code> attribute doesn't apply to other XBL
|
|
elements, only to <code><a href="#div0">div</a></code>.</span>
|
|
|
|
<dt><dfn id=state title=attr-div-state>state</dfn>
|
|
|
|
<dd>A free-form attribute with no predefined meaning that can be used as
|
|
a stylistic hook, to store state, or for other purposes as desired by
|
|
the binding author.
|
|
|
|
<dt><dfn id=title title=attr-div-title>title</dfn>
|
|
|
|
<dd>Text representing advisory information that the user agent should
|
|
show to the user upon request (e.g., on a graphical browser, the
|
|
contents of this attribute could be shown as a tooltip when the user
|
|
indicates the element with a mouse pointer). <span class=note>The <code
|
|
title=attr-div-title><a href="#title">title</a></code> attribute doesn't
|
|
apply to other XBL elements, only to <code><a
|
|
href="#div0">div</a></code>.</span>
|
|
</dl>
|
|
|
|
<p>The <code><a href="#div0">div</a></code> element in XBL is <em>not</em>
|
|
the same element type as the <code><a href="#div0">div</a></code> element
|
|
in HTML, but it is intended to be used in similar ways (and shares the
|
|
name for that reason).</p>
|
|
|
|
<div class=example id=div-element-example>
|
|
<p>Many of the examples in this specification use the <code><a
|
|
href="#div0">div</a></code> element.</p>
|
|
|
|
<p>The following example uses the <code title=attr-div-state><a
|
|
href="#state">state</a></code> attribute so that the CSS style sheet can
|
|
render the shadow tree differently based on whether the switch that the
|
|
binding represents is turned on or off.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="switch">
|
|
<template>
|
|
<div class="wrapper">
|
|
<div id="main" state="off"/>
|
|
</div>
|
|
</template>
|
|
<handlers>
|
|
<handler event="click">
|
|
this.shadowTree.getElementById('main').setAttribute('state',
|
|
this.shadowTree.getElementById('main').getAttribute('state') == 'on' ?
|
|
'off' : 'on');
|
|
</handler>
|
|
</handlers>
|
|
<resources>
|
|
<style>
|
|
#main[state=off] { ... }
|
|
#main[state=on] { ... }
|
|
</style>
|
|
</resources>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-handlers><span class=secno>2.10. </span>The <dfn
|
|
id=handlers0><code>handlers</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#binding16">binding</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd><code><a href="#handler0">handler</a></code>: zero or more.
|
|
</dl>
|
|
|
|
<div class=note>
|
|
<p>The <code><a href="#handlers0">handlers</a></code> element's event
|
|
handlers can be called for events that flow through the bound element.
|
|
During capture, target, bubbling, and <a href="#the-default1"
|
|
title="default phase">default</a> phases, when a given event is received
|
|
by a bound element, if a corresponding event listener has been attached
|
|
to the <code><a href="#handlers0">handlers</a></code> element, then the
|
|
event will be <a href="#event12" title="event forwarding">forwarded</a>
|
|
to that event listener. (See: <a href="#event12">event forwarding</a>,
|
|
<a href="#binding17">binding attachment and detachment</a>.)</p>
|
|
|
|
<p>Typically, event handlers are defined using <code><a
|
|
href="#handler0">handler</a></code> elements.</p>
|
|
</div>
|
|
|
|
<h4 class="no-toc no-num" id=attributes11>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id7 title=attr-handlers-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
</dl>
|
|
|
|
<div class=example id=handlers-element-example>
|
|
<p>The following example shows how <code><a
|
|
href="#handlers0">handlers</a></code> can be used with any event
|
|
listener mechanism.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="test">
|
|
<handlers id="test-handlers"/>
|
|
...
|
|
</binding>
|
|
<script>
|
|
document.getElementById('test-handlers').addEventListener('click', function (event) {
|
|
// this will get called for every click event that bubbles through
|
|
// any element that is bound to the "test" binding above.
|
|
...
|
|
}, false);
|
|
</script>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-handler><span class=secno>2.11. </span>The <dfn
|
|
id=handler0><code>handler</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#handlers0">handlers</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>Depends on the scripting language.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#handler0">handler</a></code> element
|
|
describes a single event handler. This handler is attached to its parent
|
|
<code><a href="#handlers0">handlers</a></code> element, which is used as
|
|
an event forwarding target when handling events on the bound element.
|
|
(See: <a href="#event11">event handlers</a>.) It wraps a script that is
|
|
executed when the event handler is matched.</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes12>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id8 title=attr-handler-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=event9 title=attr-handler-event>event</dfn>
|
|
|
|
<dd>The <code title=attr-handler-event><a href="#event9">event</a></code>
|
|
attribute describes the specific event that this handler is listening
|
|
for. (See: <a href="#registering1">registering event handlers with the
|
|
<code>handler</code> element</a>.)
|
|
|
|
<dt><dfn id=phase title=attr-handler-phase>phase</dfn>
|
|
|
|
<dd>This attribute specifies the phase of the event flow that this
|
|
handler should monitor. When specified, the value must be one of
|
|
<code>capture</code>, <code>target</code>, <code>bubble</code>, or
|
|
<code>default-action</code>. If <code>capture</code> is specified, then
|
|
the event handler must only be fired during the capturing phase of event
|
|
propagation. If <code>target</code> is specified, then the event handler
|
|
must only be fired during the target phase. If
|
|
<code>default-action</code> is specified, then the event handler must
|
|
only be fired during the <a href="#the-default1">default phase</a> (if
|
|
it occurs). Otherwise, the handler must only be fired during the
|
|
bubbling phase. (See: <a href="#registering1">registering event handlers
|
|
with the <code>handler</code> element</a>.)
|
|
|
|
<dt><dfn id=trusted title=attr-handler-trusted>trusted</dfn>
|
|
|
|
<dd>This attribute specifies whether the handler should be limited to <a
|
|
href="#trusted0" title=event-trusted>trusted events</a>. When specified,
|
|
it must have the value <code>true</code> or the value
|
|
<code>false</code>. If <code>true</code> is specified, then the event
|
|
handler must only be fired if the event's <code title=event-trusted><a
|
|
href="#trusted0">trusted</a></code> attribute is true. Otherwise, the
|
|
value of the <code title=event-trusted><a
|
|
href="#trusted0">trusted</a></code> flag does not affect the event
|
|
handler. (See: <a href="#registering1">registering event handlers with
|
|
the <code>handler</code> element</a>.)
|
|
|
|
<dt><dfn id=propagate title=attr-handler-propagate>propagate</dfn>
|
|
|
|
<dd>The <code title=attr-handler-propagate><a
|
|
href="#propagate">propagate</a></code> attribute specifies whether after
|
|
processing all listeners at the current node, the event is allowed to
|
|
continue on its path (either in the capture or the bubble phase). When
|
|
specified, it must have the value <code title="">stop</code> or the
|
|
value <code title="">continue</code>. If the value is <code
|
|
title="">stop</code>, then propagation will be stopped, otherwise it
|
|
won't. It has no effect if the <code title=attr-handler-phase><a
|
|
href="#phase">phase</a></code> attribute has the value
|
|
<code>default-action</code>. (See: <a href="#registering1">registering
|
|
event handlers with the <code>handler</code> element</a>.)
|
|
|
|
<dt><dfn id=default-action
|
|
title=attr-handler-default-action>default-action</dfn>
|
|
|
|
<dd>The <code title=attr-handler-default-action><a
|
|
href="#default-action">default-action</a></code> attribute specifies
|
|
whether after processing of all listeners for the event, the default
|
|
action for the event (if any) should be performed or not. (See: <a
|
|
href="#registering1">registering event handlers with the
|
|
<code>handler</code> element</a>.)</dd>
|
|
<!--XXX provide <handler method="foo"/> as a shortcut for <handler>foo(event)</handler> -->
|
|
<!-- lexical constraints for filters are defined in filter sections -->
|
|
|
|
<dt><dfn id=button title=attr-handler-button>button</dfn>
|
|
|
|
<dd>The <code title=attr-handler-button><a
|
|
href="#button">button</a></code> attribute imposes a <em>filter</em> on
|
|
the handler. It is used with mouse handlers to specify a particular
|
|
button. (See: <a href="#mouse1">mouse event handler filters</a>.)
|
|
|
|
<dt><dfn id=click-count title=attr-handler-click-count>click-count</dfn>
|
|
|
|
<dd>The <code title=attr-handler-click-count><a
|
|
href="#click-count">click-count</a></code> attribute imposes a
|
|
<em>filter</em> on the handler. It is used with mouse handlers to
|
|
specify how many clicks must have occurred. (See: <a
|
|
href="#mouse1">mouse event handler filters</a>.)
|
|
|
|
<dt><dfn id=modifiers1 title=attr-handler-modifiers>modifiers</dfn>
|
|
|
|
<dd>The <code title=attr-handler-modifiers><a
|
|
href="#modifiers1">modifiers</a></code> attribute imposes a filter on
|
|
key and mouse handlers. It is used with mouse and key handlers to
|
|
specify particular modifier keys. (See: <a href="#mouse1">mouse event
|
|
handler filters</a>, <a href="#key-event1">key event handler
|
|
filters</a>, <a href="#modifiers2">modifiers</a>.)
|
|
|
|
<dt><dfn id=key title=attr-handler-key>key</dfn>
|
|
|
|
<dd>The <code title=attr-handler-key><a href="#key">key</a></code>
|
|
attribute imposes a filter on key handlers. It is used with key handlers
|
|
to specify which keys to listen for. (See: <a href="#key-event1">key
|
|
event handler filters</a>.)
|
|
|
|
<dt><dfn id=key-location
|
|
title=attr-handler-key-location>key-location</dfn>
|
|
|
|
<dd>The <code title=attr-handler-key-location><a
|
|
href="#key-location">key-location</a></code> attribute imposes a filter
|
|
on key handlers. It is used with key handlers to specify which keys to
|
|
listen for. (See: <a href="#key-event1">key event handler filters</a>.)
|
|
|
|
<dt><dfn id=text title=attr-handler-text>text</dfn>
|
|
|
|
<dd>The <code title=attr-handler-text><a href="#text">text</a></code>
|
|
attribute imposes a filter on text input handlers. It is used with text
|
|
input handlers to specify which characters to listen for. (See: <a
|
|
href="#text-input1">text input event handler filters</a>.)
|
|
|
|
<dt><dfn id=prev-value title=attr-handler-prev-value>prev-value</dfn>
|
|
|
|
<dd>The <code title=attr-handler-prev-value><a
|
|
href="#prev-value">prev-value</a></code> attribute imposes a filter on
|
|
mutation handlers. It is used with mutation handlers to specify what
|
|
<code>prev-value</code> to listen for. (See: <a
|
|
href="#mutation1">mutation event handler filters</a>.)
|
|
|
|
<dt><dfn id=new-value title=attr-handler-new-value>new-value</dfn>
|
|
|
|
<dd>The <code title=attr-handler-new-value><a
|
|
href="#new-value">new-value</a></code> attribute imposes a filter on
|
|
mutation handlers. It is used with mutation handlers to specify what
|
|
<code>new-value</code> to listen for. (See: <a
|
|
href="#mutation1">mutation event handler filters</a>)
|
|
|
|
<dt><dfn id=attr-name title=attr-handler-attr-name>attr-name</dfn>
|
|
|
|
<dd>The <code title=attr-handler-attr-name><a
|
|
href="#attr-name">attr-name</a></code> attribute imposes a filter on
|
|
mutation handlers. It is used with attribute mutation handlers to
|
|
specify which attribute to listen to for changes. (See: <a
|
|
href="#mutation1">mutation event handler filters</a>)
|
|
|
|
<dt><dfn id=attr-change title=attr-handler-attr-change>attr-change</dfn>
|
|
|
|
<dd>The <code title=attr-handler-attr-change><a
|
|
href="#attr-change">attr-change</a></code> attribute imposes a filter on
|
|
mutation handlers. It is used with attribute mutation handlers to
|
|
specify the type of change to listen for. (See: <a
|
|
href="#mutation1">mutation event handler filters</a>.)
|
|
</dl>
|
|
|
|
<p>If a <code><a href="#handler0">handler</a></code> element is marked
|
|
(via the <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute of the <code><a
|
|
href="#xbl0">xbl</a></code> element) as being in a language that the UA
|
|
does not support then the UA must <a href="#ignoring">ignore</a> it,
|
|
meaning it must not be used for the event handler definitions of any
|
|
binding.</p>
|
|
|
|
<p>How UAs must handle nodes inside <code><a
|
|
href="#handler0">handler</a></code> elements depends on the language
|
|
used. (See: <a href="#loading6">loading and running scripts</a>, <a
|
|
href="#event11">event handlers</a>.)</p>
|
|
|
|
<p><code><a href="#handler0">handler</a></code> blocks are evaluated each
|
|
time they are fired. Changes to the <code><a
|
|
href="#handler0">handler</a></code> elements therefore take effect the
|
|
next time the event is fired.</p>
|
|
|
|
<div class=example id=handler-element-example>
|
|
<p>The following binding implements a link which, when clicked once with
|
|
the primary button and with no key modifiers, or, when focused and sent
|
|
a keypress of the Enter key with no modifiers, will cause the link to be
|
|
followed.</p>
|
|
|
|
<p>It will only do this if the click or the keypress is a real event
|
|
triggered by the user; it won't do it for events faked by script.
|
|
However, if the event faked by script is a DOMActivate event, then it
|
|
will follow the link, because the handler for the DOMActivate event
|
|
doesn't check that the event is <a href="#trusted0"
|
|
title=event-trusted>trusted</a>. (If it did, it would never fire,
|
|
because the event is dispatched by the binding, and therefore is not
|
|
trusted.)</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="events">
|
|
<handlers>
|
|
<handler event="click" phase="default-action"
|
|
button="1" click-count="1" modifiers="none"
|
|
trusted="true">
|
|
this.activate();
|
|
</handler>
|
|
<handler event="keypress" phase="default-action"
|
|
key="Enter" modifiers="none"
|
|
trusted="true">
|
|
this.activate();
|
|
</handler>
|
|
<handler event="DOMActivate" phase="default-action">
|
|
if (event.target == this.boundElement)
|
|
this.boundElement.ownerDocument.location.href = this.href;
|
|
</handler>
|
|
</handlers>
|
|
...
|
|
<!-- it is assumed that the implementation for this binding
|
|
implements a .activate() method that fires the DOMActivate
|
|
event on itself. -->
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-resources><span class=secno>2.12. </span>The <dfn
|
|
id=resources1><code>resources</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#binding16">binding</a></code>
|
|
|
|
<dt>Expected children (in any order):
|
|
|
|
<dd><code><a href="#style2">style</a></code>: zero or more.
|
|
|
|
<dd><code><a href="#prefetch0">prefetch</a></code>: zero or more.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#resources1">resources</a></code> element
|
|
contains a list of style sheets to apply when using this binding, as well
|
|
as a list of files (images, videos, sound files, etc) to optionally
|
|
preload.</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes13>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id9 title=attr-resources-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
</dl>
|
|
|
|
<h3 id=the-style><span class=secno>2.13. </span>The <dfn
|
|
id=style2><code>style</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#resources1">resources</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>If the element has no <code title=attr-style-src><a
|
|
href="#src0">src</a></code> attribute: depends on the styling language.
|
|
|
|
<dd>If the element does have a <code title=attr-style-src><a
|
|
href="#src0">src</a></code> attribute: none.
|
|
</dl>
|
|
|
|
<div class=note>
|
|
<p>The <code><a href="#style2">style</a></code> element is used to
|
|
specify a style sheet that is to be applied to the bound element and to
|
|
the shadow content generated by the binding, as well as to any <a
|
|
href="#explicit3">explicit children</a> (and their descendants) assigned
|
|
to <code><a href="#content0">content</a></code> elements in the shadow
|
|
content whose <code title=attr-content-apply-binding-sheets><a
|
|
href="#apply-binding-sheets">apply-binding-sheets</a></code> attribute
|
|
is set.</p>
|
|
|
|
<p>The <code><a href="#style2">style</a></code> element in XBL never
|
|
applies styles to elements in the bound document other than the bound
|
|
element (and <a href="#apply-binding-sheets"
|
|
title=attr-content-apply-binding-sheets>possibly its children</a>). It
|
|
never affects any ancestors of the bound element, or any nodes in any
|
|
other bindings or binding templates.</p>
|
|
</div>
|
|
|
|
<h4 class="no-toc no-num" id=attributes14>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id10 title=attr-style-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=media title=attr-style-media>media</dfn>
|
|
|
|
<dd>The <code title=attr-style-media><a href="#media">media</a></code>
|
|
attribute specifies the intended destination medium for style
|
|
information. If specified, the value of the attribute must be a valid
|
|
Media Query (<code title="">media_query</code> token). How the value of
|
|
this attribute is interpreted is defined by Media Queries. If this
|
|
attribute is not specified, then there is no restriction on which media
|
|
the style sheet should be applied to (same as specifying
|
|
<code>media="all"</code>). <a href="#refsMQ">[MQ]</a>
|
|
|
|
<dt><dfn id=src0 title=attr-style-src>src</dfn>
|
|
|
|
<dd>The <code title=attr-style-src><a href="#src0">src</a></code>
|
|
attribute specifies the <a href="#attributes24">URI</a> to a resource of
|
|
the type given by the XBL subtree's <code title=attr-xbl-style-type><a
|
|
href="#style-type">style-type</a></code> attribute. If the attribute is
|
|
specified, the contents of the element must be ignored (even if the
|
|
resource could not be fetched or was of the wrong type). (See: <a
|
|
href="#binding22">binding style sheets</a>.)
|
|
</dl>
|
|
|
|
<p>If a <code><a href="#style2">style</a></code> element is marked (via
|
|
the <code title=attr-xbl-style-type><a
|
|
href="#style-type">style-type</a></code> attribute of the <code><a
|
|
href="#xbl0">xbl</a></code> element) as being in a language that the UA
|
|
does not support, the UA must <a href="#ignoring">ignore</a> it.
|
|
Similarly, if the <code><a href="#style2">style</a></code> element points
|
|
(using the <code title=attr-style-src><a href="#src0">src</a></code>
|
|
attribute) to a resource that is either unavailable, or not of the type
|
|
specified by the <code title=attr-xbl-style-type><a
|
|
href="#style-type">style-type</a></code> attribute of the <code><a
|
|
href="#xbl0">xbl</a></code> element (or implied by its absence), then it
|
|
is <a href="#in-error">in error</a> and the UA must <a
|
|
href="#ignoring">ignore</a> it. In both cases, "ignoring it" means it
|
|
must not be used to style anything.</p>
|
|
|
|
<p>How UAs must handle nodes inside <code><a
|
|
href="#style2">style</a></code> elements depends on the language used.
|
|
(See: <a href="#binding22">binding style sheets</a>.)</p>
|
|
|
|
<p>For a summary of the various ways that content can be styled in the
|
|
presence of XBL, see the <a href="#styleSummary">styling summary
|
|
section</a>.</p>
|
|
|
|
<h3 id=the-prefetch><span class=secno>2.14. </span>The <dfn
|
|
id=prefetch0><code>prefetch</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#resources1">resources</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>None.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#prefetch0">prefetch</a></code> element
|
|
can be used to list resources that may be pre-loaded for performance
|
|
reasons.</p>
|
|
|
|
<p>Support for this element is optional. UAs may <a
|
|
href="#ignoring">ignore</a> it.</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes15>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id11 title=attr-prefetch-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=src1 title=attr-prefetch-src>src</dfn>
|
|
|
|
<dd>A <a href="#attributes24">URI</a> to a resource (such as an image)
|
|
that the binding might use later.
|
|
</dl>
|
|
|
|
<div class=example id=prefetch-element-example>
|
|
<p>The following binding uses two images; it sets the source of an HTML
|
|
<code>img</code> element programmatically to refer to those images. To
|
|
increase the chance that the "green.png" image is available straight
|
|
away when it is used, it uses a <code><a
|
|
href="#prefetch0">prefetch</a></code> element and specifies that that
|
|
image will be needed.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl"
|
|
xmlns:html="http://www.w3.org/1999/xhtml">
|
|
<binding id="light">
|
|
<template>
|
|
<html:img id="l" src="red.png" alt=""/>
|
|
</template>
|
|
<resources>
|
|
<prefetch src="red.png"/> <!-- this one isn't necessary, since
|
|
the UA will fetch this one as soon as it sees the <html:img> element -->
|
|
<prefetch src="green.png"/>
|
|
</resources>
|
|
<implementation>
|
|
({
|
|
red: function() {
|
|
this.shadowTree.getElementById('l').src = 'red.png';
|
|
},
|
|
green: function() {
|
|
this.shadowTree.getElementById('l').src = 'green.png';
|
|
},
|
|
})
|
|
</implementation>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>This binding might be used as follows:</p>
|
|
|
|
<pre><!DOCTYPE HTML>
|
|
<html>
|
|
<head>
|
|
<title>Light Demo</title>
|
|
<style>
|
|
#light { binding: url(demo.xml#light); }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<p id="light">Red</p>
|
|
<p>
|
|
<input type="button" onclick="doRed()" value="red">
|
|
<input type="button" onclick="doGreen()" value="green">
|
|
</p>
|
|
<script>
|
|
var light = document.getElementById('light');
|
|
function doRed() {
|
|
light.textContent = "Red";
|
|
if (light.red)
|
|
// binding might not be applied, so only call the method if it is defined
|
|
light.red();
|
|
}
|
|
function doGreen() {
|
|
light.textContent = "Green";
|
|
if (light.green) // same
|
|
light.green();
|
|
}
|
|
</script>
|
|
</body>
|
|
</html></pre>
|
|
|
|
<p>Ok, so this example is a little far fetched. So are most of the
|
|
examples in this spec. They're just examples!</p>
|
|
</div>
|
|
|
|
<h3 id=the-script><span class=secno>2.15. </span>The <dfn
|
|
id=script2><code>script</code></dfn> Element</h3>
|
|
|
|
<dl>
|
|
<dt>Expected context:
|
|
|
|
<dd><code><a href="#xbl0">xbl</a></code>
|
|
|
|
<dt>Expected children:
|
|
|
|
<dd>If the element has no <code title=attr-script-src><a
|
|
href="#src2">src</a></code> attribute: depends on the scripting
|
|
language.
|
|
|
|
<dd>If the element does have a <code title=attr-script-src><a
|
|
href="#src2">src</a></code> attribute: none.
|
|
</dl>
|
|
|
|
<p class=note>The <code><a href="#script2">script</a></code> element
|
|
contains code that is executed when the XBL subtree is loaded. It can
|
|
therefore be used to define helper functions used by the bindings.</p>
|
|
|
|
<p>The <code><a href="#script2">script</a></code> element, when present,
|
|
must either contain code in the language specified by the XBL subtree's
|
|
<code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute, or have a <code
|
|
title=attr-script-src><a href="#src2">src</a></code> attribute that
|
|
points to a resource containing code in the language specified by the
|
|
<code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute. The syntax and
|
|
semantics of this code depend on the specific language. (See: <a
|
|
href="#loading6">loading and running scripts</a>.)</p>
|
|
|
|
<h4 class="no-toc no-num" id=attributes16>Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><dfn id=id12 title=attr-script-id>id</dfn>
|
|
|
|
<dd>The <a href="#id13" title=attr-id><code>id</code> attribute</a>.
|
|
|
|
<dt><dfn id=src2 title=attr-script-src>src</dfn>
|
|
|
|
<dd>The <code title=attr-script-src><a href="#src2">src</a></code>
|
|
attribute specifies the <a href="#attributes24">URI</a> to a resource of
|
|
the type given by the XBL subtree's <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute. If the attribute
|
|
is specified, the contents of the element must be ignored (even if the
|
|
resource could not be fetched or was of the wrong type). (See: <a
|
|
href="#loading6">loading and running scripts</a>.)
|
|
</dl>
|
|
|
|
<p>If an <code><a href="#script2">script</a></code> element is marked (via
|
|
the <code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code> attribute of the <code><a
|
|
href="#xbl0">xbl</a></code> element) as being in a language that the UA
|
|
does not support, the UA must <a href="#ignoring">ignore</a> it.
|
|
Similarly, if the <code><a href="#script2">script</a></code> element
|
|
points (using the <code title=attr-script-src><a
|
|
href="#src2">src</a></code> attribute) to a resource that is either
|
|
unavailable, or not of the type specified by the <code
|
|
title=attr-xbl-script-type><a href="#script-type">script-type</a></code>
|
|
attribute of the <code><a href="#xbl0">xbl</a></code> element (or implied
|
|
by its absence), then it is <a href="#in-error">in error</a> and the UA
|
|
must <a href="#ignoring">ignore</a> it. In both cases, "ignoring it"
|
|
means that the script must not be executed.</p>
|
|
|
|
<p>How UAs must handle nodes inside <code><a
|
|
href="#script2">script</a></code> elements depends on the language used.
|
|
(See: <a href="#loading6">loading and running scripts</a>.)</p>
|
|
|
|
<p><code><a href="#script2">script</a></code> blocks must be evaluated
|
|
when their end-tag is parsed, or, for dynamically created elements, when
|
|
they are first inserted into a document. This is the case whether or not
|
|
the elements are <a href="#in-error">in
|
|
error</a><!--[uncomment this is people
|
|
demand more] (because script processing is not considered to be part
|
|
of XBL processing)-->.
|
|
Once evaluation has started, a <code><a href="#script2">script</a></code>
|
|
block is dead and changes to its contents or attributes have no effect.</p>
|
|
|
|
<h3 id=the-id><span class=secno>2.16. </span>The <dfn id=id13
|
|
title=attr-id><code>id</code></dfn> Attribute of XBL Elements</h3>
|
|
|
|
<dl>
|
|
<dt>Expected element:
|
|
|
|
<dd>Any element in the XBL namespace.
|
|
</dl>
|
|
|
|
<p class=note>The <code title=attr-id><a href="#id13">id</a></code>
|
|
attribute assigns an identifier to an element.</p>
|
|
|
|
<p>The given identifier must be unique in the <a href="#binding15">binding
|
|
document</a>. The <code title=attr-id><a href="#id13">id</a></code>
|
|
attribute is of type ID. <a href="#refsXML">[XML]</a>.</p>
|
|
|
|
<p>If the attribute's value is the empty string, the attribute must not
|
|
set an ID. Otherwise, the attribute's value must be treated as (one of)
|
|
the element's ID(s).</p>
|
|
|
|
<h2 id=binding><span class=secno>3. </span><dfn id=binding17>Binding
|
|
Attachment and Detachment</dfn></h2>
|
|
|
|
<p>Bindings can be attached and detached dynamically, using several
|
|
mechanisms.</p>
|
|
|
|
<p>Bindings must be attached as soon as the following conditions have all
|
|
been met:</p>
|
|
|
|
<ul>
|
|
<li>it is known that the binding applies to the element,
|
|
|
|
<li>the DOM <code>Element</code> object for the element has been created,
|
|
and
|
|
|
|
<li>the binding document defining the binding has loaded.
|
|
</ul>
|
|
|
|
<p>In particular, binding can happen before the element is inserted into
|
|
its document.</p>
|
|
|
|
<p>If the binding document was already loaded when the element was
|
|
created, or when it became known that the element matched the binding
|
|
(e.g. because the binding's <code title=attr-binding-element><a
|
|
href="#element">element</a></code> attribute is mutated in a script),
|
|
then the binding must be applied such that to any running scripts,
|
|
notwithstanding those implementing <code><a
|
|
href="#xblbindingattached">xblBindingAttached()</a></code> notification
|
|
methods, it appears that the binding was applied immediately. When
|
|
mutation events are to fire, they must fire <em>after</em> the binding
|
|
being applied.</p>
|
|
|
|
<p>If the binding document has yet to be (fully) loaded when it becomes
|
|
known that the binding applies, then the user agent must wait until all
|
|
running scripts have completed before attaching the binding.</p>
|
|
<!-- XXX someone complained last time i used that term
|
|
("run to completion"), and suggested better text. In the WA1 spec, I
|
|
think. Use that here. [in the thread-safe storage bit, iirc] -->
|
|
|
|
<p class=note>If the binding attachment mechanism is the <code
|
|
title="binding property"><a href="#binding18">'binding'</a></code>
|
|
property, then it does not become known to the user agent that the
|
|
binding applies (or does not apply) until the next time style resolution
|
|
is performed. This specification does not define when style resolution
|
|
happens.</p>
|
|
<!-- XXX who does. HTML5? -->
|
|
<div class=example>
|
|
<p>Assume that <code title="">foo.xml</code> defines a binding that
|
|
applies to all "<code title="">foo</code>" elements. The following
|
|
script uses <code title=loadBindingDocument><a
|
|
href="#loadbindingdocument">loadBindingDocument()</a></code> to ensure
|
|
that <code title="">foo.xml</code> is loaded, then creates a <code
|
|
title="">foo</code> element and uses it.</p>
|
|
|
|
<pre>// load the binding document
|
|
document.loadBindingDocument('foo.xml'); // this is synchronous
|
|
|
|
// create an element <foo>
|
|
var foo = document.createElement('foo'); // binds synchronously too
|
|
foo.myCustomMethod(); // calls the binding's implementation</pre>
|
|
|
|
<p>Without the call to <code title=loadBindingDocument><a
|
|
href="#loadbindingdocument">loadBindingDocument()</a></code>, if the
|
|
binding document wasn't loaded yet the element wouldn't be bound
|
|
straight away, and the last line would fail.</p>
|
|
</div>
|
|
|
|
<p>Bindings must be detached as soon as it is known that the binding no
|
|
longer applies to the element. In the case of attachment using the '<code
|
|
title="binding property"><a href="#binding18">binding</a></code>'
|
|
property, this won't be until the next time style resolution is
|
|
performed.</p>
|
|
|
|
<p>When it becomes known that a binding is to be detached, it must happen
|
|
such that to any running scripts it appears that the binding was removed
|
|
immediately, except if the script in question is running as part of the
|
|
last step of the binding attachment process, in which case the detachment
|
|
happens after all the bindings being attached have had their methods
|
|
called. (See: <a href="#binding19">binding attachment model</a>.)</p>
|
|
<!-- XXX this contradicts what is said elsewhere; could make this
|
|
work by saying "except if there is an xblFoo notification method
|
|
running" or something -->
|
|
|
|
<h3 id=the-bindings-are-ready><span class=secno>3.1. </span><dfn
|
|
id=the-bindings-are-ready1>The Bindings-Are-Ready State</dfn></h3>
|
|
|
|
<p>XBL implementations must have a <dfn
|
|
id=bindings-are-ready>bindings-are-ready</dfn> counter (for each
|
|
<code>Document</code>) that keeps track of when there are outstanding
|
|
bindings to bind. This counter is set at the times given in the following
|
|
sections. (It is not set for all kinds of attachments.)</p>
|
|
|
|
<p>If the bound document is being parsed by the user agent, then, as soon
|
|
as all the following conditions have been met, the user agent must fire
|
|
an <dfn
|
|
id=xbl-bindings-are-ready><code>xbl-bindings-are-ready</code></dfn> event
|
|
on the document's root element. The conditions are:</p>
|
|
|
|
<ul>
|
|
<li> the document has finished parsing,
|
|
|
|
<li> the <a href="#bindings-are-ready">bindings-are-ready</a> counter is
|
|
at zero,
|
|
|
|
<li> all bindings that are known to apply to elements have been
|
|
completely applied, and
|
|
|
|
<li> no scripts are running.
|
|
</ul>
|
|
|
|
<p>The event must use the <code>Event</code> interface, must bubble, must
|
|
not be cancelable, and must not have a default action. <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>Initially, the <a href="#bindings-are-ready">bindings-are-ready</a>
|
|
counter must be set to zero.</p>
|
|
|
|
<p>The bound document's <code>load</code> event must not fire until after
|
|
the <code><a
|
|
href="#xbl-bindings-are-ready">xbl-bindings-are-ready</a></code> event
|
|
has fired. The <code><a
|
|
href="#xbl-bindings-are-ready">xbl-bindings-are-ready</a></code> event
|
|
must fire even in the complete absence of any use of XBL in the document.</p>
|
|
|
|
<p>The <code><a
|
|
href="#xbl-bindings-are-ready">xbl-bindings-are-ready</a></code> event
|
|
must only fire once per document load.</p>
|
|
|
|
<h3 id=attachment><span class=secno>3.2. </span><dfn id=attachment4
|
|
title="attachment using binding">Attachment using <code
|
|
title=binding><binding element=""></code></dfn></h3>
|
|
|
|
<p>The simplest binding mechanism is the <code><a
|
|
href="#binding16">binding</a></code> element's <code
|
|
title=attr-binding-element><a href="#element">element</a></code>
|
|
attribute. It declares which bindings should be attached to which
|
|
elements. (See: <a href="#attributes21" title=selector>attributes
|
|
containing selectors</a>, <a href="#element"
|
|
title=attr-binding-element>the <code title="">binding</code>
|
|
element</a>.)</p>
|
|
|
|
<p>While an element matches the <code title=attr-binding-element><a
|
|
href="#element">element</a></code> attribute of one or more of the
|
|
<code><a href="#binding16">binding</a></code> elements that is <a
|
|
href="#importing1" title=import>imported</a> into, or defined in, the
|
|
element's document, the bindings defined by each such <code><a
|
|
href="#binding16">binding</a></code> element must be bound to the
|
|
element. This applies to all elements that are associated with a
|
|
document, even when they have not yet been inserted into the document, or
|
|
are not in the <a href="#final0">final flattened tree</a>.</p>
|
|
|
|
<h4 id=importing><span class=secno>3.2.1. </span><dfn id=importing1
|
|
title=import>Importing Binding Documents</dfn></h4>
|
|
|
|
<p>There are two ways to import binding documents (and thus have their
|
|
<code title=binding><a href="#binding16"><binding
|
|
element=""></a></code> bindings apply): <a href="#the-ltxblgt"
|
|
title=xbl-pi>the <code><?xbl?></code> processing instruction</a>,
|
|
and the <code><a
|
|
href="#loadbindingdocument">loadBindingDocument()</a></code> method. The
|
|
latter is defined in the section on the <code><a
|
|
href="#documentxbl">DocumentXBL</a></code> interface.</p>
|
|
|
|
<p><dfn id=the-ltxblgt title=xbl-pi>The <code><?xbl?></code>
|
|
processing instruction</dfn> specifies a binding document to load. Any
|
|
bindings <a href="#attachment4" title="attachment using binding">defined
|
|
in that document</a> must be applied to matching elements in the document
|
|
with the processing instruction.</p>
|
|
|
|
<p><code><?xbl?></code> processing instructions that occur after the
|
|
root element's start tag in the markup are <a href="#in-error">in
|
|
error</a>. <code><?xbl?></code> PIs that are dynamically inserted
|
|
through the DOM after the root element's start tag has been parsed or the
|
|
root element has been attached to the document are <a href="#in-error">in
|
|
error</a> too.</p>
|
|
|
|
<p>A <code><?xbl?></code> processing instruction that is not <a
|
|
href="#in-error">in error</a> according to the above must be parsed using
|
|
the same syntax as the XML Stylesheet PI. <a
|
|
href="#refsXMLSSPI">[XMLSSPI]</a> If there are any parse errors, then the
|
|
entire processing instruction is <a href="#in-error">in error</a>.</p>
|
|
|
|
<p>Otherwise, if it has an <dfn id=href
|
|
title=attr-import-href><code>href</code></dfn> pseudo-attribute then it
|
|
specifies the <a href="#attributes24">URI</a> of the binding document to
|
|
import. If the URI cannot be resolved, or returns an error, or does not
|
|
point to a resource with <span>an XML MIME type</span><!-- XXX
|
|
xref -->,
|
|
or has any other problem that makes it unusable, then the processing
|
|
instruction is <a href="#in-error">in error</a>.</p>
|
|
|
|
<p>If a processing instruction is <a href="#in-error">in error</a> (as
|
|
described in the previous few paragraphs) then it must be ignored.</p>
|
|
|
|
<p>Otherwise, the referenced document must be loaded (unless it has <a
|
|
href="#loading5" title="loading external resources">already been
|
|
loaded</a>), and any bindings defined by that document must be applied to
|
|
matching elements in the document that contained the PI. Once loaded, the
|
|
binding document is added to the <code><a
|
|
href="#bindingdocuments">bindingDocuments</a></code> list of the document
|
|
with the PI.</p>
|
|
|
|
<p>Dynamic changes to <code><?xbl?></code> processing instructions
|
|
must be ignored from an XBL standpoint.</p>
|
|
|
|
<p>An imported binding document is <em>live</em>.</p>
|
|
|
|
<p class=example>For example, if new <code><a
|
|
href="#binding16">binding</a></code> elements are added to an imported
|
|
binding document (via the DOM), then the new bindings are immediately
|
|
applied to the document that had the PI importing that binding document.</p>
|
|
|
|
<p>XBL bindings are always implicitly imported into the document in which
|
|
they are defined.</p>
|
|
|
|
<p>Whenever an <code><?xbl?></code> PI causes a binding document to be
|
|
loaded, the document's <a
|
|
href="#bindings-are-ready">bindings-are-ready</a> counter must be
|
|
increased by one. Once the binding document is loaded, the counter must
|
|
be decreased by one.</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.xml</strong>
|
|
|
|
<...>
|
|
<xbl xmlns="http://www.w3.org/ns/xbl" ...>
|
|
<binding element="foo">
|
|
...
|
|
</binding>
|
|
<binding element="bar">
|
|
...
|
|
</binding>
|
|
</xbl ...>
|
|
<foo xmlns=""/> <!-- this will have a binding applied -->
|
|
<bar xmlns=""/> <!-- this will have a binding applied -->
|
|
</...>
|
|
</pre>
|
|
|
|
<p>If the binding definitions are in a separate file, then that file
|
|
needs to be imported explicitly:</p>
|
|
|
|
<pre><strong>widgets.xml</strong>
|
|
|
|
<...>
|
|
<xbl xmlns="http://www.w3.org/ns/xbl" ...>
|
|
<binding element="foo">
|
|
...
|
|
</binding>
|
|
<binding element="bar">
|
|
...
|
|
</binding>
|
|
</xbl ...>
|
|
</...>
|
|
</pre>
|
|
|
|
<pre><strong>example.xml</strong>
|
|
|
|
<em><?xbl href="widgets.xml"?></em>
|
|
<...>
|
|
<foo/> <!-- bound -->
|
|
<bar/> <!-- bound -->
|
|
</...>
|
|
</pre>
|
|
|
|
<p>If a file imports some bindings and the file containing those bindings
|
|
has its own <code><?xbl?></code> processing instructions, that
|
|
second PI only affects nodes in the binding document, not the original
|
|
document. For example:</p>
|
|
|
|
<pre><strong>foo.xml</strong>
|
|
|
|
<...>
|
|
<xbl xmlns="http://www.w3.org/ns/xbl" ...>
|
|
<binding element="foo">
|
|
<content>
|
|
<bar xmlns=""/> <!-- not bound, not even when in shadow content -->
|
|
</content>
|
|
</binding>
|
|
</xbl>
|
|
</...>
|
|
</pre>
|
|
|
|
<pre><strong>bar.xml</strong>
|
|
|
|
<?xbl href="foo.xml"?>
|
|
<...>
|
|
<xbl xmlns="http://www.w3.org/ns/xbl" ...>
|
|
<binding element="bar">
|
|
<content>
|
|
<foo xmlns=""/> <!-- bound: this document imports foo.xml -->
|
|
<bar xmlns=""/> <!-- bound: bar binding is defined locally -->
|
|
</content>
|
|
</binding>
|
|
</xbl>
|
|
</...>
|
|
</pre>
|
|
|
|
<pre><strong>example.xml</strong>
|
|
|
|
<?xbl href="bar.xml"?>
|
|
<...>
|
|
<foo/> <!-- not bound: foo.xml not imported here -->
|
|
<bar/> <!-- bound -->
|
|
</...>
|
|
</pre>
|
|
</div>
|
|
|
|
<h3 id=attachment0><span class=secno>3.3. </span>Attachment using CSS</h3>
|
|
|
|
<p>Bindings can be attached to elements through CSS using the '<code
|
|
title="binding property"><a href="#binding18">binding</a></code>'
|
|
property.</p>
|
|
|
|
<div class=example>
|
|
<p>In the following example, a binding is referenced that will be
|
|
attached to all XHTML checkbox elements.</p>
|
|
|
|
<pre>
|
|
input[type="checkbox"] {
|
|
binding: url("http://www.example.org/xbl/htmlBindings.xml#checkbox");
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>Bindings attached through CSS must only remain on the bound element as
|
|
long as the element continues to match the style rule. If at any time a
|
|
resolution of style on the element determines that a different binding
|
|
should be attached, the old binding (and all bindings that it explicitly
|
|
extends in its <a href="#explicit1">explicit inheritance chain</a>) must
|
|
be detached.</p>
|
|
|
|
<p>Whenever an element is removed from a document, any bindings attached
|
|
to that element via CSS must be detached.</p>
|
|
|
|
<p class=note>Attaching a binding using CSS does not <a
|
|
href="#importing1">import</a> the binding document. The <code
|
|
title=attr-binding-element><a href="#element">element</a></code>
|
|
attributes of <code><a href="#binding16">binding</a></code> elements in
|
|
the binding document do not take effect unless the binding document is
|
|
imported. (See: <a href="#importing1" title=import>importing binding
|
|
documents</a>.)</p>
|
|
|
|
<p>Attaching using CSS does not affect the <a
|
|
href="#bindings-are-ready">bindings-are-ready</a> counter.</p>
|
|
|
|
<h4 id=the-binding0><span class=secno>3.3.1. </span>The '<code
|
|
title="binding property"><a href="#binding18">binding</a></code>'
|
|
Property</h4>
|
|
|
|
<p>A property to attach a binding to a particular element.</p>
|
|
|
|
<table class=propdef id=binding6>
|
|
<caption> <dfn id=binding18 title="binding
|
|
property">'<code>binding</code>'</dfn></caption>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td><em>Value:</em>
|
|
|
|
<td>none | [ <uri> ]* <uri>
|
|
<!--XXXPD <predefined binding>-->
|
|
|
|
<tr>
|
|
<td><em>Initial:</em>
|
|
|
|
<td>none
|
|
|
|
<tr>
|
|
<td><em>Applies To:</em>
|
|
|
|
<td>all elements (but not pseudo-elements)
|
|
|
|
<tr>
|
|
<td><em title="">Inherited:</em>
|
|
|
|
<td>no
|
|
|
|
<tr>
|
|
<td><em>Percentages:</em>
|
|
|
|
<td>n/a
|
|
|
|
<tr>
|
|
<td><em>Media:</em>
|
|
|
|
<td>all
|
|
|
|
<tr>
|
|
<td><em>Computed Value:</em>
|
|
|
|
<td>specified value, with URIs resolved to absolute URIs
|
|
</table>
|
|
|
|
<dl>
|
|
<dt>none
|
|
|
|
<dd>No bindings are to be attached through CSS.
|
|
|
|
<dt><uri>
|
|
|
|
<dd>The specified binding is attached. More than one binding can be
|
|
specified, resulting in the bindings being attached in the specified
|
|
order, with the last binding implicitly inheriting from the previous
|
|
one, and so forth, up to the first binding. (See: <a
|
|
href="#binding20">binding inheritance</a>.)</dd>
|
|
<!--XXXPB
|
|
<dt><predefined binding></dt>
|
|
<dd>One of the bindings defined in the <a
|
|
href="#base-bindings">Predefined Base Bindings</a> section is
|
|
attached.</dd>
|
|
-->
|
|
</dl>
|
|
|
|
<h4 id=processing><span class=secno>3.3.2. </span>Processing Model</h4>
|
|
|
|
<p>User agents may perform the CSS cascade, inheritance, and computation
|
|
stages either across the entire tree, or per element, or per property per
|
|
element, and either before applying bindings, or simultaneously, while
|
|
applying bindings. In any case, for each element the computed value of
|
|
'<code title="binding property"><a href="#binding18">binding</a></code>'
|
|
must be found and then used to apply the bindings to the element (when
|
|
the element is first styled, and each subsequent time the styles that
|
|
match the element change).</p>
|
|
|
|
<p>Since each time a binding is applied it can change the computed values
|
|
of properties of elements that are descendants of the bound element, this
|
|
may require several passes. This may be avoided by computing the value of
|
|
the '<code title="binding property"><a
|
|
href="#binding18">binding</a></code>' property for the element, and then
|
|
applying any bindings, before any of its descendants.</p>
|
|
|
|
<h4 id=examples><span class=secno>3.3.3. </span>Examples</h4>
|
|
|
|
<div class=example id=triangles-example>
|
|
<p>The following XBL document defines two bindings for use in SVG. The
|
|
first renders an isosceles triangle in place of bound elements that use
|
|
it, the other renders a right-angled triangle in place of bound elements
|
|
that use it.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl"
|
|
xmlns:xbl="http://www.w3.org/ns/xbl">
|
|
<binding id="isosceles">
|
|
<template>
|
|
<polygon xbl:attr="transform" points="0 -1, 1 0, -1 0" xmlns="http://www.w3.org/2000/svg"/>
|
|
</template>
|
|
</binding>
|
|
<binding id="rightangle">
|
|
<template>
|
|
<polygon xbl:attr="transform" points="0 0, 1 0, 0 -1" xmlns="http://www.w3.org/2000/svg"/>
|
|
</template>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>Assuming the above file was called <code>triangles.xml</code>, these
|
|
bindings could be bound to elements using CSS like so:</p>
|
|
|
|
<pre>@namespace triangles url(http://triangles.example.com/);
|
|
triangles|isosceles { binding: url(triangles.xml#isosceles); }
|
|
triangles|rightangle { binding: url(triangles.xml#rightangle); }</pre>
|
|
|
|
<p>If the stylesheet was called <code>triangles.css</code>, an SVG file
|
|
using these elements might look like:</p>
|
|
|
|
<pre><?xml-stylesheet href="triangles.css"?>
|
|
<svg xmlns="http://www.w3.org/2000/svg"
|
|
xmlns:t="http://triangles.example.com/">
|
|
<circle cx="10" cy="10" r="5"/>
|
|
<rect x="20" y="20" height="5" width="10"/>
|
|
<t:isosceles transform="translate(10 20) scale(10)"/>
|
|
<t:rightangle transform="translate(20 20) scale(10)"/>
|
|
</svg></pre>
|
|
|
|
<p>The same example could also be done all in one file like this:</p>
|
|
|
|
<pre><svg xmlns="http://www.w3.org/2000/svg"
|
|
xmlns:t="http://triangles.example.com/">
|
|
<defs>
|
|
<xbl xmlns="http://www.w3.org/ns/xbl"
|
|
xmlns:xbl="http://www.w3.org/ns/xbl">
|
|
<binding id="isosceles">
|
|
<template>
|
|
<polygon xbl:attr="transform" points="0 -1, 1 0, -1 0" xmlns="http://www.w3.org/2000/svg"/>
|
|
</template>
|
|
</binding>
|
|
<binding id="rightangle">
|
|
<template>
|
|
<polygon xbl:attr="transform" points="0 0, 1 0, 0 -1" xmlns="http://www.w3.org/2000/svg"/>
|
|
</template>
|
|
</binding>
|
|
</xbl>
|
|
<style type="text/css">
|
|
@namespace triangles url(http://triangles.example.com/);
|
|
triangles|isosceles { binding: url(#isosceles); }
|
|
triangles|rightangle { binding: url(#rightangle); }
|
|
</style>
|
|
</defs>
|
|
<circle cx="10" cy="10" r="5"/>
|
|
<rect x="20" y="20" height="5" width="10"/>
|
|
<t:isosceles transform="translate(10 20) scale(10)"/>
|
|
<t:rightangle transform="translate(20 20) scale(10)"/>
|
|
</svg></pre>
|
|
</div>
|
|
|
|
<h3 id=attachment1><span class=secno>3.4. </span>Attachment using the DOM</h3>
|
|
|
|
<p>Bindings can be attached to elements through the DOM using the <a
|
|
href="#dom-interfaces"><code>ElementXBL</code></a> interface. The method
|
|
<code><a href="#addbinding">addBinding</a></code> takes a binding URI and
|
|
attaches the binding to the element (in all <a href="#view"
|
|
title=view>views</a>).</p>
|
|
|
|
<pre class="dom
|
|
example">var checkbox = document.getElementById("mycheckbox");
|
|
checkbox.addBinding("http://www.example.org/xbl/htmlBindings.xml#checkbox");</pre>
|
|
|
|
<p>This attachment is not necessarily synchronous. Scripts that invoke
|
|
this method should not assume that the binding is installed immediately
|
|
after this method returns. (An <code><a
|
|
href="#xbl-bound">xbl-bound</a></code> event is fired when the binding is
|
|
installed.)</p>
|
|
|
|
<p>When a binding is attached using the DOM, it inherits from the current
|
|
<a href="#most-derived">most derived binding</a> that is already attached
|
|
to the element, if any. (See: <a href="#binding20">binding
|
|
inheritance</a>.)</p>
|
|
|
|
<p>Any bindings attached to an element using the <code><a
|
|
href="#addbinding">addBinding()</a></code> method will remain on the
|
|
element until the element is destroyed or a corresponding <code><a
|
|
href="#removebinding">removeBinding()</a></code> call is made.</p>
|
|
|
|
<p class=note>Attaching a binding using the <code><a
|
|
href="#addbinding">addBinding()</a></code> DOM APIs does not <a
|
|
href="#importing1">import</a> the binding document. The <code
|
|
title=attr-binding-element><a href="#element">element</a></code>
|
|
attributes of <code><a href="#binding16">binding</a></code> elements in
|
|
the binding document do not take effect unless the binding document is
|
|
imported. (See: <a href="#importing1" title=import>importing binding
|
|
documents</a>.)</p>
|
|
|
|
<p>Attaching using the <code><a href="#addbinding">addBinding()</a></code>
|
|
API does not affect the <a
|
|
href="#bindings-are-ready">bindings-are-ready</a> counter.</p>
|
|
|
|
<h3 id=binding0><span class=secno>3.5. </span><dfn id=binding19>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>If the binding has an <code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code> attribute, then the user agent must
|
|
immediately consider the binding that the attributes references (if any)
|
|
to apply to the bound element as well, and must attach that binding
|
|
first, recursively applying these steps to that binding. If this causes
|
|
a loop — that is, if a binding directly or indirectly derives from
|
|
itself through a chain of one or more <code
|
|
title=attr-binding-extends><a href="#extends">extends</a></code>
|
|
attributes — then the user agent must only apply each binding in
|
|
the chain once. (See: <a href="#explicit2">explicit inheritance</a>, <a
|
|
href="#interpretation1">interpretation of URIs to XBL bindings</a>.)
|
|
|
|
<li>If the binding has a template, the binding's shadow tree must be
|
|
generated. This may cause other bindings to be applied synchronously, if
|
|
their binding documents are already loaded. (See: <a
|
|
href="#rules3">rules for shadow content generation</a>, <a
|
|
href="#binding17">binding attachment and detachment</a>.)
|
|
|
|
<li>If other bindings are already attached to the bound element, then the
|
|
newly added binding will add a new <a href="#explicit1">explicit
|
|
inheritance chain</a> to the element's list of bindings (its <a
|
|
href="#implicit1">implicit inheritance chain</a>). (See: <a
|
|
href="#implicit2">implicit inheritance</a>.)
|
|
|
|
<li>If the new binding has an implementation, it must be made available
|
|
to scripts. Language-specific constructors for the binding
|
|
implementation must run at this point. (See: <a
|
|
href="#binding23">binding implementations</a>.)
|
|
|
|
<li>Events must start being routed through the binding's <code><a
|
|
href="#handlers0">handlers</a></code> element, when there is one. (See:
|
|
<a href="#event12">event forwarding</a>.)
|
|
|
|
<li>If the new binding changes which shadow trees contribute to the <a
|
|
href="#final0">final flattened tree</a> then the <a
|
|
href="#explicit3">explicit children</a> must be redistributed. (See: <a
|
|
href="#processing2">processing <code title="">content</code>
|
|
elements</a>.)
|
|
</ol>
|
|
|
|
<p>The attachment process for the binding must then wait for the above
|
|
steps to have been completed for all bindings that are known to apply to
|
|
elements. When all the new bindings have reached this point, then, for
|
|
each newly attached binding, the <code><a
|
|
href="#xblbindingattached">xblBindingAttached()</a></code> method must be
|
|
invoked on the binding's <a href="#implementation0">implementation</a>,
|
|
immediately followed, if that bound element <a href="#is-in">is in a
|
|
document</a>, by the invocation of the <code><a
|
|
href="#xblentereddocument">xblEnteredDocument()</a></code> method.
|
|
|
|
<p>The order that bindings on different bound elements have these methods
|
|
called must be the relative tree order of all their bound elements, as
|
|
returned by the <code>compareDocumentPosition()</code> function. In
|
|
certain cases (e.g. bound elements in disconnected fragments), this order
|
|
is implementation-specific; however, it must always be consistent with
|
|
the return values of that function. <a
|
|
href="#refsDOM3CORE">[DOM3CORE]</a></p>
|
|
|
|
<p>The order that bindings on the same bound element have these methods
|
|
called must be the derivation order, with less derived bindings being
|
|
initialized before more derived bindings.</p>
|
|
|
|
<p>After all the appropriate methods have been called, an <dfn
|
|
id=xbl-bound title=xbl-bound><code>xbl-bound</code></dfn> event that
|
|
bubbles, is not cancelable, has no default action, and uses the
|
|
<code>Event</code> interface, must be fired on every bound element that
|
|
just got bound, in the same order as their <code><a
|
|
href="#xblbindingattached">xblBindingAttached()</a></code> methods were
|
|
invoked. (See: <a href="#binding20">binding inheritance</a>.) <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>If a binding stops applying to a document while the above steps are
|
|
being applied, the binding is not removed until after the steps above
|
|
have all been completed. Once they have been completed, any bindings that
|
|
no longer apply must be detached. (See: <a href="#binding21">binding
|
|
detachment model</a>.)</p>
|
|
|
|
<h3 id=handling><span class=secno>3.6. </span><dfn id=handling3>Handling
|
|
Insertion and Removal from the Document</dfn></h3>
|
|
|
|
<p>A bound element <dfn id=is-in>is in a document</dfn> if it has a
|
|
<code>Document</code> node as an ancestor, or it is in a shadow tree and
|
|
that shadow tree's bound element is itself <a href="#is-in" title="is in
|
|
a document">in a document</a>.</p>
|
|
|
|
<p>When a bound element that is not <a href="#is-in" title="is in a
|
|
document">in a document</a> is affected in such a way that it
|
|
subsequently <a href="#is-in"><em>is</em> in a document</a>, then the
|
|
<code><a href="#xblentereddocument">xblEnteredDocument()</a></code>
|
|
method must be invoked on the binding's <a
|
|
href="#implementation0">implementation</a>.</p>
|
|
|
|
<p>Similarly in reverse: when a bound element that <a
|
|
href="#is-in"><em>is</em> in a document</a> is affected in such a way
|
|
that it subsequently is <em>not</em> <a href="#is-in" title="is in a
|
|
document">in a document</a>, then the <code><a
|
|
href="#xblleftdocument">xblLeftDocument()</a></code> method must be
|
|
invoked on the binding's <a href="#implementation0">implementation</a>.</p>
|
|
|
|
<p>These methods must be invoked as soon as the DOM is in a stable state,
|
|
after any mutation events have fired, and after all running scripts have
|
|
finished executing. If a bound element is removed and then reinserted
|
|
into a document (or vice versa) during script execution, or while
|
|
mutation events are being fired, the user agent must coalesce all the
|
|
notifications into zero or one method calls (i.e. matching pairs of
|
|
insertions and removals must not cause bindings to be notified).</p>
|
|
<!-- XXX this needs work -->
|
|
<h3 id=binding1><span class=secno>3.7. </span><dfn id=binding20>Binding
|
|
Inheritance</dfn></h3>
|
|
|
|
<p>Bindings can inherit from each other explicitly using the <code
|
|
title=attr-binding-extends><a href="#extends">extends</a></code>
|
|
attribute. They can also inherit from each other <em>implicitly</em> if
|
|
multiple bindings are attached to an element.</p>
|
|
|
|
<div class="figure example">
|
|
<!-- Note: alt="" is correct for the following image, since the
|
|
caption says everything the image says. -->
|
|
|
|
<p><img alt="" src="images/attachment.gif"></p>
|
|
|
|
<div class=caption>
|
|
<p>The implicit inheritance link can be pictured as having several
|
|
explicit chains adjacent to each other, with the implicit inheritance
|
|
chain going down each explicit inheritance chain sequentially.</p>
|
|
|
|
<p>Consider a case where seven bindings are defined, "a", which inherits
|
|
from "b" which inherits from "c"; "d", which stands alone; and "e",
|
|
which inherits from "f" which inherits from "g". If a bound element E
|
|
is bound to "a", "b", "d", and "e" (with "e" bound last), then there
|
|
would be nine bindings attached to E. Four of them would be explicitly
|
|
bound, and five would be part of explicit inheritance chains from those
|
|
four.</p>
|
|
|
|
<p>In such an example, you would also get implicit inheritance from "g"
|
|
to "d", from "d" to "b", and from one of the instances of "c" to "a".</p>
|
|
</div>
|
|
</div>
|
|
|
|
<p>An <dfn id=explicit1>explicit inheritance chain</dfn> is a chain of
|
|
bindings connected using the <code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code> attribute.</p>
|
|
|
|
<p>An <dfn id=implicit1>implicit inheritance chain</dfn> is a chain of <a
|
|
href="#explicit1" title="explicit inheritance chain">explicit inheritance
|
|
chains</a>. There can be at most one <em>implicit</em> inheritance chain
|
|
per bound element.</p>
|
|
|
|
<p>A <dfn id=base-binding>base binding</dfn> is a binding that does not
|
|
inherit from any other binding, either explicitly or implicitly. The base
|
|
binding of a bound element is at one end of the bound element's implicit
|
|
inheritance chain.</p>
|
|
|
|
<p>A <dfn id=base-binding0>base binding of the explicit chain</dfn> is any
|
|
binding that does not inherit explicitly from another, but may inherit
|
|
implicitly from other bindings.</p>
|
|
|
|
<p>A <dfn id=most-derived>most derived binding</dfn> is a binding that no
|
|
other binding inherits from. The most derived binding of a bound element
|
|
is the binding at the other end of the bound element's implicit
|
|
inheritance chain from the base binding.</p>
|
|
|
|
<p>If <var title="">B<sub title=""><var title="">i</var></sub></var> is
|
|
the <var title="">i</var>th binding in a group of <var title="">N</var>
|
|
chains, where <var title="">B<sub title="">1</sub></var> is the <a
|
|
href="#base-binding">base binding</a> and <var title="">B<sub
|
|
title=""><var title="">N</var></sub></var> is the <a
|
|
href="#most-derived">most derived binding</a>, then <var title="">B<sub
|
|
title=""><var title="">i</var>-1</sub></var> is the <dfn id=next->next
|
|
most derived</dfn> binding of <var title="">B<sub title=""><var
|
|
title="">i</var></sub></var>.</p>
|
|
|
|
<p>In this specification, inheritance is represented as an arrow pointing
|
|
to the binding that is being inherited. Thus, in the chain A→B, the
|
|
A binding is the most derived binding, and the B binding is the next most
|
|
derived binding, in this case also the base binding.</p>
|
|
|
|
<p class=example>In the example above, the <em><a
|
|
href="#base-binding">base binding</a></em> is the first "c", the four <em
|
|
title="base binding of the explicit chain"><a href="#base-binding0">base
|
|
bindings of the explicit chains</a></em> are "c", "c", "d", and "g", and
|
|
the <em><a href="#most-derived">most derived binding</a></em> is "e".</p>
|
|
|
|
<p class=note>The results of inheritance are described in the sections on
|
|
<a href="#binding23">binding implementations</a> and <a
|
|
href="#shadow5">shadow content</a>.</p>
|
|
|
|
<h4 id=explicit><span class=secno>3.7.1. </span><dfn id=explicit2>Explicit
|
|
Inheritance</dfn></h4>
|
|
|
|
<p>The <code><a href="#binding16">binding</a></code> element's <code
|
|
title=attr-binding-extends><a href="#extends">extends</a></code>
|
|
attribute gives an explicit inheritance chain for a binding, ensuring
|
|
that whenever the binding is bound to an element, the named binding also
|
|
gets bound. (See: <a href="#binding19">binding attachment model</a>, <a
|
|
href="#binding21">binding detachment model</a>.)</p>
|
|
|
|
<p>The <code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code> attribute thus creates an <a
|
|
href="#explicit1">explicit inheritance chain</a>.</p>
|
|
|
|
<p>If a <code><a href="#binding16">binding</a></code> element's <code
|
|
title=attr-binding-extends><a href="#extends">extends</a></code>
|
|
attribute is changed, then, for each time the binding is bound to an
|
|
element, the user agent must follow these steps:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Let <var title="">binding</var> be the instance of the binding that
|
|
is attached to the bound element.</p>
|
|
|
|
<li>
|
|
<p>If <var title="">binding</var> is not <em>directly</em> attached to
|
|
the bound element, but is instead attached to the bound element because
|
|
another binding is inheriting from it using the <code
|
|
title=attr-binding-extends><a href="#extends">extends</a></code>
|
|
attribute, then let <var title="">binding</var> be <em>that</em>
|
|
binding instead, and repeat this step.</p>
|
|
|
|
<p>Otherwise, <var title="">binding</var> was attached to the bound
|
|
element directly, and is not being inherited by another binding using
|
|
the <code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code> attribute.</p>
|
|
|
|
<li>
|
|
<p>Detach <var title="">binding</var>. (See: <a
|
|
href="#binding21">binding detachment model</a>.)</p>
|
|
|
|
<li>
|
|
<p>Attach a new instance of <var title="">binding</var> so that it is in
|
|
the same place in the binding chain as the old instance was. (See: <a
|
|
href="#binding19">binding attachment model</a>, <a
|
|
href="#implicit2">implicit inheritance</a>.)</p>
|
|
</ol>
|
|
|
|
<p class=note>It is possible to form a loop with the <code
|
|
title=attr-binding-extends><a href="#extends">extends</a></code>
|
|
attribute. For example, a binding A can inherit from B which inherits
|
|
from C which inherits from B again. The attachment algorithm is defined
|
|
in a way that makes the loop stop as soon as a duplicate binding would be
|
|
bound. In this case, the user agent will form a chain starting with A
|
|
(the <a href="#most-derived">most derived binding</a>), derived from B,
|
|
derived from C, with C as the <a href="#base-binding">base binding</a>
|
|
(chain A→B→C). If, given the same definitions, the element was
|
|
bound directly to C, then the chain would be C→B.</p>
|
|
|
|
<h4 id=implicit><span class=secno>3.7.2. </span><dfn id=implicit2>Implicit
|
|
Inheritance</dfn></h4>
|
|
|
|
<p>When two bindings are both attached to the same element, the <a
|
|
href="#base-binding0" title="base binding of the explicit chain">base
|
|
binding</a> at the end of the <a href="#explicit1">explicit inheritance
|
|
chain</a> of the second binding implicitly inherits from the <a
|
|
href="#most-derived">most derived binding</a> of the explicit inheritance
|
|
chain of the first.</p>
|
|
|
|
<p>If one of the <a href="#explicit1" title="explicit inheritance
|
|
chain">explicit inheritance chains</a> is removed, then the remaining
|
|
binding chains are reconnected so that the <a href="#base-binding0">base
|
|
binding of the explicit chain</a> after the break now inherits from the
|
|
<a href="#most-derived">most derived binding</a> before the break.</p>
|
|
|
|
<p>The order of bindings is always such that bindings added via the
|
|
<code><a href="#binding16">binding</a></code> element are first (in the
|
|
order the bindings are specified in the file, with the files, if there
|
|
are more than one, ordered in the same order that they are referred to,
|
|
traversed pre-order, depth-first), the bindings attached via CSS are
|
|
second (in the order specified on the '<code title="binding property"><a
|
|
href="#binding18">binding</a></code>' property), and the bindings added
|
|
via <code><a href="#addbinding">addBinding</a></code> are third (in the
|
|
order they were attached, most recently attached being the <a
|
|
href="#most-derived">most derived binding</a>).</p>
|
|
|
|
<div class=example>
|
|
<p>For example, take a binding <em>d<sub>1</sub></em>, which specifies a
|
|
base binding <em>d<sub>2</sub></em> using the <code
|
|
title=attr-binding-extends><a href="#extends">extends</a></code>
|
|
attribute such that its explicit inheritance chain is:</p>
|
|
|
|
<p><em>d<sub>1</sub></em> → <em>d<sub>2</sub></em></p>
|
|
|
|
<p>If binding <em>d<sub>1</sub></em> is attached to an element using
|
|
<code><a href="#addbinding">addBinding</a></code> that already has a
|
|
binding chain of:</p>
|
|
|
|
<p><em>s<sub>1</sub></em> → <em>s<sub>2</sub></em> →
|
|
<em>s<sub>3</sub></em></p>
|
|
|
|
<p>...then the base binding at the end of the inheritance chain,
|
|
<em>d<sub>2</sub></em>, is the one that will inherit from the most
|
|
derived binding that is already attached to the element,
|
|
<em>s<sub>1</sub></em>. The resulting binding chain following the
|
|
addition of the binding is therefore:</p>
|
|
|
|
<p><em>d<sub>1</sub></em> → <em>d<sub>2</sub></em> →
|
|
<em>s<sub>1</sub></em> → <em>s<sub>2</sub></em> →
|
|
<em>s<sub>3</sub></em></p>
|
|
|
|
<p>The inheritance between <em>d<sub>2</sub></em> and
|
|
<em>s<sub>1</sub></em> is <em>implicit</em>, meaning that there is no
|
|
connection in the XBL subtrees between the two bindings. The inheritance
|
|
link has been forged dynamically through the invocation of the <code><a
|
|
href="#addbinding">addBinding</a></code> method.</p>
|
|
</div>
|
|
|
|
<p>An element can be bound to the same binding multiple times, in which
|
|
case a binding can end up inheriting from itself. (This can only happen
|
|
via implicit inheritance, though.)</p>
|
|
|
|
<h4 id=mixing><span class=secno>3.7.3. </span>Mixing Implicit and Explicit
|
|
Inheritance</h4>
|
|
|
|
<div class=example id=mixed-inheritance-example>
|
|
<p>Consider the following completely useless but short bindings:</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="a">
|
|
<template> l <inherited> l <content> o </content> - </inherited> W </template>
|
|
</binding>
|
|
<binding id="b" element="[X]" extends="#a">
|
|
<template> e <inherited> error </inherited> o <content> r </content> </template>
|
|
</binding>
|
|
<binding id="c" element="[Y]">
|
|
<template> H <inherited> error </inherited> l <content> error </content> ! </template>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>When imported by the following equally silly but simple document:</p>
|
|
|
|
<pre><?xbl href="test.xml"?>
|
|
<root X="" Y=""> d </root></pre>
|
|
|
|
<p>The resulting flattened tree would spell
|
|
"H e l l o - W o r l d !".</p>
|
|
|
|
<p>
|
|
|
|
<p>The binding "c" that attaches because of the Y attribute implicitly
|
|
inherits from the binding "b" that is bound because of the X attribute,
|
|
and that latter binding explicitly inherits from the "a" binding. Since
|
|
the "Y" binding has a <code><a href="#content0">content</a></code>
|
|
element, the "d" explicit child node of the bound element ends up
|
|
assigned to the <code><a href="#content0">content</a></code> element in
|
|
the "Y" binding.</p>
|
|
|
|
<p>The following table shows the source of each character:</p>
|
|
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<th> Output:
|
|
|
|
<td> H
|
|
|
|
<td> e
|
|
|
|
<td> l
|
|
|
|
<td> l
|
|
|
|
<td> o
|
|
|
|
<td> -
|
|
|
|
<td> W
|
|
|
|
<td> o
|
|
|
|
<td> r
|
|
|
|
<td> l
|
|
|
|
<td> d
|
|
|
|
<td> !
|
|
|
|
<tr>
|
|
<th> Source:
|
|
|
|
<td> c
|
|
|
|
<td> b
|
|
|
|
<td> a
|
|
|
|
<td> a
|
|
|
|
<td> a
|
|
|
|
<td> a
|
|
|
|
<td> a
|
|
|
|
<td> b
|
|
|
|
<td> b
|
|
|
|
<td> c
|
|
|
|
<td> R
|
|
|
|
<td> c
|
|
</table>
|
|
|
|
<p>...where R represents the bound document.</p>
|
|
|
|
<p>The inheritance chain of the bindings attached to the <code
|
|
title="">root</code> element in this example is:</p>
|
|
|
|
<pre>c → b → a</pre>
|
|
|
|
<p>...where the first arrow is an implicit inheritance, and the second is
|
|
an explicit inheritance.</p>
|
|
</div>
|
|
|
|
<h3 id=views><span class=secno>3.8. </span>Views and Attachment</h3>
|
|
|
|
<p>Only one set of bindings is attached to the document, and they must
|
|
affect all views in a <a href="#view" title=view>multi-view UA</a>.
|
|
Bindings attached via style sheets must be attached based on the style
|
|
sheets that apply to the default view.</p>
|
|
|
|
<h3 id=attachment2><span class=secno>3.9. </span>Attachment During
|
|
Document Load</h3>
|
|
|
|
<p>Binding loads are asynchronous. That is to say, when a binding is added
|
|
(either via style sheet, script, or some other method), and the relevant
|
|
<a href="#binding15">binding document</a> is not yet loaded, the load
|
|
must be started in the background and the binding only attached once the
|
|
binding document is available. An author can ensure that all bindings are
|
|
synchronously attached by calling <code><a
|
|
href="#loadbindingdocument">loadBindingDocument</a></code> to pre-fetch
|
|
any binding documents that are required.</p>
|
|
|
|
<p>The bound document must wait until all XBL dependencies have loaded
|
|
before firing its <code title=event-load>load</code> event.</p>
|
|
|
|
<h3 id=binding2><span class=secno>3.10. </span><dfn id=binding21>Binding
|
|
Detachment Model</dfn></h3>
|
|
|
|
<p>When a binding is detached, the <code><a
|
|
href="#xblleftdocument">xblLeftDocument()</a></code> method must be
|
|
invoked on the binding's <a href="#implementation0">implementation</a>.
|
|
Then, the shadow tree must be removed, the implementation must be removed
|
|
from the bound element's list of binding implementations, and any
|
|
forwarding of events to the binding must be stopped for this bound
|
|
element.</p>
|
|
|
|
<p>If the binding had an <code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code> attribute when it was bound to the
|
|
element (it may have changed since then, in which case the binding is
|
|
being detached precisely for that reason), then the user agent must then
|
|
detach the binding that was attached because of that attribute (if any).
|
|
(See: <a href="#explicit2">explicit inheritance</a>, <a
|
|
href="#interpretation1">interpretation of URIs to XBL bindings</a>.)
|
|
|
|
<p>If the binding had a shadow tree, the explicit children must then be
|
|
redistributed. (See: <a href="#processing2">processing <code
|
|
title="">content</code> elements</a>.)</p>
|
|
<!-- XXX need to define how this works when multiple bindings stop
|
|
applying at once, and if they re-apply while being removed -->
|
|
|
|
<h2 id=shadow><span class=secno>4. </span><dfn id=shadow5>Shadow
|
|
Content</dfn></h2>
|
|
|
|
<p>The subtree specified by the <code><a
|
|
href="#template0">template</a></code> element is referred to as the <dfn
|
|
id=shadow6>shadow content template</dfn>. 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>A <dfn id=shadow7>shadow tree</dfn> is a tree of nodes created by
|
|
cloning a binding's <a href="#shadow6">shadow content template</a>. A
|
|
bound element can have zero, one, or more shadow trees. If a bound
|
|
element has any, they are combined by the user agent, along with the
|
|
element's <a href="#explicit3">explicit children</a>, to form the <a
|
|
href="#final0">final flattened tree</a>. Shadow trees are hidden from
|
|
normal DOM processing (hence the name "shadow"); they are not accessible
|
|
via Core DOM navigation facilities such as <code>firstChild</code> or
|
|
<code>nextSibling</code>. (See: <a href="#shadow5">shadow content</a>.)</p>
|
|
|
|
<p>The term <dfn id=shadow8 title="">shadow content</dfn> refers to the
|
|
various nodes in the shadow tree(s) of a bound element. Shadow content is
|
|
created by cloning <a href="#shadow6" title="shadow content
|
|
template">shadow content templates</a> during binding attachment.
|
|
|
|
<div class=example>
|
|
<p>For example, the HTML file upload control appears in most browsers as
|
|
a composite widget consisting of a text field and a button. A sample XBL
|
|
binding for the file widget might look as follows:</p>
|
|
|
|
<pre><binding id="fileupload">
|
|
<template>
|
|
<html:input type="text"/>
|
|
<html:input type="button"/>
|
|
</template>
|
|
</binding></pre>
|
|
|
|
<p>Because this content is not visible to its parent element, it is said
|
|
to be <em><a href="#shadow5">shadow content</a></em>.</p>
|
|
</div>
|
|
|
|
<p class=note>The file control is actually a special case. Due to security
|
|
considerations, untrusted bindings will typically not be able to extend
|
|
the file upload control in UAs intended for use with untrusted content.</p>
|
|
|
|
<p>Whenever bindings are attached to an element, shadow content will
|
|
potentially be <a href="#rules3" title="Rules for Shadow Content
|
|
Generation">generated</a>. Similarly, when a binding is removed from an
|
|
element, its shadow content, if any, is <a href="#rules4" title="Rules
|
|
for Shadow Content Destruction">destroyed</a>.</p>
|
|
|
|
<p>A shadow tree must be generated if a <code><a
|
|
href="#template0">template</a></code> element is added to a <code><a
|
|
href="#binding16">binding</a></code> element that had no <code><a
|
|
href="#template0">template</a></code> element. If the <code><a
|
|
href="#template0">template</a></code> element is removed, then the shadow
|
|
tree must be destroyed.</p>
|
|
|
|
<p>The <code><a href="#template0">template</a></code> element used to
|
|
generate a binding is always the first such element in a <code><a
|
|
href="#binding16">binding</a></code> element. If the <code><a
|
|
href="#binding16">binding</a></code> element is mutated in a way which
|
|
changes which <code><a href="#template0">template</a></code> element is
|
|
the first, then the corresponding shadow tree must be <a
|
|
href="#regenerating">regenerated</a>.</p>
|
|
|
|
<p>Similarly, when a <code><a href="#template0">template</a></code>
|
|
element or any of its descendants is mutated in any way, any bindings
|
|
whose shadow tree was constructed from that element must be <a
|
|
href="#regenerating">regenerated</a>.</p>
|
|
|
|
<p><dfn id=regenerating title=regenerated>Regenerating a shadow tree</dfn>
|
|
consists of first <a href="#rules4" title="Rules for Shadow Content
|
|
Destruction">destroying</a> the existing shadow tree and then <a
|
|
href="#rules3" title="Rules for Shadow Content Generation">generating</a>
|
|
a new one.</p>
|
|
|
|
<h3 id=rules><span class=secno>4.1. </span><dfn id=rules3>Rules for Shadow
|
|
Content Generation</dfn></h3>
|
|
|
|
<p>When a shadow tree is generated, user agents must act as follows:</p>
|
|
|
|
<p>If the binding element has no <code><a
|
|
href="#template0">template</a></code> element, then no shadow content
|
|
will be generated for this binding.</p>
|
|
|
|
<p>Otherwise, its first <code><a href="#template0">template</a></code>
|
|
element must be deeply cloned.</p>
|
|
|
|
<p>The <code>xml:base</code> data of the cloned <code><a
|
|
href="#template0">template</a></code> element must be set so that the
|
|
<code>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 their binding
|
|
documents' <code>Document</code> node(s).</p>
|
|
|
|
<p>No mutation events must be fired during the above steps.</p>
|
|
|
|
<p>Any bindings that apply to elements in the shadow tree must be applied.</p>
|
|
|
|
<p>For bindings with ECMAScript implementations: the <code><a
|
|
href="#shadowtree">shadowTree</a></code> member of the <a
|
|
href="#internal">internal object</a> must be set to be a reference to the
|
|
<code><a href="#template0">template</a></code> element clone (the root of
|
|
the shadow tree).</p>
|
|
|
|
<p>The shadow tree is then <dfn id=applied>applied</dfn> to the bound
|
|
element: the binding's shadow tree is placed in the appropriate place in
|
|
the final flattened tree, <a href="#explicit3">explicit children</a> are
|
|
(re)distributed to the appropriate <code><a
|
|
href="#content0">content</a></code> elements, and the CSS cascade and
|
|
inheritance is be computed along the new tree. (See: <a
|
|
href="#processing2">processing <code title="">content</code>
|
|
elements</a>.)</p>
|
|
|
|
<p>After this point, further bindings may need to be applied, or certain
|
|
bindings may need to be removed (because of CSS inheritance or because
|
|
the selectors that decide which elements match which bindings can be
|
|
affected by the shadow tree being associated with the bound element).</p>
|
|
|
|
<p>Everything described in this section must be completed atomically
|
|
— that is, the UA must not execute author scripts during this
|
|
process.</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=rules0><span class=secno>4.2. </span><dfn id=rules4>Rules for
|
|
Shadow Content Destruction</dfn></h3>
|
|
|
|
<p>The destruction of a shadow tree consists of recreating the <a
|
|
href="#final0">final flattened tree</a> without the influence of that
|
|
binding's shadow tree by redistributing the <a href="#explicit3">explicit
|
|
children</a> to the remaining shadow trees' <code><a
|
|
href="#content0">content</a></code> elements (or, if there are none,
|
|
putting the nodes back directly under the bound element).</p>
|
|
|
|
<p>For bindings with ECMAScript implementations: the <code><a
|
|
href="#shadowtree">shadowTree</a></code> member of the <a
|
|
href="#internal">internal object</a> must be set to null.</p>
|
|
|
|
<h3 id=attribute><span class=secno>4.3. </span><dfn
|
|
id=attribute1>Attribute Forwarding</dfn></h3>
|
|
|
|
<p>Attributes on shadow content elements can be tied to attributes on the
|
|
bound element; then, whenever the attribute is set or removed on the
|
|
bound element, the corresponding attribute on the shadow content is also
|
|
set or removed. On any shadow content element, an <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute can be
|
|
used to specify a <a href="#attributes22">space-separated</a> list of
|
|
attributes that should be inherited. Attributes with namespaces can be
|
|
defined using a namespace prefix and the attribute name separate by a
|
|
colon.</p>
|
|
|
|
<div class=example>
|
|
<p>For example, returning to the HTML file upload control example above,
|
|
the shadow text field can be set up to automatically inherit the
|
|
<code>value</code> attribute from the bound element.</p>
|
|
|
|
<pre><xbl:binding id="fileUploadControl">
|
|
<xbl:template>
|
|
<html:input type="text" xbl:attr="value"/>
|
|
<html:input type="button" value="Browse..."/>
|
|
</xbl:template>
|
|
</xbl:binding></pre>
|
|
</div>
|
|
|
|
<p>Each entry in the <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> list can either simply list an
|
|
attribute (a <a href="#qname">QName</a>, such as <code>value</code> in
|
|
the example above), or it can specify an <code>=</code>-separated pair of
|
|
<a href="#qname" title=QName>QNames</a> consisting of the attribute on
|
|
the shadow content that should be tied to the attribute on the bound
|
|
element. When two names are specified, the attribute to be added on the
|
|
shadow content node is listed first, and the attribute of the bound
|
|
element is second.</p>
|
|
|
|
<p>Each entry may also be suffixed by a single hash mark (#) followed by a
|
|
<a href="#type-">type designation</a>.</p>
|
|
|
|
<p>The <code title=attr-attr><a href="#xblattr0">xbl:attr</a></code>
|
|
attribute's value must be parsed as follows. First, it must be split on
|
|
spaces (treated as a <a href="#attributes22">space-separated</a> value).
|
|
Next, each resulting item must be matched against the following pattern
|
|
(given here in pseudo-BNF, where square brackets indicate optional
|
|
terms):</p>
|
|
|
|
<pre>xbl inherits item := [<var>s1</var> ':'] <var>s2</var> ['=' [<var>s3</var> ':'] <var>s4</var>] ['#' <var>s5</var>]</pre>
|
|
|
|
<p>...where <var>s1</var>..<var>s5</var> are strings of characters not
|
|
containing any of ":". "=", or "#".</p>
|
|
|
|
<p>If any item does not match this pattern, then the item is <a
|
|
href="#in-error">in error</a> and must be ignored. Other items in the
|
|
list, if any, are not affected by this.</p>
|
|
|
|
<p>The values <var>s1</var>:<var>s2</var> and <var>s3</var>:<var>s4</var>
|
|
(if present) must be resolved to fully qualified names using the
|
|
attribute <a href="#qname">QName</a> resolving semantics and the
|
|
namespaces prefix declarations in scope on the element on which the <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute is
|
|
found, at the time that the attribute is parsed. Any value in the list
|
|
that does not resolve to a fully qualified name is <a href="#in-error">in
|
|
error</a> and must be ignored. <a href="#refsXMLNS">[XMLNS]</a></p>
|
|
|
|
<p>Changes to namespace prefix definitions in the shadow tree that affect
|
|
<a href="#qname" title=QName>QNames</a> used in <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> attributes take effect the next time
|
|
the attribute is parsed (which must be the next time the attribute is
|
|
changed, but may be earlier).</p>
|
|
|
|
<h4 id=forwarding><span class=secno>4.3.1. </span>Forwarding to and from
|
|
text nodes</h4>
|
|
|
|
<p>The special value <dfn id=xbltext><code>xbl:text</code></dfn> can be
|
|
used in an <code title="">=</code>-separated pair, where the prefix is
|
|
associated with the XBL namespace. (The value is not a literal; it
|
|
represents the fictional "text" attribute in the XBL namespace.)</p>
|
|
|
|
<p>When specified on the left-hand side of the pair it indicates that the
|
|
value of the attribute on the right-hand side are to be represented as
|
|
text nodes underneath the shadow element in the <a href="#final0">final
|
|
flattened tree</a>. If the element has any child nodes in the DOM (any
|
|
nodes, including comment nodes, whitespace text nodes, or even empty
|
|
CDATA nodes) then the pair is <a href="#in-error">in error</a> and UAs
|
|
must ignore it, meaning the attribute value is not forwarded. Otherwise,
|
|
a text node must be created, and that text node will be placed under the
|
|
element in the final flattened tree.</p>
|
|
|
|
<p>Text nodes created in this way are orphans; their
|
|
<code>parentNode</code>, <code>nextSibling</code>,
|
|
<code>previousSibling</code>, <code>childNodes</code>,
|
|
<code>firstChild</code>, and <code>lastChild</code> attributes are all
|
|
null or empty. Their <code>ownerDocument</code> attribute is set to the
|
|
same as the shadow content node that generated them. (The only way one of
|
|
these text nodes can be accessed is if the element is itself bound: the
|
|
text node might then appear in a <code><a
|
|
href="#content0">content</a></code> element's <code><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list.)</p>
|
|
|
|
<p>When used on the right-hand side, it indicates that any text nodes
|
|
(including CDATA nodes and whitespace text nodes) that are <a
|
|
href="#explicit3">explicit children</a> of the bound element must have
|
|
their data concatenated and the resulting value stored as the attribute
|
|
on the left-hand side.</p>
|
|
<!--XXX use textContent instead? innerText?
|
|
The HTML5 special version? -->
|
|
|
|
<p>The <code><a href="#xbltext">xbl:text</a></code> value cannot occur by
|
|
itself in the list. If it occurs by itself, it is <a href="#in-error">in
|
|
error</a> and UAs must <a href="#ignoring">ignore</a> that value in the
|
|
<a href="#attributes22">space-separated</a> list that is the <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute.</p>
|
|
|
|
<h4 id=forwarding0><span class=secno>4.3.2. </span>Forwarding language
|
|
metadata</h4>
|
|
|
|
<p>The special value <dfn id=xbllang><code>xbl:lang</code></dfn> can also
|
|
be used in an <code title="">=</code>-separated pair. (Again, this is
|
|
just the fictional "lang" attribute in the XBL namespace, not the literal
|
|
string "xbl:lang", so the "xbl" prefix, or whatever prefix is used, must
|
|
be declared as the XBL namespace.)</p>
|
|
|
|
<p>When used on the right-hand side, it indicates that the value to be
|
|
copied is the natural language of the bound element, typically given by
|
|
the attribute <code>xml:lang</code> of that element or an ancestor, or by
|
|
HTTP headers, or similar. If no language is defined, then the value to be
|
|
copied must be the empty string.</p>
|
|
|
|
<p>The <code><a href="#xbllang">xbl:lang</a></code> value cannot occur by
|
|
itself or on the left-hand side. If it does, it is <a href="#in-error">in
|
|
error</a> and UAs must <a href="#ignoring">ignore</a> that value in the
|
|
element's <code title=attr-attr><a href="#xblattr0">xbl:attr</a></code>
|
|
attribute.</p>
|
|
|
|
<h4 id=error0><span class=secno>4.3.3. </span>Error handling</h4>
|
|
|
|
<p>Any other values in the XBL namespace in the list are <a
|
|
href="#in-error">in error</a> and must be <a href="#ignoring"
|
|
title=ignore>ignored</a>. (In particular, trying to change or set the
|
|
value of <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> or, worse, <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code>, must not result
|
|
in any changes to any attributes.)</p>
|
|
|
|
<p>If an attribute is listed multiple times on the left hand side (or on
|
|
its own), then the last designation wins (as if the attributes were each
|
|
forwarded in turn, an earlier forwarding being overwritten by a later
|
|
one).</p>
|
|
|
|
<h4 id=type-specifiers><span class=secno>4.3.4. </span>Type specifiers</h4>
|
|
|
|
<p>If the attribute or attribute pair is followed by a <dfn id=type->type
|
|
designation</dfn>, in the form of a hash mark character ("#") and by a
|
|
type name, then the value must be processed as described for its type
|
|
below before being forwarded.</p>
|
|
|
|
<dl>
|
|
<dt>If the type is <dfn id=url title=type-url><code>url</code></dfn>
|
|
|
|
<dd>The value must be resolved to an absolute URI using the base URI of
|
|
the source element before being forwarded.
|
|
|
|
<dt>If the type is <dfn id=text0 title=type-text><code>text</code></dfn>
|
|
(default)
|
|
|
|
<dd>The value is forwarded unchanged.
|
|
|
|
<dt>If the type is any other value
|
|
|
|
<dd>The attribute must not be forwarded. The value is <a
|
|
href="#in-error">in error</a> and UAs must <a
|
|
href="#ignoring">ignore</a> that value in the element's <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute.
|
|
</dl>
|
|
|
|
<div class=example>
|
|
<p>In the following shadow template, the "src" attribute on the bound
|
|
element is forwarded to the "src" attribute on the <code>image</code>
|
|
element in the shadow tree, and the link will work even if the original
|
|
attribute had a relative URI and the base URIs of the various nodes are
|
|
different:</p>
|
|
|
|
<pre>
|
|
<xbl:template>
|
|
<xul:image xbl:attr="src#url title alt=xbl:text xml:lang=xbl:lang"/>
|
|
</xbl:template>
|
|
</pre>
|
|
|
|
<p>This example also shows how to turn the value of an attribute on the
|
|
bound element, in this case the "alt" attribute, into child nodes of the
|
|
element in the shadow tree, using <code><a
|
|
href="#xbltext">xbl:text</a></code>. For accessibility reasons, the
|
|
language of the element is also explicitly forwarded.</p>
|
|
</div>
|
|
<!-- XXX we need a way to translate x="foo" y="foo" to
|
|
transform="translate(x,y)" and similar -->
|
|
<!-- XXX we need a way to handle onfoo attributes on the bound
|
|
element -->
|
|
|
|
<h4 id=dynamic><span class=secno>4.3.5. </span>Dynamic changes</h4>
|
|
|
|
<p>The <code title=attr-attr><a href="#xblattr0">xbl:attr</a></code>
|
|
attribute must be parsed when the binding is first applied and whenever
|
|
the attribute's value changes. It must be applied (causing the relevant
|
|
attributes and text nodes to be updated) when the shadow tree is
|
|
generated, when the attribute is changed, and whenever any of the bound
|
|
element's attributes or text nodes referred to by the <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute change.</p>
|
|
|
|
<h4 id=how-attribute><span class=secno>4.3.6. </span>How Attribute
|
|
Forwarding Affects the Shadow Tree</h4>
|
|
|
|
<p>The element to which the attributes are forwarded (that is, the element
|
|
with the <code title=attr-attr><a href="#xblattr0">xbl:attr</a></code>
|
|
attribute specified) has its attributes mutated. Whenever attribute
|
|
forwarding happens: existing attributes to which values are being
|
|
forwarded must have their values changed, attributes that are being
|
|
forwarded that do not yet exist on the shadow tree element must be added
|
|
to the shadow tree element, attributes to which values would be forwarded
|
|
but whose source attributes are not present on the bound element must be
|
|
removed from the shadow tree element.</p>
|
|
|
|
<p>The shadow tree element's attributes can be changed dynamically, and
|
|
this doesn't affect the attribute forwarding, until dynamic changes cause
|
|
attribute forwarding to be performed again. When attribute forwarding is
|
|
performed, all attributes are forwarded, even those that haven't changed
|
|
on the bound element, thus blowing away any dynamic changes to the shadow
|
|
tree element's attributes that are referenced by the <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute.</p>
|
|
|
|
<h3 id=processing0><span class=secno>4.4. </span><dfn
|
|
id=processing2>Processing <code>content</code> Elements</dfn></h3>
|
|
|
|
<p>A node is said to match a <code><a href="#content0">content</a></code>
|
|
element when the <code><a href="#content0">content</a></code> element has
|
|
no <code title=attr-content-includes><a
|
|
href="#includes">includes</a></code> attribute, or when the element in
|
|
question matches the selector given by that <code
|
|
title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute.</p>
|
|
|
|
<p>If an element stops matching a <code><a
|
|
href="#content0">content</a></code> element that it is assigned to, then
|
|
the bound element's explicit chlidren must be redistributed.</p>
|
|
|
|
<h4 id=how-nodes><span class=secno>4.4.1. </span>How Nodes are Distributed</h4>
|
|
|
|
<p><img alt="" class=extra src="images/xbl_image_1.gif">XBL bindings can
|
|
interleave shadow content between bound elements and their <a
|
|
href="#explicit3">explicit children</a>. 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>In addition, the shadow trees of inherited bindings get inserted into
|
|
the first <code><a href="#inherited0">inherited</a></code> element in the
|
|
binding.</p>
|
|
|
|
<p>The <dfn id=explicit3>explicit children</dfn> of an element are the
|
|
nodes that are listed in the element's <code>childNodes</code> array,
|
|
with the exception that any <code><a href="#content0">content</a></code>
|
|
elements in that array are instead replaced by whatever nodes they
|
|
currently have assigned to them, or, if no nodes are assigned to that
|
|
<code><a href="#content0">content</a></code> element, by the child nodes
|
|
of that <code><a href="#content0">content</a></code> element. If an
|
|
element's <code>childNodes</code> list is empty but the element has an
|
|
<code title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute
|
|
that uses the <code><a href="#xbltext">xbl:text</a></code> value on the
|
|
left hand side in a way that is not <a href="#in-error">in error</a> then
|
|
its "explicit children" is the text node generated during <a
|
|
href="#attribute1">attribute forwarding</a>.</p>
|
|
|
|
<div class=example>
|
|
<p>Consider the following simple document:</p>
|
|
|
|
<pre><X><A/></X></pre>
|
|
|
|
<p>Now, if the element X in that document is bound to a binding with the
|
|
following shadow tree template:</p>
|
|
|
|
<pre><template>
|
|
<my:T>
|
|
<my:P/>
|
|
<content/>
|
|
<my:Q/>
|
|
</my:T>
|
|
</template></pre>
|
|
|
|
<p>The explicit children of the <code>T</code> element, ignoring
|
|
whitespace nodes, are, in order, <code>P</code>, <code>A</code>, and
|
|
<code>Q</code>. This is because the children of <code>T</code> are
|
|
<code>P</code>, a <code><a href="#content0">content</a></code> element,
|
|
and <code>Q</code>, and the <code><a href="#content0">content</a></code>
|
|
element has just one node associated with it, namely the <code>A</code>
|
|
element.</p>
|
|
</div>
|
|
|
|
<p>When the <a href="#explicit3">explicit children</a> are distributed and
|
|
assigned to the <code><a href="#content0">content</a></code> elements in
|
|
the bound element's shadow trees, the <code
|
|
title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute determines which <code><a href="#content0">content</a></code>
|
|
element a given child is to be placed under.</p>
|
|
|
|
<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>If the <code title=attr-content-includes><a
|
|
href="#includes">includes</a></code> attribute is specified, it must be
|
|
interpreted as a <a href="#attributes21">selector</a>, and only elements
|
|
that <a href="#selectors1" title="selectors and shadow scopes">match the
|
|
selector</a> apply to that <code><a href="#content0">content</a></code>
|
|
element. If the selector is invalid, the <code><a
|
|
href="#content0">content</a></code> element is <a href="#in-error">in
|
|
error</a> and does not match any nodes. Matching of the elements to the
|
|
selector is done without taking into account the shadow tree in which the
|
|
<code><a href="#content0">content</a></code> element itself is found. <a
|
|
href="#refsSELECTORS">[SELECTORS]</a></p>
|
|
|
|
<p>Each node that is to be distributed (each <a href="#explicit3"
|
|
title="explicit children">explicit child node</a>) must be assigned to a
|
|
<code><a href="#content0">content</a></code> element as follows:</p>
|
|
|
|
<ol>
|
|
<li>If the node is already assigned to a <code><a
|
|
href="#content0">content</a></code> element for this binding, and the
|
|
<code><a href="#content0">content</a></code> element is <a
|
|
href="#locked" title=attr-content-locked>locked</a>, then that is the
|
|
<code><a href="#content0">content</a></code> element to which the node
|
|
must be assigned, stop here.
|
|
|
|
<li>Otherwise: if the node is already assigned to a <code><a
|
|
href="#content0">content</a></code> element for this binding, unassign
|
|
it.
|
|
|
|
<li>Let <var>T</var> be the shadow tree of the <span>most derived</span>
|
|
binding with a shadow tree for the bound element.
|
|
|
|
<li>If <var>T</var> contains a <a href="#correct">correct</a> <code><a
|
|
href="#content0">content</a></code> element that is not <a
|
|
href="#locked" title=attr-content-locked>locked</a> and to which the
|
|
node in question applies, then the first such element in a depth-first,
|
|
pre-order traversal of the shadow tree <var>T</var> is the <code><a
|
|
href="#content0">content</a></code> element to which the node must be
|
|
assigned, stop here.
|
|
|
|
<li>Otherwise, if this binding has no <a href="#correct">correct</a>
|
|
<code><a href="#inherited0">inherited</a></code> element in its shadow
|
|
tree, then the node is not assigned to a <code><a
|
|
href="#content0">content</a></code> element, and does not appear in the
|
|
<a href="#final0">final flattened tree</a>; stop here.
|
|
|
|
<li>Otherwise, if the binding has a <a href="#correct">correct</a>
|
|
<code><a href="#inherited0">inherited</a></code> element in its shadow
|
|
tree but it is the least derived binding with a shadow tree, then the
|
|
node is not assigned to a <code><a href="#content0">content</a></code>
|
|
element, and does not appear in the <a href="#final0">final flattened
|
|
tree</a>; stop here.
|
|
|
|
<li>Otherwise, let <var>T</var> be the shadow tree of the <a
|
|
href="#next-">next most derived</a> binding with a shadow tree and
|
|
return to step 4.
|
|
</ol>
|
|
|
|
<p>The <a href="#explicit3">explicit children</a> must be processed in
|
|
order, so if two nodes are assigned to a <code><a
|
|
href="#content0">content</a></code> element, their order in the <code><a
|
|
href="#xblchildnodes">xblChildNodes</a></code> list is the same as their
|
|
relative order in the <a href="#explicit3">explicit children</a> list.</p>
|
|
|
|
<div class=example>
|
|
<p>Consider the following simple document:</p>
|
|
|
|
<pre><X><A/><B/><C/></X></pre>
|
|
|
|
<p>Imagine that the element X in that document is bound to a binding with
|
|
the following shadow tree template:</p>
|
|
|
|
<pre><template>
|
|
<my:T>
|
|
<my:M/>
|
|
<content/>
|
|
<my:N/>
|
|
</my:T>
|
|
</template></pre>
|
|
|
|
<p>Imagine further that the element T is itself bound to a binding with
|
|
the following template:</p>
|
|
|
|
<pre><template>
|
|
<my:R>
|
|
<content includes="N"/>
|
|
<content includes="B"/>
|
|
</my:R>
|
|
</template></pre>
|
|
|
|
<p>The resulting <a href="#final0">final flattened tree</a> would be:</p>
|
|
|
|
<pre> X
|
|
|
|
|
`-- T
|
|
|
|
|
`-- R
|
|
|
|
|
+-- N
|
|
|
|
|
`-- B</pre>
|
|
|
|
<p>In this example, there are two selectors, "N" and "B", both of which
|
|
match just elements with the given local name.</p>
|
|
</div>
|
|
|
|
<h4 id=when-nodes><span class=secno>4.4.2. </span>When Nodes Are
|
|
Redistributed</h4>
|
|
|
|
<p>The algorithm described in the previous section is applied when:</p>
|
|
|
|
<ul>
|
|
<li><a href="#rules3" title="Rules for Shadow Content Generation">A
|
|
shadow tree is generated</a>.
|
|
|
|
<li><a href="#rules4" title="Rules for Shadow Content Destruction">A
|
|
shadow tree is destroyed and the bound element still has bindings with
|
|
shadow trees</a>.
|
|
|
|
<li><a href="#handling4" title="Handling DOM Changes">The bound element
|
|
has explicit children added, removed, or moved</a>.
|
|
|
|
<li><a href="#handling4" title="Handling DOM Changes">A shadow tree is
|
|
modified in a way that affects the relative order of
|
|
<code>content</code> elements or their <code
|
|
title=attr-content-includes>includes</code> attributes</a>.
|
|
|
|
<li><a href="#handling4" title="Handling DOM Changes">An <code
|
|
title=attr-content-includes>includes</code> attribute in the shadow tree
|
|
is mutated</a>.
|
|
|
|
<li><a href="#processing2" title="Processing content Elements">One or
|
|
more of the nodes assigned to a <code>content</code> element in a shadow
|
|
tree no longer match the element's <code
|
|
title=attr-content-includes>includes</code> attribute.</a></li>
|
|
<!-- XXXX the shadow tree is regenerated, e.g. template descendants
|
|
are modified -->
|
|
</ul>
|
|
|
|
<div class=example>
|
|
<p>Consider the following binding shadow tree:</p>
|
|
|
|
<pre><template>
|
|
<div>As: <content includes="A, AA"/></div>
|
|
<div>Other: <content/></div>
|
|
</template></pre>
|
|
|
|
<p>If an element is bound to this binding while it has three child
|
|
elements A, AA, and B, then the A and AA elements would end up under the
|
|
first <code><a href="#content0">content</a></code> element, and the B
|
|
element would end up under the second <code><a
|
|
href="#content0">content</a></code> element. But if the <code
|
|
title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute of the first <code><a href="#content0">content</a></code>
|
|
element in the shadow tree was then dynamically modified to just have
|
|
the value "<code title="">A</code>", then the AA element would be
|
|
reassigned to the second <code><a href="#content0">content</a></code>
|
|
element.</p>
|
|
</div>
|
|
|
|
<h3 id=the-final><span class=secno>4.5. </span>The <dfn id=final0>Final
|
|
Flattened Tree</dfn></h3>
|
|
|
|
<p>The final flattened tree is the view of the document and shadow trees
|
|
after XBL has been fully applied. It is only used for two things:</p>
|
|
|
|
<dl>
|
|
<dt>Rendering
|
|
|
|
<dd>Rendering must be performed using the final flattened tree. Nodes
|
|
that do not appear in the final flattened tree must not be rendered.
|
|
(See: <a href="#css-property1">CSS property inheritance and
|
|
rendering</a>.)
|
|
|
|
<dt>Event dispatch
|
|
|
|
<dd>Events flow along the final flattened tree. (See: <a
|
|
href="#event13">event flow and targeting across shadow scopes</a>.)
|
|
</dl>
|
|
|
|
<p>All other processing continues to use the DOM Core tree. (See: <a
|
|
href="#shadow10" title="Semantics of non-XBL elements in XBL
|
|
contexts">shadow content and other things</a>.)</p>
|
|
|
|
<p>The final flattened tree must be constructed by taking the bound
|
|
document's core DOM tree and performing the equivalent of the following
|
|
steps on each bound element, until there are no more bound elements in
|
|
the tree that have not been processed:</p>
|
|
|
|
<ol>
|
|
<li>If the bound element has no shadow trees, move on to the next bound
|
|
element.
|
|
|
|
<li>Otherwise, replace the child nodes of the bound element with the
|
|
child nodes of the most derived shadow tree's root <code><a
|
|
href="#template0">template</a></code> element.
|
|
|
|
<li>For any element in the shadow tree that has an <code
|
|
title=attr-attr><a href="#xblattr0">xbl:attr</a></code> attribute that
|
|
uses the <code><a href="#xbltext">xbl:text</a></code> value on the left
|
|
hand side in a way that is not <a href="#in-error">in error</a>, let the
|
|
element's only child node be the attribute-forwarding text node. (If the
|
|
element in question has any child nodes, then the <code><a
|
|
href="#xbltext">xbl:text</a></code> value will be <a href="#in-error">in
|
|
error</a>.)
|
|
|
|
<li>Replace any <code><a href="#content0">content</a></code> elements in
|
|
the shadow tree with the nodes that were assigned to them in the <a
|
|
href="#processing2" title="Processing content Elements">previous
|
|
section</a>, unless there are no such nodes, in which case replace them
|
|
with their child nodes.
|
|
|
|
<li>Replace the second and subsequent <code><a
|
|
href="#inherited0">inherited</a></code> elements in the shadow tree with
|
|
their child nodes.
|
|
|
|
<li>Replace the first <code><a href="#inherited0">inherited</a></code>
|
|
element in the shadow tree, if any, with the child nodes of the <a
|
|
href="#next-">next most derived</a> binding's shadow tree's root
|
|
<code><a href="#template0">template</a></code> element, or, if there is
|
|
no less-derived binding with a shadow tree, with the child nodes of the
|
|
<code><a href="#inherited0">inherited</a></code> element itself.
|
|
|
|
<li>If the previous step added a shadow tree to the flattened tree, then
|
|
return to step 3 to deal with that newly added shadow tree. Otherwise,
|
|
move on to the next bound element.
|
|
</ol>
|
|
|
|
<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/ns/xbl">
|
|
<xbl:binding 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:binding>
|
|
<xbl:binding element="Q">
|
|
<xbl:template>
|
|
<X>
|
|
<Y>
|
|
<xbl:content>
|
|
<Z1/>
|
|
</xbl:content>
|
|
<xbl:content>
|
|
<Z2/>
|
|
</xbl:content>
|
|
</Y>
|
|
</X>
|
|
</xbl:template>
|
|
</xbl:binding>
|
|
</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 the final flattened tree.
|
|
:</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>The shadow trees of B elements:</p>
|
|
|
|
<pre>
|
|
template
|
|
|
|
|
+-- P
|
|
|
|
|
+-- Q
|
|
| |
|
|
| +-- content
|
|
| |
|
|
| +-- R
|
|
|
|
|
+-- content
|
|
|
|
|
+-- S
|
|
</pre>
|
|
|
|
<p>The shadow trees of Q elements:</p>
|
|
|
|
<pre>
|
|
template
|
|
|
|
|
+-- X
|
|
|
|
|
+-- Y
|
|
|
|
|
+-- content
|
|
| |
|
|
| +-- Z1
|
|
|
|
|
+-- content
|
|
|
|
|
+-- Z2
|
|
</pre>
|
|
|
|
<p>The final flattened tree:</p>
|
|
|
|
<pre>
|
|
:
|
|
:.. A
|
|
:
|
|
:.. B
|
|
:
|
|
:.. P
|
|
:
|
|
:.. Q
|
|
: :
|
|
: :.. X
|
|
: :
|
|
: :.. Y
|
|
: :
|
|
: :.. C
|
|
: :
|
|
: :.. Z2
|
|
:
|
|
:.. D
|
|
</pre>
|
|
|
|
<p>The final flattened tree overlayed with the core DOM (the "*" and "#"
|
|
characters here identify which <code><a
|
|
href="#content0">content</a></code> elements the two explicit children
|
|
are assigned to):</p>
|
|
|
|
<pre id=pretty-diagram>
|
|
:|___
|
|
:....A template
|
|
:|___ |
|
|
:... B |
|
|
:| |
|
|
:|... P template
|
|
| :|____ |
|
|
| :|... Q |
|
|
| :| :| |
|
|
| :| :|.... X
|
|
| :| | :\_______
|
|
| :| | :....... Y __
|
|
| :| | : \
|
|
| :| +-- content* : |
|
|
| :| | : |
|
|
| :| +-- R : +-- content*
|
|
| :| : | |
|
|
+---:|--------- C* ......: | `-- Z1
|
|
| :| : |
|
|
| :| : `-- content
|
|
| :| : |___
|
|
| :| :............ Z2
|
|
| :`-- content#
|
|
| : |
|
|
| : `-- S
|
|
|___:____
|
|
:... D#
|
|
</pre>
|
|
</div>
|
|
|
|
<h4 id=terminology0><span class=secno>4.5.1. </span>Terminology</h4>
|
|
|
|
<p>Shadow content introduces the concept of <dfn id=shadow9>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>Shadow content nodes are in <dfn id=binding-level>binding-level shadow
|
|
scopes</dfn>. Binding scopes are determined by the bound element to which
|
|
the binding responsible for the generation of the shadow nodes is
|
|
attached. 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>
|
|
|
|
<h3 id=handling0><span class=secno>4.6. </span><dfn id=handling4>Handling
|
|
DOM Changes</dfn></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, and whenever its
|
|
attributes or pseudo-class states are changed, all the children of bound
|
|
elements 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 <a
|
|
href="#explicit3">explicit children</a> 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 <a href="#final0">final flattened tree</a>. Similarly, nodes that
|
|
previously did not appear in the final flattened tree may start matching
|
|
a <code><a href="#content0">content</a></code> element and thus be
|
|
inserted into the flattened tree.</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
|
|
<a href="#explicit3">explicit children</a> assigned to that element are
|
|
relocated to the first unlocked <code><a
|
|
href="#content0">content</a></code> elements that match them. If a
|
|
<code><a href="#content0">content</a></code> element's <code
|
|
title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute is changed, then the <a href="#explicit3">explicit children</a>
|
|
of the binding's bound element must be redistributed appropriately.</p>
|
|
|
|
<p><code><a href="#content0">content</a></code> elements may be
|
|
dynamically locked by manipulating their <code
|
|
title=attr-content-locked><a href="#locked">locked</a></code> attribute.
|
|
A locked <code><a href="#content0">content</a></code> element cannot
|
|
accept new children unless they are explicitly assigned to it using the
|
|
<code><a href="#setinsertionpoint">setInsertionPoint()</a></code> method.
|
|
However, children already under a locked <code><a
|
|
href="#content0">content</a></code> element remain there while the
|
|
element's <code title=attr-content-includes><a
|
|
href="#includes">includes</a></code> attribute (or lack thereof) matches
|
|
them.</p>
|
|
|
|
<p>Whenever the subtree of a <code><a
|
|
href="#template0">template</a></code> element in a binding document is
|
|
dynamically modified, any shadow trees that were constructed by cloning
|
|
that element must be <a href="#regenerating">regenerated</a>.</p>
|
|
<!-- XXX when does this happen,
|
|
exactly, relative to the mutations? -->
|
|
<h3 id=shadow0><span class=secno>4.7. </span>Shadow Content and CSS</h3>
|
|
|
|
<h4 id=selectors><span class=secno>4.7.1. </span><dfn
|
|
id=selectors1>Selectors and Shadow Scopes</dfn></h4>
|
|
|
|
<p>Bindings can interleave shadow elements between the bound element and
|
|
its <a href="#explicit3">explicit children</a>. (See: <a
|
|
href="#processing2">processing <code title="">content</code>
|
|
elements</a>.) 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 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 one or more XBL elements.</p>
|
|
|
|
<dl>
|
|
<dt>A>B
|
|
|
|
<dd>
|
|
<p>If "<code>B</code>" is in a shadow tree and
|
|
"<code>B.parentNode</code>" is a <code><a
|
|
href="#content0">content</a></code> element or an <code><a
|
|
href="#inherited0">inherited</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, but the
|
|
binding's "<code title=attr-template-allow-selectors-through><a
|
|
href="#allow-selectors-through">allow-selectors-through</a></code>" is
|
|
not <code>true</code>, the selector doesn't match "<code>B</code>".
|
|
Otherwise, if "<code>X</code>" is the root of a shadow tree and the
|
|
binding's "<code title=attr-template-allow-selectors-through><a
|
|
href="#allow-selectors-through">allow-selectors-through</a></code>" is
|
|
<code>true</code> and the binding is the bound element's most derived
|
|
binding with a shadow tree, then let "<code>X</code>" be the bound
|
|
element for which the shadow tree was generated. Otherwise, if
|
|
"<code>X</code>" is the root of a shadow tree and the binding's "<code
|
|
title=attr-template-allow-selectors-through><a
|
|
href="#allow-selectors-through">allow-selectors-through</a></code>" is
|
|
<code>true</code> but the binding is not the bound element's most
|
|
derived binding with a shadow tree, then let "<code>X</code>" be the
|
|
parent node of the <code><a href="#inherited0">inherited</a></code>
|
|
element into which the shadow tree was placed during the construction
|
|
of the <a href="#final0">final flattened tree</a>; if this is itself
|
|
the root of a shadow tree, then repeat the steps described in this
|
|
paragraph using that element as "<code>X</code>".</p>
|
|
|
|
<p>Then, the selector matches "<code>B</code>" if the "<code>X</code>"
|
|
element is the "<code>A</code>" element.</p>
|
|
|
|
<dt>A B
|
|
|
|
<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>".
|
|
|
|
<dt>A+B
|
|
|
|
<dd>If "<code>B</code>" is in a shadow tree and
|
|
"<code>B.previousSibling</code>" is a <code><a
|
|
href="#content0">content</a></code> element or an <code><a
|
|
href="#inherited0">inherited</a></code> element, the selector doesn't
|
|
match "<code>B</code>", otherwise, it matches if
|
|
"<code>B.previousSibling</code>" is "<code>A</code>".
|
|
|
|
<dt>A~B
|
|
|
|
<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>".
|
|
</dl>
|
|
|
|
<div class=example>
|
|
<p>The selector <code>p ~ p</code> never matches any elements in the
|
|
following example, even if the <code><a
|
|
href="#content0">content</a></code> element has a <code>p</code> element
|
|
assigned to it:</p>
|
|
|
|
<pre><template>
|
|
<html:p>...</html:p>
|
|
<content includes="p"><html:p>...</html:p></content>
|
|
<html:p>...</html:p>
|
|
</template>
|
|
</pre>
|
|
</div>
|
|
|
|
<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 point
|
|
given by the <code><a href="#content0">content</a></code> element
|
|
(whether that be 0, 1, 2, or more nodes).</p>
|
|
</div>
|
|
|
|
<h4 id=css-property><span class=secno>4.7.2. </span><dfn
|
|
id=css-property1>CSS Property Inheritance and Rendering</dfn></h4>
|
|
|
|
<p>The <a href="#final0">final flattened tree</a> determines how CSS
|
|
properties (e.g., fonts and colors) are inherited. Elements must inherit
|
|
from their parent node in the <a href="#final0">final flattened tree</a>,
|
|
regardless of what their DOM Core parent node is.</p>
|
|
|
|
<p>Similarly, the rendering is performed using the <a href="#final0">final
|
|
flattened tree</a>. Nodes that do not appear in the <a
|
|
href="#final0">final flattened tree</a> have no computed style (as if
|
|
they were orphan nodes) and are not rendered.</p>
|
|
|
|
<h4 id=the-bound-element><span class=secno>4.7.3. </span>The <code><a
|
|
href="#bound-element">:bound-element</a></code> Pseudo-Class</h4>
|
|
|
|
<p>The <dfn id=bound-element><code>:bound-element</code></dfn>
|
|
pseudo-class, when used from a binding, must match the bound element of
|
|
that binding. If the selector is used somewhere other than in a binding's
|
|
style sheet (i.e. with a <code><a href="#style2">style</a></code> element
|
|
in XBL) or in a <code><a href="#content0">content</a></code> element's
|
|
<code title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute, then it must match any bound element. <a
|
|
href="#refsSELECTORS">[SELECTORS]</a></p>
|
|
|
|
<div class=example>
|
|
<p>In the following example, the binding uses this pseudo-class to to
|
|
draw a border around each of the children of the bound element, but no
|
|
other elements:</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding>
|
|
<template><content allow-selectors-through="true"/></template>
|
|
<style>
|
|
:bound-element > * { border: solid; }
|
|
</style>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h4 id=matching><span class=secno>4.7.4. </span><dfn id=matching1>Matching
|
|
Pseudo-Elements</dfn></h4>
|
|
|
|
<p>Shadow nodes may be associated with various pre-defined <a
|
|
href="#pseudo-element" title=pseudo-element>pseudo-elements</a> of the
|
|
bound element. On any element in the shadow content template, an <code
|
|
title=attr-pseudo><a href="#xblpseudo0">xbl:pseudo</a></code> attribute
|
|
(in the XBL namespace) can be used to specify the name of the pseudo to
|
|
associate with that element.</p>
|
|
|
|
<div class=example>
|
|
<p>For example, once more returning to the HTML file upload control
|
|
example above, the shadow text field can be set up to be considered a
|
|
match for the selector <span>input[type=file]::value</span> as follows.</p>
|
|
|
|
<pre><xbl:binding id="fileUploadControl">
|
|
<xbl:template>
|
|
<html:input type="text" xbl:pseudo="value"/>
|
|
<html:input type="button" value="Browse..."/>
|
|
</xbl:template>
|
|
</xbl:binding></pre>
|
|
</div>
|
|
|
|
<p>The pseudo must be given without its leading double colon.</p>
|
|
|
|
<p>If the pseudo-element name is not recognized, it is <a
|
|
href="#in-error">in error</a> and the UA must <a
|
|
href="#ignoring">ignore</a> the attribute. User agents must not
|
|
automatically recognize any pseudo-element (as this will break
|
|
forwards-compatibility).</p>
|
|
|
|
<p>If an element has multiple nodes with the same pseudo-element, then
|
|
they all match the relevant selector. Matching of nodes based on their
|
|
pseudo-element is unaffected by the <code>apply-author-sheets</code>
|
|
attribute.</p>
|
|
|
|
<p id=pseudo-list>The allowed pseudo-elements are:</p>
|
|
|
|
<dl>
|
|
<dt>::value
|
|
|
|
<dd>Intended to represent the entire rectangular 'interactive area' (or
|
|
the nearest equivalent in non-visual environments) of a text-entry form
|
|
control, specifically excluding the caption.
|
|
|
|
<dt>::choices
|
|
|
|
<dd>Intended to represent the entire rectangular 'selection area' (or the
|
|
nearest equivalent in non-visual environments) of a list form control,
|
|
specifically excluding the caption.
|
|
|
|
<dt>::label
|
|
|
|
<dd>Intended to represent the non-interactive area (or the nearest
|
|
equivalent in non-visual environments) of control, typically the
|
|
caption.
|
|
|
|
<dt>::repeat-item
|
|
|
|
<dd>Within a repeating sequence, for example generated by the repeat
|
|
construct in XForms, <!-- or the template stuff in XUL --> each repeated
|
|
item could be labeled as matching a pseudo-element ::repeat-item.
|
|
|
|
<dt>::icon
|
|
|
|
<dd>Intended to represent the icon part of a control, for example the
|
|
picture in a toolbar button or the icon next to a menu item.</dd>
|
|
<!--
|
|
<dt>::XXX</dt>
|
|
|
|
<dd>Intended to represent a specific part (or the nearest equivalent
|
|
in non-visual environments) of a XXX control.</dd>
|
|
-->
|
|
<!-- XXX add more from css3-ui -->
|
|
</dl>
|
|
|
|
<p>These pseudo-element descriptions are purely advisory, and while
|
|
authors are encouraged to use them for their predefined roles, it is
|
|
valid to use them for other purposes.</p>
|
|
|
|
<div class=example>
|
|
<p>The following XBL is part of the definition of a button control.</p>
|
|
|
|
<pre> <xbl:binding id="imageButton">
|
|
<xbl:template>
|
|
<html:span xbl:pseudo="icon"/>
|
|
<html:span xbl:attr="xbl:text=title"/>
|
|
</xbl:template>
|
|
</xbl:binding></pre>
|
|
|
|
<p>This control could then be used like this:</p>
|
|
|
|
<pre><button title="Save" class="save-button"/></pre>
|
|
|
|
<p>...and styled like this:</p>
|
|
|
|
<pre> button { binding: url(buttons.xml#imageButton); }
|
|
button.save-button::icon {
|
|
content: url(icons/save.png);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>In property descriptions, the term "all elements" in the "Applies To:"
|
|
line includes these pseudo-elements, as they map directly to real
|
|
elements in the binding.</p>
|
|
|
|
<p>User agents are required to support the above pseudo-element
|
|
identifiers, in so far as they interact with XBL2. User agents may also
|
|
support these same pseudo-elements for other purposes, e.g. as described
|
|
in the CSS3 UI specification. <a href="#refsCSS3UI">[CSS3UI]</a></p>
|
|
|
|
<h3 id=shadow1><span class=secno>4.8. </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=shadow2><span class=secno>4.9. </span><dfn id=shadow10
|
|
title="Semantics of non-XBL elements in XBL contexts">Shadow Content and
|
|
Other Things</dfn></h3>
|
|
<!--XXX Things that need to be defined in future revisions include
|
|
<em>binding to</em> html:script, html:select, html:textarea, MathML
|
|
nodes, etc (are their semantics based on the shadow tree, the
|
|
<span>final flattened tree</span>, or the original tree), as well as
|
|
having elements inside the shadow tree such as html:script,
|
|
html:style, html:map, form controls (are they part of the outer
|
|
form), html:form (does it wrap elements that are assigned to
|
|
<code>content</code> elements?), etc. -->
|
|
|
|
<p>Since the processing rules of all non-XBL elements found while
|
|
processing a binding document are not affected by their being part of an
|
|
XBL subtree, there are certain elements that are unlikely to have the
|
|
desired effect when included in shadow content templates. Some of these
|
|
cases are described below.</p>
|
|
|
|
<p class=note>While some of these effects may seem peculiar, it must be
|
|
emphasized that they are merely the result of XBL not affecting the
|
|
semantics of these elements at all. It would have been possible to define
|
|
XBL in such a way that the semantics of various elements from the XHTML,
|
|
XML Events, etc, namespaces were modified, but this would have required
|
|
XBL knowing about special elements from a large number of namespaces,
|
|
causing XBL implementations to have large interdependencies.</p>
|
|
|
|
<h4 id=general><span class=secno>4.9.1. </span>General Rules</h4>
|
|
|
|
<p>Shadow content is not considered part of a document, so elements that
|
|
are defined to trigger when they are "inserted into the document" do not
|
|
trigger during binding attachment.</p>
|
|
|
|
<p>IDs used in shadow content, as seen on XML Events nodes, in XHTML on
|
|
the <code>html:label</code> element's <code>for</code> attribute, and in
|
|
many other places, must be resolved in the context of the <a
|
|
href="#shadow9">shadow scope</a> and (failing that) the binding document,
|
|
not the scope of the document into which the shadow content is inserted.</p>
|
|
|
|
<div class=example>
|
|
<p>If a shadow template has an <code>html:img</code> element that has its
|
|
<code>usemap</code> attribute set:</p>
|
|
|
|
<pre><template ...>
|
|
<html:img src="..." usemap="#test" alt="..."/>
|
|
</template></pre>
|
|
|
|
<p>If the binding is applied to an element in a document containing an
|
|
<code>html:map</code> element with ID "test", that image map will not be
|
|
associated with this image. If the binding document itself contains an
|
|
<code>html:map</code> element with ID "test", however, that
|
|
<em>would</em> be associated with the element (even if it was, say, in
|
|
another binding's template).</p>
|
|
|
|
<p>If the template looked like this:
|
|
|
|
<pre><template ...>
|
|
<html:img src="..." usemap="#test" alt="..."/>
|
|
<html:map id="test"> ... </html:map>
|
|
</template></pre>
|
|
|
|
<p>...then the <code>html:img</code> element would always be attached to
|
|
that <code>html:map</code> element, regardless of the existence of other
|
|
<code>html:map</code> elements in the binding document.</p>
|
|
</div>
|
|
|
|
<p>When an element's processing model is defined in terms of the element's
|
|
child nodes or descendants, shadow trees do not affect the processing
|
|
model (unless this is called out explicitly below). For instance, an HTML
|
|
<code>title</code> element's behavior in determining the document title
|
|
is unaffected by XBL, even if the <code>title</code> element is bound or
|
|
has bound elements in its descendants.</p>
|
|
|
|
<p>When the nodes are cloned, their <code>xml:base</code> data remains as
|
|
it was in the bindings document (see <span>rules for content
|
|
generation</span>). Therefore URIs consisting of just fragment
|
|
identifiers (such as those in <code>url()</code> notation in <code
|
|
title="">style</code> attributes of, e.g., XHTML nodes) refer to
|
|
resources in the bindings document, not content in the bound document or
|
|
the shadow tree.</p>
|
|
|
|
<p class=note>This would cause trouble with <a
|
|
href="#attribute1">attribute forwarding</a>, so the attribute forwarding
|
|
syntax allows attributes to be marked as being <a href="#url"
|
|
title=type-url>of type "url"</a>.</p>
|
|
|
|
<h4 id=style><span class=secno>4.9.2. </span><dfn id=style3>Style
|
|
Blocks</dfn></h4>
|
|
|
|
<p>The semantics of <code>html:style</code> elements is that they
|
|
introduce new styles for their document. Since the document, in the case
|
|
of anything in an XBL subtree, is the bindings document (or the <a
|
|
href="#non-xbl">non-XBL document</a> in which the XBL subtree is found),
|
|
<em>that</em> is the document that must be affected by such a style
|
|
sheet.</p>
|
|
|
|
<p>Since the style sheets of such resource documents generally have no
|
|
effect, placing <code>html:style</code> blocks in XBL binding documents
|
|
is usually redundant. Such an element placed in a shadow content template
|
|
does not affect the documents into which the shadow content is later
|
|
inserted during binding attachment.</p>
|
|
|
|
<h4 id=script><span class=secno>4.9.3. </span><dfn id=script3>Script
|
|
Blocks</dfn></h4>
|
|
|
|
<p>Script elements, such as <code>html:script</code> and its ilk, are
|
|
typically evaluated only during parsing, or during parsing and when
|
|
inserted into a document. In all cases, however, they are evaluated in
|
|
the context of their owner document. Therefore such elements must only be
|
|
evaluated during initial parsing, in the context of the XBL subtree's
|
|
document, and not during binding attachment.</p>
|
|
|
|
<h4 id=event><span class=secno>4.9.4. </span><dfn id=event10>Event Handler
|
|
Blocks</dfn></h4>
|
|
|
|
<p>XML Events elements in the binding document must result in event
|
|
handlers being registered as event listeners on the nodes in the original
|
|
bindings document (including possibly the <code title=template><a
|
|
href="#template0">template</a></code> node) as described in XML Events.
|
|
They may be included in shadow content templates, but when the shadow
|
|
content template is cloned, the newly cloned event handlers must cause
|
|
new event listeners to be added to their new DOM Core parent nodes. Thus
|
|
an event handler that is the child of an <code><a
|
|
href="#template0">template</a></code> element in the shadow content
|
|
template will never fire once it has been cloned, since the events <a
|
|
href="#event13" title="Event Flow and Targeting Across Shadow Scopes">do
|
|
not bubble into the <code>template</code> elements</a>. <a
|
|
href="#refsXMLEVENTS">[XMLEVENTS]</a></p>
|
|
|
|
<p>Event handler blocks that are children of <code><a
|
|
href="#handlers0">handlers</a></code> elements (in particular XML Events
|
|
handler blocks) cause event listeners to be fired when <a
|
|
href="#event12">event forwarding</a> happens, just like with XBL <code><a
|
|
href="#handler0">handler</a></code> elements.</p>
|
|
|
|
<h4 id=html-forms><span class=secno>4.9.5. </span>HTML Forms</h4>
|
|
|
|
<p>Forms and form controls in shadow trees don't interact with form
|
|
controls and <code>form</code> elements in the bound document. Each
|
|
document and shadow tree creates a new scope for forms and form controls.</p>
|
|
|
|
<div class=example>
|
|
<p>Here's an extract from an HTML document with a form:</p>
|
|
|
|
<pre>...
|
|
<form action="register" method="post">
|
|
<h2>Customer Registration</h2>
|
|
<p>Please enter your details.</p>
|
|
<fieldset>
|
|
<legend>Contact Information</legend>
|
|
<p>Name: <input name="name" title="Enter your full name (first name first)."></p>
|
|
<p>Job Title: <input name="title" title="Enter your job title, e.g. 'Software Engineer'."></p>
|
|
<p>E-mail: <input name="email" title="Enter your e-mail address, in the form 'user@example.com'."></p>
|
|
</fieldset>
|
|
<fieldset>
|
|
<legend>Company Information</legend>
|
|
<p>Name: <input name="company" title="Enter the name of your employer."></p>
|
|
<p>Address: <textarea name="address" title="Enter the full street address of your employer, including postal code."></p>
|
|
</fieldset>
|
|
<fieldset>
|
|
<legend>Additional Information</legend>
|
|
<p>Birthday: <input name="dob" title="Enter your birthdate in the form YYYY-MM-DD, e.g. 1975-03-29."></p>
|
|
<p>Favorite animal: <input name="animal" title="Enter the word 'Cat'."></p>
|
|
</fieldset>
|
|
<fieldset>
|
|
<legend>Submission</legend>
|
|
<p><button title="Only submit the form when you are sure it is complete.">Submit</button></p>
|
|
</fieldset>
|
|
</form>
|
|
...</pre>
|
|
|
|
<p>The first binding, shown below as an extract from an XBL document,
|
|
could be attached to the <code>form</code> above, through CSS, to
|
|
provide a help box that shows the help text associated with the
|
|
currently focused control:</p>
|
|
|
|
<pre>...
|
|
<binding id="form-with-help">
|
|
<template>
|
|
<div>
|
|
<div class="header">Form:</div>
|
|
<div class="form"><content/></div>
|
|
</div>
|
|
<div>
|
|
<div class="header">Help:</div>
|
|
<div id="help"/>
|
|
</div>
|
|
</template>
|
|
<resources>
|
|
<style>
|
|
.header { font-size: larger; }
|
|
.form { height: 15em; overflow: scroll; }
|
|
</style>
|
|
</resources>
|
|
<handlers>
|
|
<handler event="focus">
|
|
this.shadowTree.getElementById('help').textContent = event.target.getAttribute('title');
|
|
</handler>
|
|
</handlers>
|
|
</binding>
|
|
...</pre>
|
|
|
|
<p>The help could be positioned more usefully by a slightly more advanced
|
|
binding that positioned the <code><a href="#div0">div</a></code> when
|
|
setting the help.</p>
|
|
|
|
<p>The last binding isn't particularly interesting. However, the
|
|
important thing to note is that if it was extended to include form
|
|
controls of its own, as in the following example, the form controls in
|
|
the binding would not interact with the form in the markup:</p>
|
|
|
|
<pre>...
|
|
<binding id="form-with-help">
|
|
<template>
|
|
<div class="header">
|
|
<div class="title"><content includes=":bound-element > h2:first-of-type"/></div>
|
|
<div class="tagline"><content includes=":bound-element > h2:first-of-type ~ p:first-of-type"/></div>
|
|
</div>
|
|
<div>
|
|
<div class="panel"><content locked="true" id="current"/></div>
|
|
</div>
|
|
<div>
|
|
<div class="buttons">
|
|
<button id="back">Back</button>
|
|
<button id="next">Next</button>
|
|
</div>
|
|
</div>
|
|
<div class="hidden"><content includes=":bound-element > fieldset" id="not-current"/></div>
|
|
</template>
|
|
<implementation>
|
|
({
|
|
set current(fieldset) {
|
|
if (this._current)
|
|
this.shadowTree.getElementById('not-current').setInsertionPoint(this._current);
|
|
this._current = fieldset;
|
|
if (this._current)
|
|
this.shadowTree.getElementById('current').setInsertionPoint(this._current);
|
|
},
|
|
back: function() {
|
|
if (!this._current) return;
|
|
var notCurrent = this.shadowTree.getElementById('not-current');
|
|
notCurrent.setInsertionPoint(this._current);
|
|
var last = this._current;
|
|
var index = 0;
|
|
while (index &lt; notCurrent.xblChildNodes.length &&
|
|
notCurrent.xblChildNodes[index] != this._current)
|
|
last = notCurrent.xblChildNodes[index++];
|
|
this._current = last;
|
|
this.shadowTree.getElementById('current').setInsertionPoint(this._current);
|
|
}
|
|
next: function() {
|
|
if (!this._current) return;
|
|
var notCurrent = this.shadowTree.getElementById('not-current');
|
|
notCurrent.setInsertionPoint(this._current);
|
|
var last = this._current;
|
|
var index = notCurrent.xblChildNodes.length-1;
|
|
while (index > 0 && notCurrent.xblChildNodes[index] != this._current)
|
|
last = notCurrent.xblChildNodes[index++];
|
|
this._current = last;
|
|
this.shadowTree.getElementById('current').setInsertionPoint(this._current);
|
|
}
|
|
get current() {
|
|
return this._current;
|
|
},
|
|
xblBindingAttached: function() {
|
|
this.current = this.getElementById('not-current').xblChildNodes[0];
|
|
this.shadowTree.getElementById('back').addEventListener('click', this.back, false);
|
|
this.shadowTree.getElementById('next').addEventListener('click', this.next, false);
|
|
},
|
|
})
|
|
</implementation>
|
|
<resources>
|
|
<style> ... </style>
|
|
</resources>
|
|
</binding>
|
|
...</pre>
|
|
|
|
<p>Again, the binding could be made cleaner, e.g. by disabling the "back"
|
|
button when on the first page, and by hiding the last fieldset and
|
|
instead having a "finish" button, but these improvements are left as
|
|
exercises for the reader.</p>
|
|
</div>
|
|
|
|
<h4 id=svg><span class=secno>4.9.6. </span>SVG</h4>
|
|
|
|
<p><em>Painting:</em> When painting groups, for child elements that have
|
|
shadow trees, instead of painting the child element itself, the group
|
|
must paint the child nodes of the element's shadow tree's root <code><a
|
|
href="#template0">template</a></code> element.</p>
|
|
|
|
<p><em>Text:</em> When rendering text, for descendant elements that have
|
|
shadow trees, instead of using the element or its children directly, the
|
|
user agent must use the child nodes of the element's shadow tree's root
|
|
<code><a href="#template0">template</a></code> element. (All other
|
|
processing, e.g. handling of combining characters, must then be done as
|
|
defined for SVG.)</p>
|
|
|
|
<p><em>ID references and URIs:</em> When a URI identifies an element with
|
|
a shadow tree, the SVG processor must use the first element node in the
|
|
element's shadow tree's root <code><a
|
|
href="#template0">template</a></code> element's <code>childNodes</code>
|
|
list instead of the element itself. If there are no elements, then the
|
|
SVG document is in error. The SVG specification defines how to handle
|
|
documents that are in error.</p>
|
|
<!-- NOT links to "in error", since this is
|
|
SVG-in-error, not XBL-in-error. -->
|
|
|
|
<p>When a URI reference with a fragment identifier in a shadow tree
|
|
references the binding document, then, if an elemnt in the shadow tree is
|
|
identified by the fragment identifier, that is the element that must be
|
|
used; otherwise, the fragment identifier must be matched against the
|
|
actual binding document instead.</p>
|
|
|
|
<p><em>Animation elements:</em> When an animation element would be
|
|
implicitly associated with its parent element (e.g. when it has no <code
|
|
title="">xlink:href</code> attribute), but that parent element is a
|
|
<code><a href="#template0">template</a></code> element that is the root
|
|
of a shadow tree, then the animation element must instead be associated
|
|
with the element found using the following algorithm:</p>
|
|
|
|
<ol>
|
|
<li>Let <var title="">element</var> be the animation element.
|
|
|
|
<li>If <var title="">element</var> has no parent element, then the
|
|
animation element is not associated with any element. Stop these steps.
|
|
|
|
<li>Let <var title="">parent</var> be the parent element of <var
|
|
title="">element</var>.
|
|
|
|
<li>If <var title="">parent</var> is a <code><a
|
|
href="#template0">template</a></code> element that is the root of a
|
|
shadow tree, then let <var title="">element</var> be the bound element
|
|
for that shadow tree, and return to the second step.
|
|
|
|
<li>Otherwise, <var title="">parent</var> is the element to which the
|
|
animation element is assigned.
|
|
</ol>
|
|
|
|
<p>Animation elements must be processed even when in shadow trees.</p>
|
|
|
|
<div class=example>
|
|
<p>In the following example, the UA would render the string "Hello Cruel
|
|
World", while animating the colour of the entire string over six
|
|
seconds.</p>
|
|
|
|
<pre><svg xmlns="http://www.w3.org/2000/svg">
|
|
<defs>
|
|
<b:xbl xmlns:b="http://www.w3.org/ns/xbl">
|
|
<b:binding <a href="#element" title=attr-binding-element>element="|world"</a>>
|
|
<b:template>
|
|
<tspan <a href="#xblattr0" title=attr-attr>b:attr</a>="<a href="#xbltext" title=xbl:text>b:text=data</a>"/> World
|
|
<animateColor attributeName="fill" from="rgb(0,0,255)" to="rgb(128,0,0)" begin="0s" dur="6s" fill="freeze" />
|
|
</b:template>
|
|
</b:binding>
|
|
</b:xbl>
|
|
</defs>
|
|
<text y="50" font-size="12">
|
|
Hello <world xmlns="" data="Cruel"/>
|
|
</text>
|
|
</svg></pre>
|
|
</div>
|
|
|
|
<h3 id=binding3><span class=secno>4.10. </span><dfn id=binding22>Binding
|
|
Style Sheets</dfn></h3>
|
|
|
|
<p>Shadow content nodes and bound elements are styled using style sheets
|
|
from a number of sources, depending on the values of certain attributes.
|
|
When multiple bindings are applied to the same bound element, the sheets
|
|
from each binding all contribute to the final set of style sheets to
|
|
apply, the style sheets of the <a href="#most-derived">most derived
|
|
binding</a> being walked first. For each binding, the style sheets that
|
|
apply are as follows, in the order given:</p>
|
|
|
|
<p><em>Scoped style sheets:</em> A binding file can load style sheets
|
|
using the <code><a href="#style2">style</a></code> element. (See: <a
|
|
href="#loading7">loading style sheets</a>.) These style sheets must be
|
|
applied to the bound element and to all shadow content attached to the
|
|
bound element.</p>
|
|
|
|
<p>If the binding was attached using CSS, the scoped style sheets have the
|
|
same CSS origin as the sheet with the rule responsible for the binding.
|
|
Style sheets used by bindings that are attached using the DOM or using
|
|
<code title=import><a href="#importing1"><?xbl?></a></code> are
|
|
treated as author-level sheets.</p>
|
|
|
|
<p>When bindings from multiple levels are applied to the same bound
|
|
element, the style sheets that apply must cascade according to their own
|
|
levels.</p>
|
|
|
|
<p class=example>An element E is attached to binding U from the user agent
|
|
style sheet, and binding A from the DOM, which places A in the author
|
|
level. When the style sheets that apply to E are sorted, U must be
|
|
applied at the UA level and A at the author level.</p>
|
|
|
|
<p><em><a href="#author">Author style sheets</a></em>: While the <code
|
|
title=attr-template-apply-author-sheets><a
|
|
href="#apply-author-sheets">apply-author-sheets</a></code> attribute on
|
|
the <code><a href="#template0">template</a></code> element found at the
|
|
root of the element's shadow tree is set to <code>true</code>, the rules
|
|
specified in any <a href="#author">author style sheets</a> at <a
|
|
href="#shadow9" title="shadow scope">outer shadow scopes</a> (including
|
|
those promoted to outer scopes using <code
|
|
title=attr-content-apply-binding-sheets><a
|
|
href="#apply-binding-sheets">apply-binding-sheets</a></code>, as defined
|
|
below) must be applied to the shadow content. Otherwise, only those
|
|
matched through <a href="#pseudo-list">predefined pseudo-elements</a> are
|
|
used, and other author-level sheets in higher shadow scopes must not be
|
|
applied to the shadow content. (The bound element is always styled using
|
|
the sheets of higher shadow scopes.)</p>
|
|
|
|
<p>By default, style sheets specified in bindings (as described above) are
|
|
applied only to shadow content generated by bindings attached to the
|
|
bound element and to the bound element itself. A second attribute, <code
|
|
title=attr-content-apply-binding-sheets><a
|
|
href="#apply-binding-sheets">apply-binding-sheets</a></code>, can be used
|
|
to indicate that all descendants of the bound element, both shadow and
|
|
explicit, can be styled by the sheets in the binding's document. This can
|
|
be controlled on a per-insertion-point basis. While this attribute is set
|
|
to <code>true</code> on a <code><a href="#content0">content</a></code>
|
|
node in the shadow tree DOM, any nodes that are assigned to that element,
|
|
and any descendants of those nodes, must have the scoped style sheets of
|
|
the binding (those that apply to the shadow content as described above)
|
|
applied to them too, as if they had been promoted to the higher scope.</p>
|
|
|
|
<p>Sheets within each origin are always walked from the innermost shadow
|
|
scope to the outermost shadow scope (with rules in the outermost shadow
|
|
scope therefore overriding rules of equal specificity in the innermost
|
|
shadow scope). With this ordering a binding that defines a widget can
|
|
define a default look for the widget that can then be easily overridden
|
|
by a client of the widget. For multiple bindings attached to the same
|
|
element, the sheets are walked from the <a href="#base-binding">base
|
|
binding</a> to the <a href="#most-derived">most derived binding</a>.</p>
|
|
|
|
<p><em><a href="#user-agent">User agent style sheets</a> and <a
|
|
href="#user-style">user style sheets</a></em>: These are always applied
|
|
to all shadow scopes.</p>
|
|
|
|
<p>Since styles from both author style sheets and binding style sheets are
|
|
applied to the bound element, it is possible for an infinite loop to form
|
|
where an author sets the '<code title="binding property"><a
|
|
href="#binding18">binding</a></code>' property to a particular binding
|
|
that then explicitly sets the '<code title="binding property"><a
|
|
href="#binding18">binding</a></code>' property to 'none' (or another
|
|
binding). This specification does not take any precautions to avoid this,
|
|
any more than it takes precautions to avoid loops caused by binding
|
|
constructors explicitly calling <code><a
|
|
href="#removebinding">removeBinding()</a></code> to remove the binding
|
|
itself and binding detachment event handlers reattaching the bindings.
|
|
Similar potential loops exist also in underlying technologies, for
|
|
example <code>:hover</code> rules that cause elements to no longer be
|
|
hovered, or focus event handlers that move focus to an element and blur
|
|
event handlers that move focus back to the element.</p>
|
|
|
|
<p>In so far as XBL is concerned, authors must avoid constructing such
|
|
loops, and implementers must ensure that such loops do not prevent users
|
|
from interacting with the user agent.</p>
|
|
|
|
<h4 id=styleSummary><span class=secno>4.10.1. </span>Summary of styling
|
|
rules</h4>
|
|
|
|
<p><em>This section is non-normative.</em></p>
|
|
|
|
<p>The <code><style></code> is applied only to the bound element and
|
|
the shadow content that was generated by the binding. The
|
|
<code><style></code> is also applied to explicit children (and
|
|
their descendants) assigned to <code><content></code> elements
|
|
whose <code title=attr-content-apply-binding-sheets><a
|
|
href="#apply-binding-sheets">apply-binding-sheets</a></code> is set to
|
|
<code>true</code>.</p>
|
|
|
|
<p>Continuing from the above, author sheets (styles from the bound
|
|
document) are applied to the shadow content only if <code
|
|
title=attr-template-apply-author-sheets><a
|
|
href="#apply-author-sheets">apply-author-sheets</a></code> is set to true
|
|
for the <code><template></code>.</p>
|
|
|
|
<p>Last, but not least, one can use author sheets to change the style of
|
|
elements in the shadow content that use the <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attribute, as long as it matches
|
|
them with pseudo-elements (irrespective of the <code
|
|
title=attr-template-apply-author-sheets><a
|
|
href="#apply-author-sheets">apply-author-sheets</a></code> setting).</p>
|
|
|
|
<h2 id=binding4><span class=secno>5. </span><dfn id=binding23>Binding
|
|
Implementations</dfn></h2>
|
|
|
|
<p>Bindings can define methods and properties on a bound element using the
|
|
<code><a href="#implementation0">implementation</a></code> element. A
|
|
binding implementation provides a new set of methods and properties that
|
|
can be invoked from the bound element.</p>
|
|
|
|
<p>How the binding implementation is defined depends on the scripting
|
|
language used; the details for ECMAScript are defined below.</p>
|
|
|
|
<p>In general, however, each binding has an object that implements the
|
|
<code><a href="#xblimplementation">XBLImplementation</a></code>
|
|
interface, along with any other interfaces that the implementation might
|
|
implement. This is the <em>implementation object</em> for that instance
|
|
of the binding. All elements implement the <code><a
|
|
href="#elementxbl">ElementXBL</a></code> interface, whose <code><a
|
|
href="#xblimplementations">xblImplementations</a></code> member returns
|
|
an object implementing <code><a
|
|
href="#xblimplementationlist">XBLImplementationList</a></code>. This
|
|
object lists all the implementation objects for that bound element. (If
|
|
the element is not a bound element, the list is empty.)</p>
|
|
|
|
<h3 id=the-xblimplementation><span class=secno>5.1. </span>The <code><a
|
|
href="#xblimplementation">XBLImplementation</a></code> Interface</h3>
|
|
|
|
<p>All implementation objects support the <code><a
|
|
href="#xblimplementation">XBLImplementation</a></code> interface (in
|
|
addition to any other interfaces specific to the binding). By
|
|
implementing the methods defined in this interface, bindings can be
|
|
notified of the binding's state with respect to its environment.</p>
|
|
|
|
<pre
|
|
class=idl>interface <dfn id=xblimplementation>XBLImplementation</dfn> {
|
|
void <a href="#xblbindingattached">xblBindingAttached</a>();
|
|
void <a href="#xblentereddocument">xblEnteredDocument</a>();
|
|
void <a href="#xblleftdocument">xblLeftDocument</a>();
|
|
};</pre>
|
|
|
|
<p>The <dfn id=xblbindingattached><code>xblBindingAttached()</code></dfn>
|
|
method is called by the user agent after the binding has been attached.
|
|
(See: <a href="#binding19">binding attachment model</a>.)</p>
|
|
|
|
<p>The <dfn id=xblentereddocument><code>xblEnteredDocument()</code></dfn>
|
|
method is called by the user agent in two cases:</p>
|
|
|
|
<ul>
|
|
<li> When the bound element, or one of its ancestors, or one of the
|
|
elements in a higher shadow scope, is inserted into the document.
|
|
|
|
<li> When the binding is originally attached, if the bound element is
|
|
already in the document.
|
|
</ul>
|
|
|
|
<p>Thus, it can be used to perform initialization steps that depend upon
|
|
being in a document. (See: <a href="#binding19">binding attachment
|
|
model</a>, <a href="#handling3">handling insertion and removal from the
|
|
document</a>.)</p>
|
|
|
|
<p>The <dfn id=xblleftdocument><code>xblLeftDocument()</code></dfn> method
|
|
is called by the user agent when the bound element, or one of its
|
|
ancestors, or one of the elements in a higher shadow scope, is removed
|
|
from the document. (See: <a href="#handling3">handling insertion and
|
|
removal from the document</a>.)</p>
|
|
|
|
<p>If the <code><a href="#implementation0">implementation</a></code> does
|
|
not define one of these methods, then when that method is invoked,
|
|
nothing must happen (as if all bindings had default implementations of
|
|
those methods that were no-ops).</p>
|
|
<!-- XXX need a way to persist certain values -->
|
|
<p>Authors should not start their own methods with the three letters
|
|
"xbl". Future versions of this specification might add new callbacks to
|
|
this interface, and if they do, those methods will start with the prefix
|
|
"xbl".</p>
|
|
<!-- XXX more callbacks:
|
|
http://lxr.mozilla.org/seamonkey/source/content/xtf/public/nsIXTFStyledElementWrapper.idl
|
|
xblSelected to indicate that the selection now spans the element (glazou)
|
|
-->
|
|
|
|
<div class=example>
|
|
<p>This binding implements a clock. However, to save resources, the clock
|
|
is only active when it is actually included in a document.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding id="clock">
|
|
<implementation>
|
|
({
|
|
xblEnteredDocument: function () {
|
|
this.timer = setInterval(update, 1000);
|
|
},
|
|
xblLeftDocument: function () {
|
|
clearInterval(this.timer);
|
|
},
|
|
update: function () {
|
|
this.shadowTree.getElementById('clock-value').textContent = new Date();
|
|
},
|
|
})
|
|
</implementation>
|
|
<template><div id="clock-value"></div></template>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<h3 id=the-xblimplementationlist><span class=secno>5.2. </span>The
|
|
<code><a href="#xblimplementationlist">XBLImplementationList</a></code>
|
|
Interface</h3>
|
|
|
|
<p>The <dfn id=xblimplementations><code>xblImplementations</code></dfn>
|
|
attribute on all elements must return an instance of an <code><a
|
|
href="#xblimplementationlist">XBLImplementationList</a></code> object
|
|
(the same object for the lifetime of the element), which is a live list
|
|
of the implementation objects provided by the bindings for that bound
|
|
element at any particular point in time.</p>
|
|
|
|
<pre
|
|
class=idl>interface <dfn id=xblimplementationlist>XBLImplementationList</dfn> {
|
|
<a href="#xblimplementation">XBLImplementation</a> <a href="#itemn" title=XBLImplementationList-item>item</a>(in unsigned long index);
|
|
readonly attribute unsigned long <a href="#length" title=XBLImplementationList-length>length</a>;
|
|
};</pre>
|
|
|
|
<p>The <dfn id=length
|
|
title=XBLImplementationList-length><code>length</code></dfn> attribute
|
|
must return the number of implementation objects associated with the
|
|
bound element, or zero if the element is not a bound element or has none
|
|
of its bindings have implementations.</p>
|
|
|
|
<p>The <dfn id=itemn
|
|
title=XBLImplementationList-item><code>item(<var>n</var>)</code></dfn>
|
|
method must return the <var>n</var>th implementation object associated
|
|
with the bound element. If the index is not a number between zero and
|
|
<code title=XBLImplementationList-length><a
|
|
href="#length">length</a></code>-1 (inclusive), then the method must
|
|
raise an <code>INDEX_SIZE_ERR</code> DOM exception. <a
|
|
href="#refsDOM3CORE">[DOM3CORE]</a></p>
|
|
|
|
<p>The list must be ordered such that the <a href="#most-derived">most
|
|
derived binding</a> is last, and the <a href="#base-binding">base
|
|
binding</a> has index zero.</p>
|
|
|
|
<p>In ECMAScript implementations, objects that implement the <code><a
|
|
href="#xblimplementationlist">XBLImplementationList</a></code> interface
|
|
must also have a [[Get]] method that, when invoked with a property name
|
|
that is a number, acts like the <code title=XBLImplementationList-item><a
|
|
href="#itemn">item()</a></code> method would when invoked with that
|
|
argument.</p>
|
|
|
|
<h3 id=accessing><span class=secno>5.3. </span>Accessing Binding
|
|
Implementations</h3>
|
|
|
|
<p>Script can access binding implementations directly using the <code><a
|
|
href="#xblimplementations">xblImplementations</a></code> member. In
|
|
addition, in languages that support dynamic dispatch (such as
|
|
ECMAScript), any attempts to access members of <code><a
|
|
href="#elementxbl">ElementXBL</a></code> objects that do not correspond
|
|
to methods or properties on the object itself but do correspond to
|
|
members of one of the objects in the <code><a
|
|
href="#xblimplementations">xblImplementations</a></code> list must be
|
|
forwarded to the last object in the <code><a
|
|
href="#xblimplementations">xblImplementations</a></code> list that is so
|
|
matched.</p>
|
|
<!-- XXX example needed, including one that shows this with an
|
|
lvalue -->
|
|
|
|
<h3 id=ecmascript><span class=secno>5.4. </span><dfn
|
|
id=ecmascript1>ECMAScript Bindings</dfn></h3>
|
|
|
|
<p>When a binding is attached, the user agent must follow the following
|
|
steps to make the binding implementation available to scripts:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>If this is the first time the binding defined by that <code><a
|
|
href="#binding16">binding</a></code> element is used since that binding
|
|
document was loaded, and if that element contains an <code><a
|
|
href="#implementation0">implementation</a></code> element, then:</p>
|
|
|
|
<ol>
|
|
<li>The first <code><a
|
|
href="#implementation0">implementation</a></code> element child of the
|
|
<code><a href="#binding16">binding</a></code> element must have its
|
|
code <a href="#compiling1" title="Compiling ECMAScript
|
|
Bindings">compiled and run</a> (see below).
|
|
|
|
<li>The return value of that script, if it is an object, must be
|
|
forever associated with that <code><a
|
|
href="#binding16">binding</a></code> element as that binding's
|
|
<em>implementation prototype object</em>.
|
|
</ol>
|
|
|
|
<p>Otherwise, if the <code><a href="#binding16">binding</a></code>
|
|
element doesn't contain an <code><a
|
|
href="#implementation0">implementation</a></code> element, or if it
|
|
does but it does not evaluate to an object, then an empty object must
|
|
be created (by invoking the <code>Object</code> constructor in the
|
|
global scope of the binding document), and the <code><a
|
|
href="#binding16">binding</a></code> element's implementation prototype
|
|
object must be forever set to that object.</p>
|
|
|
|
<p class=note>Any further changes to <code><a
|
|
href="#implementation0">implementation</a></code> elements will have no
|
|
effect on the implementation prototype object of this particular
|
|
binding.</p>
|
|
|
|
<li>
|
|
<p>Next, the UA must create two new ECMAScript objects by invoking the
|
|
<code>Object</code> constructor in the global scope of the binding
|
|
document. These objects are the <dfn id=internal>internal object</dfn>
|
|
and the <dfn id=external0>external object</dfn>.</p>
|
|
|
|
<li>
|
|
<p>The [[Prototype]] property of the internal object must be set to the
|
|
external object, and the [[Prototype]] property of the external object
|
|
must be set to the binding's implementation prototype object.</p>
|
|
|
|
<li>
|
|
<p>The internal object must then have the following fields defined:</p>
|
|
|
|
<dl>
|
|
<dt><dfn id=external1><code>external</code></dfn>
|
|
|
|
<dd>This field's value must be set to a reference to the external
|
|
object.
|
|
|
|
<dt><dfn id=boundelement><code>boundElement</code></dfn>
|
|
|
|
<dd>This field's value must be set to a reference of the node object
|
|
that is the bound element.
|
|
|
|
<dt><dfn id=shadowtree><code>shadowTree</code></dfn>
|
|
|
|
<dd>This field's value must be initially set to null. Its value is
|
|
changed during <a href="#rules3" title="Rules for Shadow Content
|
|
Generation">shadow content generation</a> and <a href="#rules4"
|
|
title="Rules for Shadow Content Destruction">destruction</a>.
|
|
|
|
<dt><dfn id=basebinding><code>baseBinding</code></dfn>
|
|
|
|
<dd>If the binding's <code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code> attribute caused another binding to
|
|
be attached to the bound element, then the <code><a
|
|
href="#basebinding">baseBinding</a></code> field's value must be set
|
|
to a reference of that binding's implementation object, if it has one
|
|
(if that is an ECMAScript implementation as well, then that is that
|
|
binding's external object). Otherwise, it must be set to the value
|
|
null.
|
|
</dl>
|
|
</ol>
|
|
|
|
<p>Conceptually, the internal and external objects together make the
|
|
implementation object, but as far as the <code><a
|
|
href="#xblimplementations">xblImplementations</a></code> property's list
|
|
is concerned, the external object is the one that is returned as the
|
|
implementation object.</p>
|
|
|
|
<h4 id=compiling><span class=secno>5.4.1. </span><dfn
|
|
id=compiling1>Compiling ECMAScript Bindings</dfn></h4>
|
|
|
|
<p>When the user agent has to compile and run an XBL binding ECMAScript
|
|
implementation, it must first obtain the script itself in the manner
|
|
described in the section on <a href="#loading6">loading and running
|
|
scripts</a>, and must then compile and execute the script using the
|
|
binding document's global scope.</p>
|
|
|
|
<p>If the script evaluates to an object, then that is the
|
|
<em>implementation prototype object</em>. Otherwise, there isn't one.</p>
|
|
|
|
<h4 id=invoking><span class=secno>5.4.2. </span>Invoking Methods on an
|
|
ECMAScript Implementation Object</h4>
|
|
|
|
<p>When function code of an implementation object implemented in
|
|
ECMAScript is called, the user agent must set the <code>this</code> value
|
|
to the <a href="#internal">internal object</a> associated with the <a
|
|
href="#external0">external object</a> on which the function was invoked.</p>
|
|
|
|
<h2 id=event0><span class=secno>6. </span><dfn id=event11>Event
|
|
Handlers</dfn></h2>
|
|
|
|
<h3 id=event1><span class=secno>6.1. </span><dfn id=event12>Event
|
|
Forwarding</dfn></h3>
|
|
|
|
<p>Whenever an event passes through a bound element, whether during the
|
|
capture, target, bubble, or <a href="#the-default1" title="default
|
|
phase">default</a> phases, the user agent must also invoke any
|
|
appropriate event listeners attached to the binding's first <code><a
|
|
href="#handlers0">handlers</a></code> element.</p>
|
|
|
|
<p>When events are forwarded in this manner, the event handlers attached
|
|
to the <code><a href="#handlers0">handlers</a></code> element must fire
|
|
after any event handlers on the bound element itself in the capture
|
|
phase, after the event has been retargeted to shadow nodes, if
|
|
appropriate; and before any event handlers on the bound element itself in
|
|
the target and bubble phases, before the event has been retargeted to the
|
|
bound element, if appropriate. (See: <a href="#event13">event flow and
|
|
targeting across shadow scopes</a>.)</p>
|
|
|
|
<p>Event handlers must fire first on the <a href="#most-derived">most
|
|
derived binding</a> and then on its inherited binding, continuing all the
|
|
way up the chains to the <a href="#base-binding">base binding</a>. A
|
|
derived handler then has a way of preventing the event from flowing to
|
|
the handlers of the bindings it inherits from, by using the
|
|
<code>stopImmediatePropagation()</code> method.</p>
|
|
|
|
<p>Event handlers may be attached to the <code><a
|
|
href="#handlers0">handlers</a></code> element using any method, including
|
|
DOM3 Events' <code>addEventListener()</code> method and the <code><a
|
|
href="#handler0">handler</a></code> XBL element. All event handlers
|
|
registered on the first <code><a href="#handlers0">handlers</a></code>
|
|
element of the binding are considered, not just those attached using the
|
|
<code><a href="#handler0">handler</a></code> element.</p>
|
|
|
|
<div class=example>
|
|
<p>In the following example, the bound element is the
|
|
<code>hotspot</code> element. When either it is clicked or the element
|
|
inside it is clicked, an alert is generated containing the text "Hello
|
|
World".</p>
|
|
|
|
<p>The bound document is:</p>
|
|
|
|
<pre><hotspot message="Hello World">
|
|
<instruction> Activate this text. </instruction>
|
|
</hotspot></pre>
|
|
|
|
<p>The binding is:</p>
|
|
|
|
<pre><binding>
|
|
<handlers>
|
|
<handler event="click">
|
|
alert(event.currentTarget.getAttribute('message'));
|
|
</handler>
|
|
</handlers>
|
|
</binding></pre>
|
|
|
|
<p>Note that the event object passed to the <code><a
|
|
href="#handlers0">handlers</a></code>'s handlers is the same as would
|
|
have been passed to event handlers registered directly on the bound
|
|
element. This is why <code>currentTarget</code> in this example points
|
|
to the bound element.</p>
|
|
</div>
|
|
|
|
<h3 id=registering><span class=secno>6.2. </span><dfn
|
|
id=registering1>Registering Event Handlers with the <code>handler</code>
|
|
Element</dfn></h3>
|
|
|
|
<p>Whenever the <code>event</code> or <code>phase</code> attributes of an
|
|
XBL <code><a href="#handler0">handler</a></code> element change, or
|
|
whenever a <code><a href="#handler0">handler</a></code> element's parent
|
|
changes, an event listener must be registered on the element's parent
|
|
element, if it has one; and if an event listener had previously been
|
|
registered for that <code><a href="#handler0">handler</a></code> element,
|
|
it must be removed.</p>
|
|
|
|
<p>In terms of the DOM3 Events <code>addEventListenerNS()</code> method,
|
|
the arguments used when registering the new event listener must be set as
|
|
follows:</p>
|
|
|
|
<dl>
|
|
<dt><code>namespaceURI</code>
|
|
|
|
<dd>Always <code>null</code> in this version of XBL.
|
|
|
|
<dt><code>type</code>
|
|
|
|
<dd>The literal value of the <code title=attr-handler-event><a
|
|
href="#event9">event</a></code> attribute, or the empty string if the
|
|
attribute is missing.
|
|
|
|
<dt><code>listener</code>
|
|
|
|
<dd>An object implementing the <code>EventListener</code> interface that
|
|
invokes the <code><a href="#handler0">handler</a></code> element as
|
|
described below.
|
|
|
|
<dt><code>useCapture</code>
|
|
|
|
<dd>True if the <code title=attr-handler-phase><a
|
|
href="#phase">phase</a></code> attribute is present and has the literal
|
|
value <code>capture</code>, otherwise false.
|
|
|
|
<dt><code>evtGroup</code>
|
|
|
|
<dd>Always <code>null</code> in this version of XBL. (Event listeners
|
|
registered with <code><a href="#handler0">handler</a></code> elements
|
|
are registered in the default event group.)
|
|
</dl>
|
|
|
|
<p>Thus, the <code title=attr-handler-event><a
|
|
href="#event9">event</a></code> attribute specifies the event type, and
|
|
the <code title=attr-handler-phase><a href="#phase">phase</a></code>
|
|
attribute the listener type. If the <code title=attr-handler-event><a
|
|
href="#event9">event</a></code> attribute is missing or its value is the
|
|
empty string, it is <a href="#in-error">in error</a>. If the <code
|
|
title=attr-handler-phase><a href="#phase">phase</a></code> attribute is
|
|
present but has a value other than the literal strings
|
|
<code>capture</code>, <code>target</code>, <code>bubble</code>, or
|
|
<code>default-action</code>, it is <a href="#in-error">in error</a>.
|
|
(However, their being <a href="#in-error">in error</a> does not affect
|
|
the processing model described above.)</p>
|
|
|
|
<p>When a <code><a href="#handler0">handler</a></code> element is invoked
|
|
by the object passed to the <code>addEventListenerNS()</code> method, the
|
|
user agent must check that the event in question was forwarded to a
|
|
<code><a href="#handlers0">handlers</a></code> element from a bound
|
|
element, and that that <code><a href="#handlers0">handlers</a></code>
|
|
element is the parent node of the <code><a
|
|
href="#handler0">handler</a></code> element.</p>
|
|
|
|
<p>If that isn't the case, then the invocation must do nothing.</p>
|
|
|
|
<p>Otherwise, if that condition <em>is</em> met, then the UA must check
|
|
any relevant filters specified on the <code><a
|
|
href="#handler0">handler</a></code> element. If any of them fail to match
|
|
the event, then the invocation must not do anything else. (The filter
|
|
attributes are defined in the next few sections.)</p>
|
|
|
|
<p>Otherwise, if all the filters match, then the user agent must execute
|
|
the contents of the <code><a href="#handler0">handler</a></code> element,
|
|
treating it as being in the language specified by the <code
|
|
title=attr-xbl-script-type><a href="#script-type">script-type</a></code>
|
|
attribute. (See: <a href="#loading6">loading and running scripts</a>, <a
|
|
href="#event14">event handlers implemented in ECMAScript</a>.) The script
|
|
must be run in the context of the binding document (and not, e.g., in the
|
|
bound document's context).</p>
|
|
|
|
<p>The <code title=attr-handler-propagate><a
|
|
href="#propagate">propagate</a></code> attribute specifies whether, after
|
|
processing all listeners at the current node, the event is allowed to
|
|
continue on its path (either in the capture or the bubble phase). The
|
|
possible values are <code>stop</code> and <code>continue</code> (the
|
|
default). If <code>stop</code> is specified, then after the event handler
|
|
has been fired, the event's <code>stopPropagation()</code> method must be
|
|
called.</p>
|
|
|
|
<p>The <code title=attr-handler-default-action><a
|
|
href="#default-action">default-action</a></code> attribute specifies
|
|
whether, after processing of all listeners for the event, the default
|
|
action for the event (if any) should be performed or not. For instance,
|
|
in XHTML the default action for a mouse click on an <code>html:a</code>
|
|
element or one of its descendants is to traverse the link. The possible
|
|
values are <code>cancel</code> and <code>perform</code> (the default). If
|
|
<code>cancel</code> is specified, then after the event handler has been
|
|
fired, the event's <code>preventDefault()</code> method must be called.</p>
|
|
|
|
<p>The <code title=attr-handler-trusted><a
|
|
href="#trusted">trusted</a></code> attribute is a filter that, if set to
|
|
the value <code>true</code>, matches only events whose <code
|
|
title=event-trusted><a href="#trusted0">trusted</a></code> attribute is
|
|
true. Otherwise, if it has another value or if it is not specified, any
|
|
event matches this filter. This filter can be used regardless of the type
|
|
of the event.</p>
|
|
|
|
<p>The <code title=attr-handler-phase><a href="#phase">phase</a></code>
|
|
attribute is a filter that matches only events that are in the phase it
|
|
specifies. If the attribute has the value <code>capture</code>, it must
|
|
only match events whose <code>eventPhase</code> attribute has the value
|
|
<code>CAPTURING_PHASE</code> (1). If the attribute has the value
|
|
<code>target</code>, it must only match events whose
|
|
<code>eventPhase</code> attribute has the value <code>AT_TARGET</code>
|
|
(2). If the attribute has the value <code>default-action</code>, it must
|
|
only match events whose <code>eventPhase</code> attribute has the value
|
|
0x78626C44 <!--
|
|
"xblD" in ASCII --> (2019716164). This is the value
|
|
used in the <a href="#the-default1">default phase</a>. If it is specified
|
|
and has another value, it must only match events whose
|
|
<code>eventPhase</code> attribute has the value <code>BUBBLE_PHASE</code>
|
|
(3). If it is not specified, it must only match events whose
|
|
<code>eventPhase</code> attribute has the value <code>AT_TARGET</code>
|
|
(2) or <code>BUBBLE_PHASE</code> (3). (If it isn't specified, then it
|
|
isn't registered as a capture event listener, so the handler would never
|
|
see the value <code>CAPTURING_PHASE</code> (1).) This filter can be used
|
|
regardless of the type of the event.</p>
|
|
|
|
<p>In addition to the <code title=attr-handler-trusted><a
|
|
href="#trusted">trusted</a></code> and <code title=attr-handler-phase><a
|
|
href="#phase">phase</a></code> filters, event-specific filters may be
|
|
used, as described in the following sections. Only filters appropriate to
|
|
the given event type may be used; all other filter attributes, if
|
|
specified, are <a href="#in-error">in error</a> and UAs must <a
|
|
href="#ignoring">ignore</a> them.</p>
|
|
|
|
<h3 id=mouse><span class=secno>6.3. </span><dfn id=mouse1>Mouse Event
|
|
Handler Filters</dfn></h3>
|
|
|
|
<p>For events that use or derive from the <code>MouseEvent</code>
|
|
interface, three event-specific filter attributes may be used. <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>The filters are:</p>
|
|
|
|
<dl>
|
|
<dt><code title=attr-handler-button><a href="#button">button</a></code>
|
|
|
|
<dd>A list of values, at least one of which has to match the
|
|
<code>button</code> attribute on the event object for the XBL event
|
|
handler to fire. If the attribute is not specified, then any value of
|
|
the <code>button</code> attribute on the event object must be considered
|
|
a match. If the value is specified, it must be a <a
|
|
href="#attributes22">space-separated</a> list of values, each of which
|
|
must be one or more digits in the range U+0030 DIGIT ZERO (0) to U+0039
|
|
DIGIT NINE (9). Each string must be interpreted as a base ten integer
|
|
and then compared to the value of the <code>button</code> attribute on
|
|
the event object. If none of the values match the <code>button</code>
|
|
attribute, then the event handler must not be executed.
|
|
|
|
<dt><code title=attr-handler-click-count><a
|
|
href="#click-count">click-count</a></code>
|
|
|
|
<dd>A list of values, at least one of which has to match the
|
|
<code>detail</code> attribute on the event object for the XBL event
|
|
handler to fire. If the attribute is not specified, then any value of
|
|
the <code>detail</code> attribute on the event object must be considered
|
|
a match. If the value is specified, it must be a <a
|
|
href="#attributes22">space-separated</a> list of values, each of which
|
|
must be one or more digits in the range U+0030 DIGIT ZERO (0) to U+0039
|
|
DIGIT NINE (9). Each string must be interpreted as a base ten integer
|
|
and then compared to the value of the <code>detail</code> attribute on
|
|
the event object. If none of the values match the <code>detail</code>
|
|
attribute, then the event handler must not be executed. Note that this
|
|
is checked for <em>any</em> event that uses the <code>MouseEvent</code>
|
|
interface, not just those for which <code>detail</code> is defined.
|
|
Authors should take care to not specify this attribute with, for
|
|
example, <code>mouseover</code> events, since in that context
|
|
<code>detail</code> is undefined.
|
|
|
|
<dt><code title=attr-handler-modifiers><a
|
|
href="#modifiers1">modifiers</a></code>
|
|
|
|
<dd>See <a href="#modifiers2">modifiers</a>.
|
|
</dl>
|
|
|
|
<h3 id=key-event><span class=secno>6.4. </span><dfn id=key-event1>Key
|
|
Event Handler Filters</dfn></h3>
|
|
|
|
<p>For events that use or derive from the <code>KeyboardEvent</code>
|
|
interface, three event-specific filter attributes may be used. <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>The filters are:</p>
|
|
|
|
<dl>
|
|
<dt><code title=attr-handler-key><a href="#key">key</a></code>
|
|
|
|
<dd>The key identifier. If specified, the value must be an exact literal
|
|
match of the <code>keyIdentifier</code> attribute of the event object.
|
|
For example, <code>Enter</code>. If this filter is specified but the
|
|
<code title=attr-handler-modifiers><a
|
|
href="#modifiers1">modifiers</a></code> attribute is not, the user agent
|
|
must act as if the <code title=attr-handler-modifiers><a
|
|
href="#modifiers1">modifiers</a></code> attribute had been set with the
|
|
value "<code>none</code>". If specified, the value of this attribute
|
|
must be a valid value of the <code>keyIdentifier</code> attribute.
|
|
|
|
<dt><code title=attr-handler-key-location><a
|
|
href="#key-location">key-location</a></code>
|
|
|
|
<dd>If specified, this attribute's value must be a <a
|
|
href="#attributes22">space-separated</a> list of values from the four
|
|
literal (case-sensitive) keywords <code>standard</code>,
|
|
<code>left</code>, <code>right</code>, and <code>numpad</code> (with no
|
|
duplicates), which map to the DOM values 0x00, 0x01, 0x02, or 0x03
|
|
respectively. If specified, the event object's <code>keyLocation</code>
|
|
attribute must have a value equal to the numeric value of one of the
|
|
specified keywords. Unknown and duplicate values are <a
|
|
href="#in-error">in error</a> and UAs must <a
|
|
href="#ignoring">ignore</a> them (although without dropping any <a
|
|
href="#correct">correct</a> values).
|
|
|
|
<dt><code title=attr-handler-modifiers><a
|
|
href="#modifiers1">modifiers</a></code>
|
|
|
|
<dd>See <a href="#modifiers2">modifiers</a>.
|
|
</dl>
|
|
|
|
<h3 id=text-input><span class=secno>6.5. </span><dfn id=text-input1>Text
|
|
Input Event Handler Filters</dfn></h3>
|
|
|
|
<p>For events that use or derive from the <code>TextEvent</code>
|
|
interface, one event-specific filter attribute may be used. <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>The filter is:</p>
|
|
|
|
<dl>
|
|
<dt><code title=attr-handler-text><a href="#text">text</a></code>
|
|
|
|
<dd>The text data to match. If specified, the value must be an exact
|
|
literal match of the <code>data</code> attribute of the event object.
|
|
The value of the attribute may be any string.
|
|
</dl>
|
|
|
|
<h3 id=mutation><span class=secno>6.6. </span><dfn id=mutation1>Mutation
|
|
Event Handler Filters</dfn></h3>
|
|
|
|
<p>For events that use or derive from the <code>MutationEvent</code>
|
|
interface, four event-specific filter attributes may be used. <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>The filters are:</p>
|
|
|
|
<dl>
|
|
<dt><code title=attr-handler-prev-value><a
|
|
href="#prev-value">prev-value</a></code>
|
|
|
|
<dd>If specified, the value must be an exact literal match of the
|
|
<code>prevValue</code> attribute of the event object. The value of the
|
|
attribute may be any string.
|
|
|
|
<dt><code title=attr-handler-new-value><a
|
|
href="#new-value">new-value</a></code>
|
|
|
|
<dd>If specified, the value must be an exact literal match of the
|
|
<code>newValue</code> attribute of the event object. The value of the
|
|
attribute may be any string.
|
|
|
|
<dt><code title=attr-handler-attr-name><a
|
|
href="#attr-name">attr-name</a></code>
|
|
|
|
<dd>If specified, the value must be an exact literal match of the
|
|
<code>attrName</code> attribute of the event object. The value of the
|
|
attribute may be any string.
|
|
|
|
<dt><code title=attr-handler-attr-change><a
|
|
href="#attr-change">attr-change</a></code>
|
|
|
|
<dd>If specified, this attribute's value must be a <a
|
|
href="#attributes22">space-separated</a> list of values from the three
|
|
literal (case-sensitive) keywords <code>modification</code>,
|
|
<code>addition</code>, <code>removal</code> (with no duplicates), which
|
|
map to the DOM values 0x00, 0x01, or 0x02 respectively. If specified,
|
|
the event object's <code>attrChange</code> attribute must have a value
|
|
equal to the numeric value of one of the specified keywords. Unknown and
|
|
duplicate values are <a href="#in-error">in error</a> and the UA must <a
|
|
href="#ignoring">ignore</a> them, although without causing <a
|
|
href="#correct">correct</a> values to be dropped.
|
|
</dl>
|
|
|
|
<p>There are currently no attributes specifically designed to be used with
|
|
events that use the <code>MutationEventName</code> interface.</p>
|
|
|
|
<h3 id=modifiers><span class=secno>6.7. </span><dfn
|
|
id=modifiers2>Modifiers</dfn></h3>
|
|
|
|
<p>The <code title=attr-handler-modifiers><a
|
|
href="#modifiers1">modifiers</a></code> attribute specifies a filter
|
|
dependent on which keyboard accelerator keys ("modifiers") are set.</p>
|
|
|
|
<p>The attribute is a <a href="#attributes22">space-separated</a> list of
|
|
values.</p>
|
|
|
|
<p>To process this filter, the user agent must first invoke the
|
|
<code>getModifierState()</code> method of the event for all the modifiers
|
|
the UA supports, noting the return value for each modifier. The user
|
|
agent must then walk through all the values in the <code
|
|
title=attr-handler-modifiers><a href="#modifiers1">modifiers</a></code>
|
|
attribute, as described in the list below. The filter matches if all the
|
|
modifiers that returned true are accounted for, and none of the values
|
|
made the filter fail.</p>
|
|
|
|
<p class=note>The <code>getModifierState()</code> method, and the
|
|
modifiers that go with it, are defined in DOM3 Events. <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<p>By default, only the <code>CapsLock</code>, <code>NumLock</code>, and
|
|
<code>Scroll</code> modifiers are accounted for. Values on the attribute
|
|
cause other modifiers to be accounted for.</p>
|
|
|
|
<p>Before comparing the modifiers to the attribute values, the user agent
|
|
must convert all the modifiers to lowercase.</p>
|
|
|
|
<p>User agents must recognize the <code>accel</code> keyword as a synonym
|
|
for the modifier that is the primary accelerator key on the platform (on
|
|
Windows, this would typically be <code>control</code>, on Mac it would
|
|
typically be <code>meta</code>).</p>
|
|
|
|
<p>User agents must also recognize the <code>access</code> keyword as a
|
|
synonym for the primary shortcut mnemonic key on the platform (on
|
|
Windows, this would typically be <code>alt</code>).</p>
|
|
|
|
<p>The attribute values must be handled as follows:</p>
|
|
|
|
<dl>
|
|
<dt><code>any</code>
|
|
|
|
<dd>If the keyword <code>any</code> is specified, then all the modifiers
|
|
are accounted for.
|
|
|
|
<dt><code>none</code>
|
|
|
|
<dd>The keyword <code>none</code> makes the filter fail if any modifiers
|
|
returned true, except for the <code>CapsLock</code>,
|
|
<code>NumLock</code>, and <code>Scroll</code> modifiers, which are
|
|
ignored for the purposes of this keyword.
|
|
|
|
<dt><code>+<var>modifier</var></code>
|
|
|
|
<dd>The <var>modifier</var> modifier is accounted for. If the given
|
|
modifier does not correspond to the lowercase version of one of the
|
|
modifiers supported by the UA, or if the <code>getModifierState()</code>
|
|
method did not actually return true for the corresponding modifier, then
|
|
it makes the filter fail.
|
|
|
|
<dt><code>-<var>modifier</var></code>
|
|
|
|
<dd>If the <code>getModifierState()</code> method returned true for the
|
|
modifier corresponding to <var>modifier</var>, then it makes the filter
|
|
fail.
|
|
|
|
<dt><code><var>modifier</var>?</code>
|
|
|
|
<dd>The <var>modifier</var> modifier is accounted for. If the
|
|
<code>getModifierState()</code> method did not actually return true for
|
|
the modifier corresponding to <var>modifier</var>, the value is ignored.
|
|
|
|
<dt>Anything else ("<code><var>modifier</var></code>")
|
|
|
|
<dd>Treated the same as <code>+<var>modifier</var></code>.
|
|
</dl>
|
|
|
|
<p>A modifier can be listed multiple times, though this is not
|
|
particularly useful.</p>
|
|
|
|
<div class=example>
|
|
<p>Here are some examples of what this means:</p>
|
|
|
|
<dl>
|
|
<dt><code title="">modifiers</code> not specified
|
|
|
|
<dd>The modifiers are ignored, unless the <code
|
|
title=attr-handler-key><a href="#key">key</a></code> attribute is
|
|
specified, in which case the event handler is only invoked if no
|
|
modifiers are pressed.
|
|
|
|
<dt><code title="">modifiers=""</code>
|
|
|
|
<dt><code title="">modifiers="none"</code>
|
|
|
|
<dd>The event handler is only invoked if no modifiers are pressed.
|
|
|
|
<dt><code title="">modifiers="any"</code>
|
|
|
|
<dd>The modifiers are ignored.
|
|
|
|
<dt><code title="">modifiers="alt control"</code>
|
|
|
|
<dd>The filter matches if both alt and control were pressed, and no
|
|
others.
|
|
|
|
<dt><code title="">modifiers="alt control?"</code>
|
|
|
|
<dd>The filter matches if alt was pressed, and no others, except maybe
|
|
control.
|
|
|
|
<dt><code title="">modifiers="any -control"</code>
|
|
|
|
<dd>The filter matches if the control key was not pressed, regardless of
|
|
the state of other modifiers.
|
|
|
|
<dt><code title="">modifiers="Alt"</code>
|
|
|
|
<dd>Never matches, since the user agent must compare the given values to
|
|
<em>lowercase</em> modifier names.
|
|
|
|
<dt><code title="">modifiers="accel -capslock"</code>
|
|
|
|
<dd>Matches when the platform's accelerator key is pressed, but only if
|
|
the caps lock key is not active.
|
|
|
|
<dt><code title="">modifiers="alt alt alt"</code>
|
|
|
|
<dd>Same as just listing the alt modifier once: the filter matches if
|
|
only the alt modifier is pressed.
|
|
|
|
<dt><code title="">modifiers="+alt -accel"</code>
|
|
|
|
<dd>Matches when the platform's accelerator key is pressed, but the alt
|
|
modifier is not pressed. If the platform's accelerator key is in fact
|
|
the alt key, this filter can never match.
|
|
</dl>
|
|
</div>
|
|
|
|
<h3 id=event2><span class=secno>6.8. </span><dfn id=event13>Event Flow and
|
|
Targeting Across Shadow Scopes</dfn></h3>
|
|
|
|
<p>DOM events can fire on shadow targets just as they can on explicit
|
|
targets. Events must flow through the <a href="#final0">final flattened
|
|
tree</a>. As long as the event flows within the same shadow tree <a
|
|
href="#shadow9" title="shadow scope">scope</a>, it is no different from
|
|
the behavior outlined in the DOM Events specification.</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>target</code> field set to the bound element.</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
|
|
retargeting 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 rules are exactly reversed. The first
|
|
node to see the event is the node after which bubbling stops. 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>
|
|
|
|
<p>When an event is retargetted at a bound element, the bound element's
|
|
event handlers must see the event only in the target phase. The capture
|
|
phase listeners must not be triggered for the bound element.</p>
|
|
|
|
<p>The timing of event retargeting is such that when the event is
|
|
forwarded to the <code><a href="#handlers0">handlers</a></code> element,
|
|
the binding's handlers see the relevant shadow tree node as the target,
|
|
rather than the bound element as the target. (See: <a
|
|
href="#event12">event forwarding</a>.)</p>
|
|
|
|
<p>Events bubble into deeper scopes; for example, an event fired on a
|
|
bound element's <a href="#explicit3" title="explicit children">explicit
|
|
child</a> bubbles into the element containing the <code><a
|
|
href="#content0">content</a></code> element the element was assigned to.
|
|
This does not cause any event retargeting to take place, either when
|
|
entering the deeper scope or when leaving it, since such an event does
|
|
not actually originate in that shadow tree.</p>
|
|
|
|
<p>Any method invocations on any clones of the event object must also be
|
|
forwarded to the original event and all the clones, so that attempts to
|
|
stop propagation and cancel the default action affect the event
|
|
regardless of how many scopes it has crossed.</p>
|
|
|
|
<div class=example>
|
|
<p>Bound document:</p>
|
|
|
|
<pre><root xmlns="">
|
|
<bound/>
|
|
</root></pre>
|
|
|
|
<p>Binding template applied to the <code>bound</code> element:</p>
|
|
|
|
<pre> ...
|
|
<xbl:template>
|
|
<shadow xmlns="">
|
|
<target/>
|
|
</shadow>
|
|
</xbl:template>
|
|
...</pre>
|
|
|
|
<p>If someone clicks the "target" element, the click event is dispatched
|
|
as follows:</p>
|
|
|
|
<ol>
|
|
<li>The capture listeners on <code>root</code>. Capture phase, target is
|
|
<code>bound</code>.
|
|
|
|
<li>The capture listeners on the binding's <code><a
|
|
href="#handlers0">handlers</a></code>. Capture phase, target is
|
|
<code>target</code>.
|
|
|
|
<li>The capture listeners on <code>shadow</code>. Capture phase, target
|
|
is <code>target</code>.
|
|
|
|
<li>The bubbling listeners on <code>target</code>. Target phase, target
|
|
is <code>target</code>.
|
|
|
|
<li>The bubbling listeners on <code>shadow</code>. Bubbling phase,
|
|
target is <code>target</code>.
|
|
|
|
<li>The bubbling listeners on the binding's <code><a
|
|
href="#handlers0">handlers</a></code>. Bubbling phase, target is
|
|
<code>target</code>.
|
|
|
|
<li>The bubbling listeners on <code>bound</code>. Target phase, target
|
|
is <code>bound</code>.
|
|
|
|
<li>The bubbling listeners on <code>root</code>. Bubbling phase, target
|
|
is <code>bound</code>.
|
|
|
|
<li>The default action listeners on the binding's <code><a
|
|
href="#handlers0">handlers</a></code>. Default phase, target is
|
|
<code>target</code>.
|
|
|
|
<li>The UA's default action listeners for <code>target</code>. Default
|
|
phase, target is <code>target</code>.
|
|
</ol>
|
|
</div>
|
|
|
|
<h3 id=the-default><span class=secno>6.9. </span><dfn id=the-default1
|
|
title="default phase">The Default Phase</dfn></h3>
|
|
|
|
<p>If an event bubbles through or is targeted at one or more bound
|
|
elements, and the event is not canceled (after the capture, target, and
|
|
bubble phases have all completed, its <code>defaultPrevented</code>
|
|
attribute is still false), then the event's <code>eventPhase</code>
|
|
attribute must be set to the value 0x78626C44 <!-- "xblD" in ASCII -->
|
|
(2019716164), and then the event must be <a href="#event12" title="event
|
|
forwarding">forwarded</a> to the relevant <code><a
|
|
href="#handlers0">handlers</a></code> elements of all the bound elements
|
|
the event bubbled through or was targeted at in those bubble and target
|
|
phases, in reverse tree order (starting from the target node and walking
|
|
the tree towards the <code>Document</code> node), with
|
|
<code>currentTarget</code> set to the relevant bound element each time.
|
|
If the event is canceled (that is, if the <code>defaultPrevented</code>
|
|
attribute becomes true) while being forwarded to one of these bound
|
|
elements, subsequent bound elements must not receive the event.</p>
|
|
|
|
<p>If the event has a UA default action, it must only perform it if the
|
|
<code>defaultPrevented</code> attribute is still false after it has been
|
|
so forwarded.</p>
|
|
|
|
<p>The <code>stopPropagation()</code> and
|
|
<code>stopImmediatePropagation()</code> methods must have no effect
|
|
during this "default" phase.</p>
|
|
|
|
<h3 id=the-focus><span class=secno>6.10. </span>The <code>focus</code>,
|
|
<code>DOMFocusIn</code>, <code>blur</code>, and <code>DOMFocusOut</code>
|
|
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 focused.)</p>
|
|
|
|
<p>If the focus moves from the bound element's shadow content to a node
|
|
completely outside the bound element, or vice versa, then the respective
|
|
events must be retargetted instead.</p>
|
|
|
|
<p>The <span>'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>'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>As an example, consider the HTML file upload control. It is a
|
|
focusable element that in turn is made up of two focusable shadow
|
|
elements: a text field and a button. Tab indices can be specified on the
|
|
text field and the button to indicate the order in which the components
|
|
of the file control should be accessed when tabbing.</p>
|
|
|
|
<p>When the user tabs such that the file control should become focused,
|
|
the user agent determines if any shadow content should also become
|
|
focused, using the tab order specified by the shadow content elements.
|
|
It then generates a focus event on the text field inside the file
|
|
control. As this event flows across shadow scopes, it is retargeted to
|
|
be a focus event on the file control itself.</p>
|
|
|
|
<p>Focus events should also be stopped if the bound element is already
|
|
focused. For example, if the user has already focused the text field
|
|
within an HTML file upload control, then the file upload control is now
|
|
also focused. If the user then focuses the button inside the file upload
|
|
control, the focus event generated for the button is stopped before it
|
|
reaches the file control, since the file control is already focused.</p>
|
|
</div>
|
|
|
|
<p>Because content in multiple shadow scopes can be focused, the CSS
|
|
<code>: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>:focus</code> state at the same time.</p>
|
|
|
|
<p class=note>Further specifications may describe in more detail the
|
|
interaction of arbitrary chains of elements that can be in the
|
|
<code>:focus</code> state at the same time.</p>
|
|
|
|
<h3 id=the-mouseover><span class=secno>6.11. </span>The
|
|
<code>mouseover</code> and <code>mouseout</code> 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>
|
|
|
|
<div class=example>
|
|
<p>For example, if the user enters the HTML file upload control from the
|
|
left, a mouseover event is generated for the shadow text field. Because
|
|
this event also constitutes a mouseover of the file control itself, the
|
|
event is retargeted when it flows across shadow scopes. If the user then
|
|
moves the mouse from the text field to the button, a mouseout is
|
|
generated for the text field, followed by a mouseover of the button.</p>
|
|
|
|
<p>Since neither of these events constitutes a mouseover or mouseout of
|
|
the file control itself, the events are not allowed to flow to the file
|
|
control. If the user continues moving to the right and leaves the
|
|
button, then the mouseout generated will be retargeted, since the file
|
|
control will also have been exited.</p>
|
|
</div>
|
|
|
|
<h3 id=event3><span class=secno>6.12. </span><dfn id=event14>Event
|
|
Handlers Implemented in ECMAScript</dfn></h3>
|
|
|
|
<p>When a script of a <code><a href="#handler0">handler</a></code> element
|
|
implemented in ECMAScript is executed the user agent must set the
|
|
<code>this</code> value to the <a href="#internal">internal object</a>
|
|
part of the implementation object of the binding with which the <code><a
|
|
href="#handler0">handler</a></code> element is associated. The script
|
|
must be executed as a function body with one argument, called
|
|
<code>event</code>, which is a reference to the <code>Event</code> object
|
|
representing the event. The script must be compiled and executed each
|
|
time it is accessed, so that any dynamic changes to the event handler
|
|
code in the binding document take effect.</p>
|
|
|
|
<h2 id=dom-interfaces><span class=secno>7. </span><dfn
|
|
id=dom-interfaces1>DOM Interfaces</dfn></h2>
|
|
|
|
<p>XBL introduces a few XBL-specific interfaces.</p>
|
|
|
|
<h3 id=the-documentxbl><span class=secno>7.1. </span>The <code><a
|
|
href="#documentxbl">DocumentXBL</a></code> Interface</h3>
|
|
|
|
<p>The <code><a href="#documentxbl">DocumentXBL</a></code> interface
|
|
contains methods for loading and obtaining binding documents. The
|
|
interface is implemented by DOM documents that support having their
|
|
elements bound by XBL.</p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition
|
|
|
|
<dd>
|
|
<pre class=idl>interface <dfn id=documentxbl>DocumentXBL</dfn> {
|
|
readonly attribute NamedNodeMap <a href="#bindingdocuments">bindingDocuments</a>;
|
|
Document <a href="#loadbindingdocument">loadBindingDocument</a>(in DOMString documentURI);
|
|
};</pre>
|
|
|
|
<dt>Attributes
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn id=bindingdocuments><code
|
|
class=attribute-name>bindingDocuments</code></dfn> of type <code
|
|
class=dom>NamedNodeMap</code>, readonly
|
|
|
|
<dd>The <code><a href="#bindingdocuments">bindingDocuments</a></code>
|
|
attribute must return a <code>NamedNodeMap</code> of all the binding
|
|
documents loaded by the document. Documents are referenced using their
|
|
URIs as the node names, with null namespaces. The
|
|
<code>NamedNodeMap</code> must be live, and must raise
|
|
<code>NO_MODIFICATION_ALLOWED_ERR</code> on any attempts at
|
|
modification or deletion.
|
|
</dl>
|
|
|
|
<dt>Methods
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn id=loadbindingdocument><code
|
|
class=method-name>loadBindingDocument</code></dfn>
|
|
|
|
<dd>
|
|
<p>The <code><a
|
|
href="#loadbindingdocument">loadBindingDocument</a></code> method
|
|
must synchronously load the specified binding document (unless it has
|
|
<a href="#loading5" title="loading external resources">already been
|
|
loaded</a>), as well as any binding documents that are required by
|
|
that binding document due to <a href="#extends"
|
|
title=attr-binding-extends>explicit inheritance</a>, and any bindings
|
|
defined by that document must be applied to matching elements in the
|
|
document that corresponds to this <code><a
|
|
href="#documentxbl">DocumentXBL</a></code> object. The method must
|
|
then return the binding document's <code>Document</code> object.
|
|
(See: <a href="#binding17">binding attachment and detachment</a>.) If
|
|
the load succeeded, it is also added to the <code><a
|
|
href="#bindingdocuments">bindingDocuments</a></code> attribute. If
|
|
the load fails, this method must return null.</p>
|
|
|
|
<dl>
|
|
<dt>Parameters
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class=parameter-name>documentURI</code> of type <code
|
|
class=dom>DOMString</code>
|
|
|
|
<dd>The <a href="#attributes24">URI</a> of a binding document.
|
|
</dl>
|
|
|
|
<dt>Return Value
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code>Document</code>
|
|
|
|
<dd>The return value of <code><a
|
|
href="#loadbindingdocument">loadBindingDocument()</a></code> is
|
|
the <code>Document</code> object of the binding document that was
|
|
loaded, or <code>null</code> if the load failed.
|
|
</dl>
|
|
|
|
<dt>No Exceptions
|
|
</dl>
|
|
</dl>
|
|
</dl>
|
|
|
|
<h3 id=the-elementxbl><span class=secno>7.2. </span>The <code><a
|
|
href="#elementxbl">ElementXBL</a></code> Interface</h3>
|
|
|
|
<p>The <code><a href="#elementxbl">ElementXBL</a></code> interface
|
|
contains methods for adding or removing bindings from an element. The
|
|
interface is implemented by all <code>Element</code> nodes (regardless of
|
|
whether they are currently involved with any XBL processing) and may be
|
|
obtained using binding-specific casting methods on an
|
|
<code>Element</code> interface.</p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition
|
|
|
|
<dd>
|
|
<pre class=idl>interface <dfn id=elementxbl>ElementXBL</dfn> {
|
|
readonly attribute XBLImplementationList <a href="#xblimplementations">xblImplementations</a>;
|
|
void <a href="#addbinding">addBinding</a>(in DOMString bindingURI);
|
|
void <a href="#removebinding">removeBinding</a>(in DOMString bindingURI);
|
|
boolean <a href="#hasbinding">hasBinding</a>(in DOMString bindingURI);
|
|
};</pre>
|
|
|
|
<dt>Attributes
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code><a href="#xblimplementations">xblImplementations</a></code>
|
|
of type <code><a
|
|
href="#xblimplementationlist">XBLImplementationList</a></code>,
|
|
readonly
|
|
|
|
<dd>See <a href="#binding23">binding implementations</a>.
|
|
</dl>
|
|
|
|
<dt>Methods
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn id=addbinding><code class=method-name>addBinding</code></dfn>
|
|
|
|
<dd> The <code><a href="#addbinding">addBinding</a></code> method must
|
|
attach the specified binding (and any bindings that the binding
|
|
inherits from) to the element. This call is not necessarily
|
|
synchronous. The binding may not be attached yet when the call
|
|
completes.
|
|
<dl>
|
|
<dt>Parameters
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class=parameter-name>bindingURI</code> of type
|
|
<code>DOMString</code>
|
|
|
|
<dd>A <a href="#attributes24">URI</a> that specifies the location
|
|
of a specific binding to attach.
|
|
</dl>
|
|
|
|
<dt>No Return Value
|
|
|
|
<dt>Exceptions
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code>HIERARCHY_REQUEST_ERR</code>
|
|
|
|
<dd>This exception must be raised if the node is not an element.
|
|
</dl>
|
|
</dl>
|
|
|
|
<dt><dfn id=removebinding><code
|
|
class=method-name>removeBinding</code></dfn>
|
|
|
|
<dd> The <code><a href="#removebinding">removeBinding</a></code> method
|
|
must detach the specified binding (and any bindings that the binding
|
|
inherits from explicitly using the <code>extends</code> attribute)
|
|
from the element. This method can only detach bindings that were
|
|
attached using <code><a href="#addbinding">addBinding</a></code>. If
|
|
the binding in question is not attached to this element (or was
|
|
attached through another attachment mechanism) then the method must do
|
|
nothing.
|
|
<dl>
|
|
<dt>Parameters
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class=parameter-name>bindingURI</code> of type
|
|
<code>DOMString</code>
|
|
|
|
<dd>A <a href="#attributes24">URI</a> that specifies the location
|
|
of a specific binding to detach.
|
|
</dl>
|
|
|
|
<dt>No Return Value
|
|
|
|
<dt>No Exceptions
|
|
</dl>
|
|
|
|
<dt><dfn id=hasbinding><code class=method-name>hasBinding</code></dfn>
|
|
|
|
<dd>
|
|
<p>The <code><a href="#hasbinding">hasBinding</a></code> method must
|
|
check the bindings applied to the element and compares each binding's
|
|
URI with the parameter passed. If any of the bindings matches the
|
|
specified URI, then the method must return true, otherwise it must
|
|
return false. This can be used to check if an element has been bound
|
|
to a particular binding in in order to ensure that the expected
|
|
methods and attributes are available.</p>
|
|
|
|
<p>Any bindings attached to the element (including, e.g., those
|
|
attached using CSS) are examined by this method.</p>
|
|
|
|
<p class=example>For example widgets may walk up their ancestors
|
|
looking for an element that has been bound to a form-container
|
|
binding in order to locate their scope (so that radio buttons may
|
|
properly be mutually exclusive, or so that a submit button can
|
|
properly submit a form).</p>
|
|
|
|
<dl>
|
|
<dt>Parameters
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class=parameter-name>bindingURI</code> of type
|
|
<code>DOMString</code>
|
|
|
|
<dd>A <a href="#attributes24">URI</a> that specifies the location
|
|
of a specific binding for which to look.
|
|
</dl>
|
|
|
|
<dt>Returns
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code>boolean</code>
|
|
|
|
<dd><code>true</code> if any of the bindings match the parameter,
|
|
<code>false</code> otherwise.
|
|
</dl>
|
|
|
|
<dt>No Exceptions
|
|
</dl>
|
|
</dl>
|
|
</dl>
|
|
|
|
<h4 id=scoping><span class=secno>7.2.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 <a href="#shadow9">shadow scope</a>. Bound elements
|
|
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>childNodes</code> list for the bound element, nor is it
|
|
accessible using <code>firstChild</code>/<code>nextSibling</code> to
|
|
iterate over the children of the bound element.</p>
|
|
|
|
<p>DOM methods that can be invoked on elements (e.g.,
|
|
<code>getElementsByTagName()</code>) will only see nodes that are in the
|
|
same shadow scope. Methods invoked on the document (e.g., <code
|
|
title="">getElementById</code>) only see nodes that are not in shadow
|
|
trees.</p>
|
|
|
|
<p>On shadow content nodes, <code>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 (the cloned <code><a
|
|
href="#template0">template</a></code> elements) cannot be inserted into a
|
|
document. Any attempt to do so must raise a
|
|
<code>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 mighty confusing
|
|
for things like getComputedStyle() --></p>
|
|
|
|
<p>Manipulating the DOM of a shadow tree (<code><a
|
|
href="#content0">content</a></code> elements being moved about or even
|
|
removed altogether, <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> attributes being attached and
|
|
modified, etc) must immediately cause the <a href="#final0">final
|
|
flattened tree</a> to be updated.</p>
|
|
|
|
<p>Changes to namespace prefix definitions in the shadow tree that affect
|
|
<a href="#qname" title=QName>QNames</a> used in <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> attributes may have their effects
|
|
applied immediately but this is not required.</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>
|
|
|
|
<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 <a
|
|
href="#final0">final flattened tree</a>).</p>
|
|
|
|
<h3 id=the-xblcontentelement><span class=secno>7.3. </span>The <code><a
|
|
href="#xblcontentelement">XBLContentElement</a></code> Interface</h3>
|
|
|
|
<p>The <code><a href="#xblcontentelement">XBLContentElement</a></code>
|
|
interface is implemented by <code><a href="#content0">content</a></code>
|
|
elements in the XBL namespace (regardless of whether they are <a
|
|
href="#in-error">in error</a> or not).</p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition
|
|
|
|
<dd>
|
|
<pre
|
|
class=idl>interface <dfn id=xblcontentelement>XBLContentElement</dfn> : Element {
|
|
readonly attribute <span>NodeList</span> <a href="#xblchildnodes">xblChildNodes</a>;
|
|
void <a href="#setinsertionpoint">setInsertionPoint</a>(in Node child);
|
|
};</pre>
|
|
|
|
<dt>Attributes
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn id=xblchildnodes><code>xblChildNodes</code></dfn> of type
|
|
<code>NodeList</code>, readonly
|
|
|
|
<dd>
|
|
<p>The <code><a href="#xblchildnodes">xblChildNodes</a></code>
|
|
attribute must return a <code>NodeList</code> containing a live list
|
|
of all the nodes that are currently assigned to the <code><a
|
|
href="#content0">content</a></code> element.</p>
|
|
|
|
<p class=note>A node can be assigned to multiple <code><a
|
|
href="#content0">content</a></code> elements simultaneously, in the
|
|
case of bound elements inside shadow trees.</p>
|
|
|
|
<p>Exception: if the <code><a href="#content0">content</a></code>
|
|
element is not in a <a href="#shadow7">shadow tree</a>, then this
|
|
attribute must return null.</p>
|
|
</dl>
|
|
|
|
<dt>Methods
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn id=setinsertionpoint><code>setInsertionPoint</code></dfn>
|
|
|
|
<dd>
|
|
<p>The <code><a href="#setinsertionpoint">setInsertionPoint</a></code>
|
|
method perform the following steps.</p>
|
|
|
|
<ol>
|
|
<li>Let <var title="">e</var> be the bound element for which the user
|
|
agent generated the shadow tree in which the given <code><a
|
|
href="#content0">content</a></code> element finds itself. If there
|
|
is no such bound element (e.g. the <code><a
|
|
href="#content0">content</a></code> element has been removed from
|
|
its shadow tree), then the method must raise an
|
|
<code>INVALID_STATE_ERR</code> exception.
|
|
|
|
<li>Let <var title="">child</var> be the node that was given as an
|
|
argument to the method.
|
|
|
|
<li>The user agent must then check that the parent of <var
|
|
title="">child</var> is in fact <var title="">e</var>. If it is not,
|
|
then the method must raise an <code>HIERARCHY_REQUEST_ERR</code>
|
|
exception.
|
|
|
|
<li>The user agent must then check that either the <code><a
|
|
href="#content0">content</a></code> element has no <code
|
|
title=attr-content-includes><a href="#includes">includes</a></code>
|
|
attribute, or that <var title="">child</var> matches the selector
|
|
given in the <code><a href="#content0">content</a></code> element's
|
|
<code title=attr-content-includes><a
|
|
href="#includes">includes</a></code> attribute. If the attribute is
|
|
present but the element does not match the selector it specifies (or
|
|
if the selector is not syntactically correct), then the method must
|
|
raise an <code>TYPE_MISMATCH_ERR</code> exception.</li>
|
|
<!-- XXX
|
|
that one is stretching it -->
|
|
|
|
<li>Finally, the user agent must assign <var title="">child</var> to
|
|
the <code><a href="#content0">content</a></code> element, instead of
|
|
whatever previous <code><a href="#content0">content</a></code>
|
|
element it was assigned to, if any.
|
|
</ol>
|
|
|
|
<p>If a node is assigned, using the <code><a
|
|
href="#setinsertionpoint">setInsertionPoint</a></code> method, to a
|
|
<code><a href="#content0">content</a></code> element that is not
|
|
locked, then the element will only remain there until such time as
|
|
the user agent redistributes the bound element's explicit children.</p>
|
|
|
|
<p>See <a href="#processing2">processing <code>content</code>
|
|
elements</a>.</p>
|
|
|
|
<p class=note>The order of nodes assigned to a <code><a
|
|
href="#content0">content</a></code> element is always be the same as
|
|
the relative order of those nodes in the original core DOM.</p>
|
|
|
|
<dl>
|
|
<dt>Parameters
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class=parameter-name>child</code> of type
|
|
<code>Node</code>
|
|
|
|
<dd>The child of the bound element to assign to this <code><a
|
|
href="#content0">content</a></code> element.
|
|
</dl>
|
|
|
|
<dt>No Return Value
|
|
|
|
<dt>No Exceptions
|
|
</dl>
|
|
|
|
<div class=example>
|
|
<p>The following example implements a tabbed interface as a binding.
|
|
It creates a list of buttons to enable the user to access each of
|
|
the sections that the tab box contains, and then uses <code><a
|
|
href="#setinsertionpoint">setInsertionPoint()</a></code> to make the
|
|
selected tab panel appear.</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding>
|
|
<template>
|
|
<div id="tabs"/>
|
|
<div class="panel"><content id="current" locked="true"/></div>
|
|
<div class="hidden"><content id="not-current"/></div>
|
|
</template>
|
|
<implementation>
|
|
({
|
|
set current(section) {
|
|
if (this._current)
|
|
this.shadowTree.getElementById('not-current').setInsertionPoint(this._current);
|
|
this._current = section;
|
|
if (this._current)
|
|
this.shadowTree.getElementById('current').setInsertionPoint(this._current);
|
|
},
|
|
get current() {
|
|
return this._current;
|
|
},
|
|
xblBindingAttached: function() {
|
|
this.updateTabs();
|
|
this.current = this.boundElement.getElementsByTagName('section')[0];
|
|
},
|
|
clearTabs: function() {
|
|
with (this.shadowTree.getElementById('tabs'))
|
|
while (hasChildNodes())
|
|
removeChild(firstChild);
|
|
},
|
|
addTabFor: function(section) {
|
|
var tab = document.createElementNS('http://www.w3.org/ns/xbl', 'div');
|
|
tab.appendChild(document.createTextNode(section.getAttribute('title')););
|
|
tab.addEventListener('click', function (_this) { return function (event) {
|
|
var tabs = this.shadowTree.getElementByID('tabs').getElementsByTagName('div');
|
|
for (var i = 0; i &lt; tabs.length; ++i)
|
|
tabs[i].setAttribute('class', '');
|
|
_this.current = section;
|
|
event.target.setAttribute('class', 'selected');
|
|
event.preventDefault();
|
|
} }(this), false);
|
|
this.shadowTree.getElementById('tabs').appendChild(tab);
|
|
},
|
|
updateTabs: function() {
|
|
this.clearTabs();
|
|
var sections = this.boundElement.getElementsByTagName('section');
|
|
for (var i = 0; i &lt; sections.length; ++i)
|
|
this.addTabFor(sections[i]);
|
|
},
|
|
})
|
|
</implementation>
|
|
<resources>
|
|
<style>
|
|
#tabs > div { /* style for tabs */ }
|
|
#tabs > div.selected { /* style for selected tab */ }
|
|
.panel { /* style for panel */ }
|
|
.hidden { display: none; }
|
|
</style>
|
|
</resources>
|
|
</binding>
|
|
</xbl></pre>
|
|
|
|
<p>This binding could be applied to any element that has
|
|
<code>section</code> elements as children, each <code>section</code>
|
|
element having its title given in its <code>title</code> attribute.</p>
|
|
|
|
<p>The binding implemented above doesn't dynamically update when the
|
|
DOM is changed, a full implementation would probably want to listen
|
|
to mutation events to catch attribute changes and insertions and
|
|
removals of the panels.</p>
|
|
</div>
|
|
</dl>
|
|
</dl>
|
|
|
|
<h3 id=the-xbltemplateelement><span class=secno>7.4. </span>The <code><a
|
|
href="#xbltemplateelement">XBLTemplateElement</a></code> Interface</h3>
|
|
|
|
<p>The <code><a href="#xbltemplateelement">XBLTemplateElement</a></code>
|
|
interface is implemented by <code><a
|
|
href="#template0">template</a></code> elements that are in the XBL
|
|
namespace (regardless of whether they are <a href="#in-error">in
|
|
error</a> or not).</p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition
|
|
|
|
<dd>
|
|
<pre class=idl>
|
|
interface <dfn id=xbltemplateelement>XBLTemplateElement</dfn> : Element {
|
|
Element <a href="#getelementbyid">getElementById</a>(in DOMString elementId);
|
|
};
|
|
</pre>
|
|
|
|
<dt>Attributes
|
|
|
|
<dd>No Attributes
|
|
|
|
<dt>Methods
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><dfn class=method-name
|
|
id=getelementbyid><code>getElementById</code></dfn>
|
|
|
|
<dd>
|
|
<p class=note>This method is modeled after the method of the same name
|
|
defined by <a href="#refsDOM3CORE">[DOM3CORE]</a> on the
|
|
<code>Document</code> interface.</p>
|
|
|
|
<p>This method must return an <code>Element</code> that has an ID
|
|
attribute with the given value, and that is a descendant of the
|
|
<code><a href="#template0">template</a></code> element on which it is
|
|
invoked. If more than one such element exists, which one is returned
|
|
is undefined. If no such element exists, this returns
|
|
<code>null</code>.</p>
|
|
|
|
<p class=note>Attributes with the name "ID" or "id" are not of type ID
|
|
unless so defined. For example, attributes with the name "id" on
|
|
elements that are from the XHTML, MathML and XBL namespaces are
|
|
defined to be of type ID by their respective specifications.</p>
|
|
|
|
<dl>
|
|
<dt>Parameters
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class=parameter-name>elementId</code> of type
|
|
<code>DOMString</code>
|
|
|
|
<dd>The unique <code>id</code> value for an element.
|
|
</dl>
|
|
|
|
<dt>Returns
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code>Element</code>
|
|
|
|
<dd> The matching element or null if there is none.
|
|
</dl>
|
|
|
|
<dt>No Exceptions
|
|
</dl>
|
|
</dl>
|
|
</dl>
|
|
|
|
<h3 id=the-eventxbl><span class=secno>7.5. </span>The <code><a
|
|
href="#eventxbl">EventXBL</a></code> Interface</h3>
|
|
|
|
<p>Objects that implement the <code>Event</code> interface must also
|
|
implement the <code><a href="#eventxbl">EventXBL</a></code> interface. <a
|
|
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
|
|
|
|
<dl>
|
|
<dt>IDL Definition
|
|
|
|
<dd>
|
|
<pre class=idl>interface <dfn id=eventxbl>EventXBL</dfn> {
|
|
readonly attribute boolean <a href="#trusted0" title=event-trusted>trusted</a>;
|
|
};</pre>
|
|
</dl>
|
|
|
|
<p>The <dfn id=trusted0 title=event-trusted><code>trusted</code></dfn>
|
|
attribute must return true if the user agent dispatched the event (e.g.
|
|
in response to user action), and false otherwise (e.g. if an author
|
|
script dispatched a synthetic event). Events fired by the user agent in
|
|
response to untrusted events must themselves be untrusted.</p>
|
|
<!--XXX
|
|
<h2>Widget Bindings</h2>
|
|
|
|
<p class="big-issue">(to be completed)</p>
|
|
|
|
<p>A <dfn>widget binding</dfn> is a binding that extends either
|
|
the <span class= "css">widget</span> base binding or any of the
|
|
other <dfn>predefined base bindings</dfn> for widgets listed
|
|
below.</p>
|
|
|
|
<h3 id="base-bindings">Predefined Base Bindings</h3>
|
|
|
|
<p>The following bindings have predefined meaning.</p>
|
|
|
|
<dl>
|
|
|
|
<dt>widget</dt>
|
|
|
|
<dd>Implements the <code>value</code> property.</dd>
|
|
|
|
<dt>native-checkbox</dt>
|
|
|
|
<dd>...</dd>
|
|
|
|
<dt>simple-checkbox</dt>
|
|
|
|
<dd>...</dd>
|
|
|
|
<dt>widget-scope</dt>
|
|
|
|
<dd>Implements the <code>submit</code> and <code>reset</code>
|
|
methods.</dd>
|
|
|
|
</dl>
|
|
-->
|
|
|
|
<h2 id=resources><span class=secno>8. </span>Resources</h2>
|
|
|
|
<h3 id=loading><span class=secno>8.1. </span><dfn id=loading5>Loading
|
|
External Resources</dfn></h3>
|
|
|
|
<h4 id=binding5><span class=secno>8.1.1. </span>Binding Documents</h4>
|
|
|
|
<p>Several features in XBL allow binding documents to be loaded.</p>
|
|
|
|
<p>When the specification says that a binding document must be loaded
|
|
<em>unless it has already been loaded</em>, then references to the same
|
|
binding document (even if they are somewhat indirect, for example via
|
|
HTTP redirects) must result in the same <code>Document</code> instance
|
|
being reused, or shared.</p>
|
|
|
|
<p>To determine if two binding documents are the same, their final base
|
|
URIs (after all redirects) are compared.</p>
|
|
|
|
<div class=example>
|
|
<p>A <a href="#binding15">binding document</a> A contains a <code><a
|
|
href="#binding16">binding</a></code> element that refers to a second
|
|
binding document X. A new DOM <code>Document</code> instance is created
|
|
to represent that instance and the relevant bindings are used.</p>
|
|
|
|
<p>Now assume RX is a resource that redirects to resource X using the
|
|
HTTP 301 redirection mechanism. A second <code><a
|
|
href="#binding16">binding</a></code> element in the binding document A
|
|
refers to resource RX. When that resource is being loaded, the redirect
|
|
to X would be discovered, and therefore instead of creating a new
|
|
<code>Document</code>, the existing one is reused.</p>
|
|
</div>
|
|
|
|
<p>Such sharing of binding documents must be limited to binding documents
|
|
loaded by a document, its binding documents, its scripts, and its style
|
|
sheets. Nested documents and images do not share binding documents with
|
|
each other or with their container document.</p>
|
|
|
|
<div class=example>
|
|
<p>For example, if a document uses a binding document, and its style
|
|
sheets use that binding document, the same binding document instance
|
|
will be used for both cases. However, if that document contains an
|
|
<code>iframe</code> whose document uses the same binding document, a new
|
|
instance will be used: the binding document instance from the outer
|
|
document is not reused.</p>
|
|
</div>
|
|
|
|
<p>Binding documents that are currently loading count as binding documents
|
|
that are already loaded for the purposes of this reuse mechanism.</p>
|
|
|
|
<h4 id=external><span class=secno>8.1.2. </span>External Resources</h4>
|
|
|
|
<p>When the specification simply says that the external resource must be
|
|
loaded, without giving any caveats regarding multiple accesses of the
|
|
same resource, then each reference must instantiate a new unique copy of
|
|
the document.</p>
|
|
|
|
<p class=example>For example, two <code><a href="#style2">style</a></code>
|
|
elements whose <code>src</code> attributes point to the same style sheet
|
|
must create two different <code>Stylesheet</code> instances, such that
|
|
mutating one does not affect the other.</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>
|
|
|
|
<h3 id=loading0><span class=secno>8.2. </span><dfn id=loading6>Loading and
|
|
Running Scripts</dfn></h3>
|
|
|
|
<p>Scripts in XBL may be found in <code><a
|
|
href="#script2">script</a></code>, <code><a
|
|
href="#implementation0">implementation</a></code>, and <code><a
|
|
href="#handler0">handler</a></code> elements, or in resources that those
|
|
elements point to.</p>
|
|
|
|
<p>In the case of <code title=attr-script-src><a
|
|
href="#src2">script</a></code> and <code title=attr-implementation-src><a
|
|
href="#src">implementation</a></code> elements, if a <code
|
|
title="">src</code> attribute is present then the contents of the element
|
|
must be <span title="">ignored</span> (even if fetching the specified URI
|
|
fails).</p>
|
|
|
|
<p>The rules for parsing the scripts are the same for all three elements,
|
|
but depend on the scripting language specified by the author.</p>
|
|
|
|
<p>For non-XML languages, if the content is inline, UAs must concatenate
|
|
all the textual contents of text and CDATA child nodes, and must <a
|
|
href="#ignoring">ignore</a> any other, non-text nodes (such as elements
|
|
and comments) along with all their children. All descendant elements must
|
|
be processed, though, according to their semantics, before the XBL script
|
|
block itself is executed.</p>
|
|
|
|
<div class=example>
|
|
<p>For example, in an XHTML-aware and ECMAScript-capable user agent, the
|
|
following ridiculous code would cause the alerts to appear in the order
|
|
One, Two, Three, and would set the <code title="">test</code> property
|
|
in the binding document's global script scope to the string
|
|
"undefinedABC":</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<!-- WARNING: THIS EXAMPLE IS NON-CONFORMING -->
|
|
<script>
|
|
alert('Two');
|
|
test += "B";
|
|
<script xmlns="http://www.w3.org/1999/xhtml">
|
|
alert('One');
|
|
test += "A";
|
|
</script>
|
|
alert('Three');
|
|
test += "C";
|
|
</script>
|
|
</xbl></pre>
|
|
|
|
<p>Authors must not ever consider doing this. The above is invalid.</p>
|
|
</div>
|
|
|
|
<p>For XML-based scripting languages, handling of unknown elements and
|
|
other unexpected nodes must be defined by that language.</p>
|
|
|
|
<p>If the content is not inline, then when the element is evaluated, the
|
|
resource specified by the <code title="">src</code> attribute must be
|
|
fetched. For <code><a href="#script2">script</a></code> elements, while
|
|
an external script is being fetched, any pending <a href="#binding19"
|
|
title="Binding Attachment Model">binding attachments</a> from the same
|
|
binding document must block, as must the evaluation of any further
|
|
<code><a href="#script2">script</a></code> blocks. For <code><a
|
|
href="#implementation0">implementation</a></code> elements, while the
|
|
external script is being fetched, the <a href="#binding19" title="Binding
|
|
Attachment Model">attachment</a> of that binding must block. If the
|
|
file's Content-Type (or equivalent for non-HTTP protocols), if any, is
|
|
not of the type <a href="#script-type"
|
|
title=attr-xbl-script-type>specified</a> on the <code><a
|
|
href="#xbl0">xbl</a></code> element, then the script must be ignored.
|
|
Otherwise, the contents of that file must be used directly, as specified
|
|
by the relevant language specification.</p>
|
|
|
|
<h4 id=xforms><span class=secno>8.2.1. </span>XForms Actions</h4>
|
|
|
|
<p><em>This section is only normative for implementations that support
|
|
XForms.</em></p>
|
|
|
|
<p>It is theoretically possible to use XForms Actions as the scripting
|
|
language in XBL <a href="#refsXFORMS">[XFORMS]</a>. The MIME type that
|
|
indicates this scripting language is tentatively defined to be <code
|
|
class=mimetype>application/x-xforms-actions+xml</code>. XBL elements have
|
|
the following semantics when used with XForms Actions:</p>
|
|
|
|
<dl>
|
|
<dt><code><a href="#script2">script</a></code> elements
|
|
|
|
<dd>These are exactly equivalent to <code>xforms:action</code> elements
|
|
that trigger immediately upon being added to the document.
|
|
|
|
<dt><code><a href="#handler0">handler</a></code> elements
|
|
|
|
<dd>These are exactly equivalent to <code>xforms:action</code> elements
|
|
that trigger when the appropriate event on the bound element is
|
|
detected.
|
|
|
|
<dt><code><a href="#implementation0">implementation</a></code> elements
|
|
|
|
<dd>Since XForms Actions cannot declare new interfaces, <code><a
|
|
href="#implementation0">implementation</a></code> elements when the
|
|
script language is set to <code
|
|
class=mimetype>application/x-xforms-actions+xml</code> are <a
|
|
href="#in-error">in error</a> and the UA must <a
|
|
href="#ignoring">ignore</a> them, by treating <code><a
|
|
href="#implementation0">implementation</a></code> elements like
|
|
<code>xforms:action</code> elements that are not bound to any event.
|
|
</dl>
|
|
|
|
<h4 id=scripting><span class=secno>8.2.2. </span>Scripting Model</h4>
|
|
|
|
<p>Each document that runs script (including bound documents and binding
|
|
documents) has a <code>DocumentWindow</code> object, a
|
|
<code>Window</code> object, a global script scope, and a security
|
|
context. In ECMAScript, the global script scope and the
|
|
<code>Window</code> object are one and the same.</p>
|
|
|
|
<p class=note>This above paragraph is a vague description of the Web's
|
|
de-facto scripting model. This specification depends on that model, but
|
|
it hasn't yet been specified in detail. This specification will be
|
|
updated when a suitable description is available.</p>
|
|
|
|
<p>Script must always be executed in the context of the global script
|
|
scope of the document specified by the script's element's
|
|
<code>ownerDocument</code> DOM attribute. This implies that scripts from
|
|
different bindings in the same binding document 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>
|
|
|
|
<p>A binding document must inherit the security context of the document to
|
|
which it is bound, not the security context of the domain from which it
|
|
was fetched<!--, unless the binding is marked
|
|
as <em>secure</em>. Secure bindings must use separate security
|
|
contexts appropriate for those given bindings-->.</p>
|
|
|
|
<p>Scripting and security contexts are (or will be) described in the HTML5
|
|
specification. <a href="#refsHTML5">[HTML5]</a></p>
|
|
|
|
<p>In binding documents, the <code>location</code> and
|
|
<code>history</code> properties of the <code>Window</code> object, and
|
|
the <code>location</code> and <code>cookie</code> properties of the
|
|
<code>DocumentWindow</code> object, must return null, and any methods
|
|
that are defined in terms of the browsing context's session history must
|
|
do nothing. <a href="#refsHTML5">[HTML5]</a></p>
|
|
|
|
<p>User agents should implement a security mechanism such as the proposed
|
|
<code><?access-control?></code> PI to prevent unauthorized
|
|
cross-domain access. <a href="#refsACCESSCONTROL">[ACCESSCONTROL]</a></p>
|
|
|
|
<h3 id=loading1><span class=secno>8.3. </span><dfn id=loading7>Loading
|
|
Style Sheets</dfn></h3>
|
|
|
|
<p>XBL <code><a href="#style2">style</a></code> elements describe the
|
|
style sheets that apply to bindings.</p>
|
|
|
|
<p>If a <code><a href="#style2">style</a></code> element's <code
|
|
title=attr-style-src><a href="#src0">src</a></code> attribute is present,
|
|
the contents of the element must be <a href="#ignoring"
|
|
title=ignore>ignored</a> (even if fetching the specified URI failed).
|
|
Otherwise, it is the element's contents that give the style sheet.</p>
|
|
|
|
<p>Wherever the style is found, the rules for parsing it are the same, but
|
|
depend on the language specified by the author.</p>
|
|
|
|
<p>For non-XML styling languages, if the content is inline, UAs must
|
|
concatenate all the textual contents of text and CDATA child nodes, and
|
|
the UA must <a href="#ignoring">ignore</a> any other, non-text nodes
|
|
(such as elements and comments) along with all their children. All
|
|
descendant elements must be processed, though, according to their
|
|
semantics, before the XBL style block itself is parsed. A style element
|
|
labeled as containing a style sheet in a non-XML language yet containing
|
|
element nodes is <a href="#in-error">in error</a>.</p>
|
|
|
|
<div class=example>
|
|
<p>For example, in an XHTML-aware and ECMAScript-capable user agent, the
|
|
rather dubious code below would result in a binding that enclosed the
|
|
bound element's children in a green box, not a red one:</p>
|
|
|
|
<pre><xbl xmlns="http://www.w3.org/ns/xbl">
|
|
<binding>
|
|
<template>
|
|
<div>
|
|
<content/>
|
|
</div>
|
|
</template>
|
|
<resources>
|
|
<style id="test">
|
|
div { background: red; }
|
|
<script xmlns="http://www.w3.org/1999/xhtml">
|
|
document.getElementById('test').firstChild.data = "div { background: green; }";
|
|
</script>
|
|
<p xmlns="http://www.w3.org/1999/xhtml">
|
|
div { border: red solid; }
|
|
This will either be ignored by the XBL user agent, or will cause
|
|
it to abort all processing altogether, as this text node is not a
|
|
child of the style element.
|
|
</p>
|
|
</style>
|
|
</resources>
|
|
</binding>
|
|
</xbl></pre>
|
|
</div>
|
|
|
|
<p>For XML-based styling languages, handling of unknown elements and other
|
|
unexpected nodes must be defined by that language.</p>
|
|
|
|
<p>If the content was in another resource, and the Content-Type (or
|
|
equivalent for non-HTTP protocols), if any, was of the type specified on
|
|
the <code><a href="#xbl0">xbl</a></code> element (or implied by its
|
|
absence), then the contents of that file must be used directly, as
|
|
specified by the relevant language specification. Otherwise, the <code><a
|
|
href="#style2">style</a></code> element doesn't provide any styling. The
|
|
<code title=attr-style-src><a href="#src0">src</a></code> attribute must
|
|
only be examined once all of the element's children have been processed
|
|
(if any).</p>
|
|
|
|
<h3 id=interpretation><span class=secno>8.4. </span><dfn
|
|
id=interpretation1>Interpretation of URIs to XBL bindings</dfn></h3>
|
|
|
|
<p>XBL attachment mechanisms use a URI to specify which binding to attach
|
|
to the designated element.</p>
|
|
|
|
<div class=example>
|
|
<p>For example:</p>
|
|
|
|
<pre>my|foo {
|
|
binding: url("<strong>http://www.example.org/bindings.xml#fooBinding</strong>");
|
|
}</pre>
|
|
</div>
|
|
|
|
<p>This section defines how these URIs, which are used in the argument to
|
|
the <code><a href="#addbinding">addBinding()</a></code> method, and in
|
|
the value of the '<code title="binding property"><a
|
|
href="#binding18">binding</a></code>' property, are to be interpreted.</p>
|
|
|
|
<p>The URI specifies a particular <a href="#binding15">binding
|
|
document</a> (an <a href="#xbl-document">XBL document</a> or <a
|
|
href="#non-xbl">non-XBL document</a> containing one or more XBL
|
|
subtrees). The user agent must fetch this resource (unless it has <a
|
|
href="#loading5" title="loading external resources">already been
|
|
loaded</a>).</p>
|
|
|
|
<p>If the URI contains a fragment identifier, then it must be processed as
|
|
described in the relevant MIME type definition. The element targeted by
|
|
the fragment identifier must be a <code><a
|
|
href="#binding16">binding</a></code> element 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; if these
|
|
conditions are not met then the URI is <a href="#in-error">in error</a>.</p>
|
|
|
|
<p class=example>For example, if the binding document is sent as
|
|
<code>application/xhtml+xml</code>, and the fragment identifier matches a
|
|
<code><a href="#binding16">binding</a></code> element's <code
|
|
title=attr-id><a href="#id13">id</a></code> attribute, then that is the
|
|
binding that is attached.</p>
|
|
|
|
<p>If there is no fragment identifier and the URI points to an XBL
|
|
document (not a <a href="#non-xbl">non-XBL document</a>) then the first
|
|
<code><a href="#binding16">binding</a></code> element in the binding
|
|
document that is a child of the root <code><a href="#xbl0">xbl</a></code>
|
|
element is selected. Otherwise, the URI does not point to a <a
|
|
href="#correct">correct</a> binding and is <a href="#in-error">in
|
|
error</a>.</p>
|
|
|
|
<p>When an attachment mechanism uses a URI that is <a href="#in-error">in
|
|
error</a> (as per the last two paragraphs), then the user agent must act
|
|
as if the attachment mechanism had not specified that binding.</p>
|
|
|
|
<p>Otherwise, the specified binding is attached to the element, as
|
|
described for the relevant attachment mechanism.</p>
|
|
|
|
<h2 id=summaries><span class=secno>9. </span>Summaries of Elements,
|
|
Attributes, and Events</h2>
|
|
|
|
<h3 id=elements><span class=secno>9.1. </span>Elements and Attributes</h3>
|
|
|
|
<p><em>This section is non-normative.</em></p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Element
|
|
|
|
<th>Attributes
|
|
|
|
<th>Content Model
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td><code><a href="#xbl0">xbl</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-xbl-script-type><a
|
|
href="#script-type">script-type</a></code>
|
|
|
|
<li><code title=attr-xbl-style-type><a
|
|
href="#style-type">style-type</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#binding16">binding</a></code>
|
|
|
|
<li><code><a href="#script2">script</a></code>
|
|
|
|
<li>Non-XBL elements
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#binding16">binding</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-binding-extends><a
|
|
href="#extends">extends</a></code>
|
|
|
|
<li><code title=attr-binding-element><a
|
|
href="#element">element</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#implementation0">implementation</a></code>
|
|
|
|
<li><code><a href="#template0">template</a></code>
|
|
|
|
<li><code><a href="#handlers0">handlers</a></code>
|
|
|
|
<li><code><a href="#resources1">resources</a></code>
|
|
|
|
<li>Non-XBL elements
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#implementation0">implementation</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-implementation-src><a href="#src">src</a></code>
|
|
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li>Script
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#template0">template</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-template-apply-author-sheets><a
|
|
href="#apply-author-sheets">apply-author-sheets</a></code>
|
|
|
|
<li><code title=attr-template-allow-selectors-through><a
|
|
href="#allow-selectors-through">allow-selectors-through</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#div0">div</a></code>
|
|
|
|
<li><code><a href="#content0">content</a></code>
|
|
|
|
<li><code><a href="#inherited0">inherited</a></code>
|
|
|
|
<li>Non-XBL elements, optionally with <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> and <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attributes
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#content0">content</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-content-includes><a
|
|
href="#includes">includes</a></code>
|
|
|
|
<li><code title=attr-content-apply-binding-sheets><a
|
|
href="#apply-binding-sheets">apply-author-sheets</a></code>
|
|
|
|
<li><code title=attr-content-locked><a
|
|
href="#locked">locked</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#div0">div</a></code>
|
|
|
|
<li><code><a href="#inherited0">inherited</a></code>
|
|
|
|
<li>Non-XBL elements, optionally with <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> and <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attributes
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#inherited0">inherited</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#div0">div</a></code>
|
|
|
|
<li><code><a href="#content0">content</a></code>
|
|
|
|
<li>Non-XBL elements, optionally with <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> and <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attributes
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#div0">div</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-div-class><a href="#class">class</a></code>
|
|
|
|
<li><code title=attr-div-state><a href="#state">state</a></code>
|
|
|
|
<li><code title=attr-div-title><a href="#title">title</a></code>
|
|
|
|
<li><code title=attr-attr><a href="#xblattr0">xbl:attr</a></code>
|
|
|
|
<li><code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#div0">div</a></code>
|
|
|
|
<li><code><a href="#content0">content</a></code>
|
|
|
|
<li><code><a href="#inherited0">inherited</a></code>
|
|
|
|
<li>Non-XBL elements, optionally with <code title=attr-attr><a
|
|
href="#xblattr0">xbl:attr</a></code> and <code title=attr-pseudo><a
|
|
href="#xblpseudo0">xbl:pseudo</a></code> attributes
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#handlers0">handlers</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#handler0">handler</a></code>
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#handler0">handler</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-handler-event><a href="#event9">event</a></code>
|
|
|
|
|
|
<li><code title=attr-handler-phase><a href="#phase">phase</a></code>
|
|
|
|
<li><code title=attr-handler-trusted><a
|
|
href="#trusted">trusted</a></code>
|
|
|
|
<li><code title=attr-handler-propagate><a
|
|
href="#propagate">propagate</a></code>
|
|
|
|
<li><code title=attr-handler-default-action><a
|
|
href="#default-action">default-action</a></code>
|
|
|
|
<li><code title=attr-handler-button><a
|
|
href="#button">button</a></code>
|
|
|
|
<li><code title=attr-handler-click-count><a
|
|
href="#click-count">click-count</a></code>
|
|
|
|
<li><code title=attr-handler-modifiers><a
|
|
href="#modifiers1">modifiers</a></code>
|
|
|
|
<li><code title=attr-handler-key><a href="#key">key</a></code>
|
|
|
|
<li><code title=attr-handler-key-location><a
|
|
href="#key-location">key-location</a></code>
|
|
|
|
<li><code title=attr-handler-text><a href="#text">text</a></code>
|
|
|
|
<li><code title=attr-handler-prev-value><a
|
|
href="#prev-value">prev-value</a></code>
|
|
|
|
<li><code title=attr-handler-new-value><a
|
|
href="#new-value">new-value</a></code>
|
|
|
|
<li><code title=attr-handler-attr-name><a
|
|
href="#attr-name">attr-name</a></code>
|
|
|
|
<li><code title=attr-handler-attr-change><a
|
|
href="#attr-change">attr-change</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li>Script
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#resources1">resources</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code><a href="#style2">style</a></code>
|
|
|
|
<li><code><a href="#prefetch0">prefetch</a></code>
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#style2">style</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-style-media><a href="#media">media</a></code>
|
|
|
|
<li><code title=attr-style-src><a href="#src0">src</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li>Style
|
|
</ul>
|
|
|
|
<tr>
|
|
<td><code><a href="#prefetch0">prefetch</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-prefetch-src><a href="#src1">src</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
|
|
<tr>
|
|
<td><code><a href="#script2">script</a></code>
|
|
|
|
<td>
|
|
<ul>
|
|
<li><code title=attr-id><a href="#id13">id</a></code>
|
|
|
|
<li><code title=attr-script-src><a href="#src2">src</a></code>
|
|
</ul>
|
|
|
|
<td>
|
|
<ul>
|
|
<li>Script
|
|
</ul>
|
|
</table>
|
|
|
|
<h3 id=events><span class=secno>9.2. </span>Events</h3>
|
|
|
|
<p><em>This section is non-normative.</em></p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Event Name
|
|
|
|
<th>Interface
|
|
|
|
<th>Target when fired by UA
|
|
|
|
<th>Bubbles?
|
|
|
|
<th>Cancelable?
|
|
|
|
<th>Default Action
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td><code title=xbl-bound><a href="#xbl-bound">xbl-bound</a></code>
|
|
|
|
<td><code>Event</code>
|
|
|
|
<td>Bound element
|
|
|
|
<td>✓ Bubbles
|
|
|
|
<td>—
|
|
|
|
<td>None
|
|
|
|
<tr>
|
|
<td><code title=xbl-bindings-are-ready><a
|
|
href="#xbl-bindings-are-ready">xbl-bindings-are-ready</a></code>
|
|
|
|
<td><code>Event</code>
|
|
|
|
<td>Bound document's root element
|
|
|
|
<td>✓ Bubbles
|
|
|
|
<td>—
|
|
|
|
<td>None
|
|
</table>
|
|
|
|
<h3 id=implementations><span class=secno>9.3. </span>Implementations</h3>
|
|
|
|
<p><em>This section is non-normative.</em></p>
|
|
|
|
<p>The properties of the <a href="#internal">internal object</a> are:</p>
|
|
|
|
<ul class=brief>
|
|
<li><code><a href="#external1">external</a></code>
|
|
|
|
<li><code><a href="#boundelement">boundElement</a></code>
|
|
|
|
<li><code><a href="#shadowtree">shadowTree</a></code>
|
|
|
|
<li><code><a href="#basebinding">baseBinding</a></code>
|
|
</ul>
|
|
|
|
<p>The methods that binding implementations can support are:</p>
|
|
|
|
<ul class=brief>
|
|
<li><code><a href="#xblbindingattached">xblBindingAttached()</a></code>
|
|
|
|
<li><code><a href="#xblentereddocument">xblEnteredDocument()</a></code>
|
|
|
|
<li><code><a href="#xblleftdocument">xblLeftDocument()</a></code>
|
|
</ul>
|
|
|
|
<h2 class=no-num id=acknowledgments>Acknowledgments</h2>
|
|
|
|
<p>David Hyatt developed XBL 1.0 and provided guidance for the development
|
|
of XBL 2.0.</p>
|
|
|
|
<p>The editor would like to thank Alex Danilo, Alex Vincent, Anne van
|
|
Kesteren, Axel Hecht, Antoine Quint, Benjamin Smedberg, Bjoern Hoehrmann,
|
|
Boris Zbarsky, Brendan Eich, Cameron McCormack, Chris Lilley, Christophe
|
|
Jolif, Cyril Concolato, Darryl Fuller, David Håsäther, Dean
|
|
Jackson, Jon Ferraiolo, Jonas Sicking, Karl Dubost, L. David Baron,
|
|
Lachlan Hunt, Liam Quin, Marcos Caceres, Mark Baker, Micah Dubinko, Mihai
|
|
Sucan, Mikko Pohja, Mohamed Zergaoui, Norman Walsh, Peter Sorotokin,
|
|
Robin Berjon, Ruud Steltenpool, Sean Hogan, Simon Pieters, Steve K.
|
|
Speicher, Steve Zilles, Tim Rowley, and Tom Pike for their contributions
|
|
to this specification.</p>
|
|
|
|
<h2 class=no-num id=references>References</h2>
|
|
|
|
<p>All references are normative unless prefixed by the mark
|
|
"(Informative)".</p>
|
|
|
|
<dl>
|
|
<dt id=refsACCESSCONTROL>[ACCESSCONTROL]
|
|
|
|
<dd>(Informative) <cite><a
|
|
href="http://www.w3.org/TR/2005/NOTE-access-control-20050613/">Authorizing
|
|
Read Access to XML Content Using the <?access-control?> Processing
|
|
Instruction 1.0</a></cite>, M. Oshry, B. Porter, R. Auburn. W3C, June
|
|
2005. The latest version of this specification is available at <a
|
|
href="http://www.w3.org/TR/access-control/">http://www.w3.org/TR/access-control/</a>
|
|
|
|
<dt id=refsCSS21>[CSS21]
|
|
|
|
<dd><cite><a href="http://www.w3.org/TR/2004/CR-CSS21-20040225/">CSS 2.1
|
|
Specification</a></cite>, B. Bos, T. Çelik, I. Hickson, H. Lie.
|
|
W3C, September 2003. The latest version of the CSS 2.1 specification is
|
|
available at <a
|
|
href="http://www.w3.org/TR/CSS21/">http://www.w3.org/TR/CSS21/</a>
|
|
|
|
<dt id=refsCSS3UI>[CSS3UI]
|
|
|
|
<dd><cite><a href="http://www.w3.org/TR/2004/CR-css3-ui-20040511/">CSS3
|
|
Basic User Interface Module</a></cite>, T. Çelik. W3C, May 2004.
|
|
The latest version of the CSS3 UI module is available at <a
|
|
href="http://www.w3.org/TR/css3-ui/">http://www.w3.org/TR/css3-ui/</a>
|
|
|
|
<dt id=refsDOM2VIEWS>[DOM2VIEWS]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113/">Document
|
|
Object Model (DOM) Level 2 Views Specification</a></cite>, A. Le Hors,
|
|
L. Cable. W3C, November 2000. The latest version of the DOM Level 2
|
|
Views specification is available at <a
|
|
href="http://www.w3.org/TR/DOM-Level-2-Views/">http://www.w3.org/TR/DOM-Level-2-Views/</a>
|
|
|
|
<dt id=refsDOM3CORE>[DOM3CORE]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/">Document
|
|
Object Model (DOM) Level 3 Core Specification</a></cite>, A. Le Hors, P.
|
|
Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne.
|
|
W3C, November 2003. The latest version of the DOM Level 3 Core
|
|
specification is available at <a
|
|
href="http://www.w3.org/TR/DOM-Level-3-Core/">http://www.w3.org/TR/DOM-Level-3-Core/</a>
|
|
|
|
<dt id=refsDOM3EVENTS>[DOM3EVENTS]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/">Document
|
|
Object Model (DOM) Level 3 Events Specification</a></cite>, P. Le
|
|
Hégaret, T. Pixley. W3C, November 2003. (Note: Despite its
|
|
non-normative status on the W3C Recommendation track, this specification
|
|
should be considered normative for the purposes of conformance.) The
|
|
latest version of the DOM Level 3 Events specification is available at
|
|
<a
|
|
href="http://www.w3.org/TR/DOM-Level-3-Events/">http://www.w3.org/TR/DOM-Level-3-Events/</a>
|
|
|
|
<dt id=refsECMA262>[ECMA262]
|
|
|
|
<dd><cite><a
|
|
href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript
|
|
Language Specification</a></cite>, Third Edition. ECMA, December 1999.
|
|
This version of the ECMAScript Language is available at
|
|
http://www.ecma-international.org/publications/standards/Ecma-262.htm
|
|
|
|
<dd>(Informative) <cite><a
|
|
href="http://developer.mozilla.org/es4/spec/spec.html">ECMAScript
|
|
Language Specification</a></cite>, Fourth Edition (Incomplete Draft
|
|
Proposal). ECMA, January 2006. This version of the ECMAScript Language
|
|
is available at http://developer.mozilla.org/es4/spec/spec.html
|
|
|
|
<dt id=refsHTC>[HTC]
|
|
|
|
<dd>(Informative) <cite><a
|
|
href="http://www.w3.org/TR/1998/NOTE-HTMLComponents-19981023">HTML
|
|
Components</a></cite>, C. Wilson. Microsoft, September 1998. The HTML
|
|
Components submission is available at
|
|
http://www.w3.org/TR/1998/NOTE-HTMLComponents-19981023
|
|
|
|
<dt id=refsHTML5>[HTML5]
|
|
|
|
<dd>(Informative) <cite><a
|
|
href="http://whatwg.org/specs/web-apps/current-work/">Web Applications
|
|
1.0</a></cite>, I. Hickson. WHATWG, work in progress. The latest version
|
|
of the HTML5 proposal is at
|
|
http://whatwg.org/specs/web-apps/current-work/
|
|
|
|
<dt id=refsMQ>[MQ]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2002/CR-css3-mediaqueries-20020708/">Media
|
|
Queries</a></cite>, H. Lie, T. Çelik, D Glazman. W3C, July 2002.
|
|
The latest version of Media Queries is available at <a
|
|
href="http://www.w3.org/TR/css3-mediaqueries/">http://www.w3.org/TR/css3-mediaqueries/</a>
|
|
|
|
<dt id=refsRFC2045>[RFC2045]
|
|
|
|
<dd><cite><a href="http://www.ietf.org/rfc/rfc2045">Multipurpose Internet
|
|
Mail Extensions (MIME) Part One: Format of Internet Message
|
|
Bodies</a></cite>, N. Freed, N. Borenstein. IETF, November 1996. RFC
|
|
2045 is available at http://www.ietf.org/rfc/rfc2045
|
|
|
|
<dt id=refsRFC2119>[RFC2119]
|
|
|
|
<dd><cite><a href="http://www.ietf.org/rfc/rfc2119.txt">Key words for use
|
|
in RFCs to Indicate Requirement Levels</a></cite>, S. Bradner. IETF,
|
|
March 1997. RFC 2119 is available at http://www.ietf.org/rfc/rfc2119.txt
|
|
|
|
<dt id=refsRFC3986>[RFC3986]
|
|
|
|
<dd><cite><a href="http://www.ietf.org/rfc/rfc3986">Uniform Resource
|
|
Identifier (URI): Generic Syntax</a></cite>, T. Berners-Lee, R.
|
|
Fielding, L. Masinter. IETF, January 2005. RFC 3986 is available at
|
|
http://www.ietf.org/rfc/rfc3986
|
|
|
|
<dt id=refsRFC3987>[RFC3987]
|
|
|
|
<dd><cite><a href="http://www.ietf.org/rfc/rfc3987">Internationalized
|
|
Resource Identifiers (IRIs)</a></cite>, M. Dürst, M. Suignard.
|
|
IETF, January 2005. RFC 3987 is available at
|
|
http://www.ietf.org/rfc/rfc3987
|
|
|
|
<dt id=refsSELECTORS>[SELECTORS]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2001/CR-css3-selectors-20011113/">Selectors</a></cite>,
|
|
D. Glazman, T. Çelik, I. Hickson. W3C, November 2001. The latest
|
|
version of the Selectors specification is available at <a
|
|
href="http://www.w3.org/TR/css3-selectors/">http://www.w3.org/TR/css3-selectors/</a>
|
|
|
|
<dt id=refsUNICODE>[UNICODE]
|
|
|
|
<dd><cite><a href="http://www.unicode.org/versions/Unicode5.0.0/">The
|
|
Unicode Standard, Version 5.0.0</a></cite>, The Unicode Consortium.
|
|
Boston, MA, Addison-Wesley, November 2006. ISBN
|
|
0-321-48091-0<!--, as amended by <a href="http://www.unicode.org/versions/Unicode5.0.1/">Unicode 5.0.1</a> and <a href="http://www.unicode.org/versions/Unicode5.1.0/">Unicode 5.1.0</a>-->.
|
|
The latest version of the Unicode specification is available at <a
|
|
href="http://www.unicode.org/versions/">http://www.unicode.org/versions/</a>
|
|
|
|
<dt id=refsXBL10>[XBL10]
|
|
|
|
<dd>(Informative) <cite><a
|
|
href="http://www.w3.org/TR/2001/NOTE-xbl-20010223/">XML Binding
|
|
Language</a></cite>, D. Hyatt. Mozilla, February 2001. The XBL
|
|
submission is available at http://www.w3.org/TR/2001/NOTE-xbl-20010223/
|
|
|
|
<dd>(Informative) <cite><a
|
|
href="http://www.mozilla.org/projects/xbl/xbl.html">XML Binding
|
|
Language</a></cite>, D. Hyatt. Mozilla, November 2000 (and subsequently
|
|
edited by other contributors). The XBL 1.0 specification is available at
|
|
http://www.mozilla.org/projects/xbl/xbl.html
|
|
|
|
<dt id=refsXFORMS>[XFORMS]
|
|
|
|
<dd>(Informative) <cite><a
|
|
href="http://www.w3.org/TR/2003/REC-xforms-20031014/">XForms
|
|
1.0</a></cite>, M. Dubinko, L. Klotz, R. Merrick, T. Raman. W3C, October
|
|
2003. The latest version of the XForms specification is available at <a
|
|
href="http://www.w3.org/TR/xforms/">http://www.w3.org/TR/xforms/</a>
|
|
|
|
<dt id=refsXML>[XML]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2006/REC-xml-20060816/">Extensible Markup
|
|
Language (XML) 1.0 (Fourth Edition)</a></cite>, T. Bray, J. Paoli, C.
|
|
Sperberg-McQueen, E. Maler, F. Yergeau. W3C, September 2006. The latest
|
|
version of the XML specification is available at <a
|
|
href="http://www.w3.org/TR/REC-xml/">http://www.w3.org/TR/REC-xml/</a>
|
|
|
|
<dt id=refsXMLBASE>[XMLBASE]
|
|
|
|
<dd><cite><a href="http://www.w3.org/TR/2001/REC-xmlbase-20010627/">XML
|
|
Base</a></cite>, J. Marsh. W3C, June 2001. The latest version of the XML
|
|
Base specification is available at <a
|
|
href="http://www.w3.org/TR/xmlbase/">http://www.w3.org/TR/xmlbase/</a>
|
|
|
|
<dt id=refsXMLEVENTS>[XMLEVENTS]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2003/REC-xml-events-20031014/">XML
|
|
Events</a></cite>, S. McCarron, S. Pemberton, T. Raman. W3C, October
|
|
2003. The latest version of the XML Events specification is available at
|
|
<a
|
|
href="http://www.w3.org/TR/xml-events/">http://www.w3.org/TR/xml-events/</a>
|
|
|
|
<dt id=refsXMLNS>[XMLNS]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/TR/2006/REC-xml-names-20060816/">Namespaces in
|
|
XML (Second Edition)</a></cite>, T. Bray, D. Hollander, A. Layman, R.
|
|
Tobin. W3C, August 2006. The latest version of the Namespaces in XML
|
|
specification is available at <a
|
|
href="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a>
|
|
|
|
<dt id=refsXMLSSPI>[XMLSSPI]
|
|
|
|
<dd><cite><a
|
|
href="http://www.w3.org/1999/06/REC-xml-stylesheet-19990629/">Associating
|
|
Style Sheets with XML documents</a></cite>, J. Clark. W3C, June 1999.
|
|
The latest version of the Associating Style Sheets with XML documents
|
|
specification is available at <a
|
|
href="http://www.w3.org/TR/xml-stylesheet/">http://www.w3.org/TR/xml-stylesheet/</a>
|
|
</dl>
|
|
</div>
|
|
</html>
|
|
<!--XXX WANTED:
|
|
|
|
some way of initializing internal fields as pointing to the DOM Nodes
|
|
of anon content, so that the constructor doesn't have to walk content,
|
|
e.g. to set mInputElement in a <textbox> binding containing an <input
|
|
type="text">.
|
|
|
|
maximum number of nodes per <content>, with overflow to other
|
|
<content>s
|
|
|
|
|
|
Nickolay Ponomarev:
|
|
A way to say that the element supports onfoo="" handlers.
|
|
A way to easily fire custom events.
|
|
|
|
-->
|