Abstract
This specification describes the ability to map elements to script,
event handlers, CSS, and more complex content models. 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 div
elements.
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 in theory be used to implement XForms.
Status of this document
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 W3C technical reports
index at http://www.w3.org/TR/.
If you wish to make comments regarding this document, please send them
to dev-tech-xbl@mozilla.org
(subscribe,
archives)
and public-appformats@w3.org
(subscribe,
archives).
All feedback is welcome.
Implementors should be aware that this specification is not stable.
Implementors who are not taking part in the discussions are likely
to find the specification changing out from under them in incompatible
ways. Vendors interested in implementing this specification
before it eventually reaches the Candidate Recommendation stage should
join the aforementioned mailing lists and take part in the discussions.
The editor's copy of this specification is available
in W3C CVS. A detailed list of changes is available from the CVS server.
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. [XBL10]
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 implementations in a broader range of
Web browsers.
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. [HTC]
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.)
While the body of this specification was created outside the W3C, the
W3C Web Application Formats
Working Group is now guiding this specification along the W3C
Recommendation track. This document consists of the initial step along
that process, the first working draft.
This document was produced by a group operating under the 5 February
2004 W3C Patent Policy. W3C maintains a public
list of any patent disclosures 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 Essential
Claim(s) must disclose the information in accordance with section
6 of the W3C Patent Policy.
Table of Contents
1. Introduction
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 behaviour of particular elements by
attaching those elements to appropriate definitions, called bindings. Bindings can be
attached to elements using either cascading style sheets, the document
object model, or by declaring, in XBL, that a particular element in a
particular namespace is implemented by a particular binding. The element
that the binding is attached to, called the bound
element, acquires the new behaviour and presentation specified
by the binding.
Bindings can contain event
handlers that watch for events on the bound element, an
implementation of new methods,
properties and fields that become accessible from the bound element,
shadow content that is inserted
underneath the bound element, and associated resources such as scoped style sheets and
precached images, sounds, or videos.
XBL cannot be used to give a document new semantics.
The meaning of a document is not changed by any bindings that are
associated with it, only its presentation and interactive behaviour.
1.1. Terminology and
Conventions
A binding is the definition of
behaviour that can be applied to an element so as to augment its
presentation.
An XBL subtree is a subtree in an XML
document (an XML instance), the subtree having as its root
node an xbl element in the XBL namespace, which is used to
define bindings. XBL subtrees can stand alone in XBL documents, or can be
included in non-XBL
documents.
An XBL document is an XML document that has
the xbl element at its root.
A non-XBL document is an XML document that
contains elements from multiple namespaces, with its root element being
from a namespace other than XBL (e.g. XHTML).
The term binding document is used to mean
either an XBL document or a
non-XBL document containing one or
more XBL
subtrees.
A bound element is an XML or HTML element to which
a binding has been applied.
A bound document is an XML or HTML document
containing one or more bound
elements.
A shadow tree is a tree of nodes created by
cloning a binding's shadow content
template. 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 explicit
children, to form the final flattened
tree. Shadow trees are hidden from normal DOM processing (hence
the name "shadow"); they are not accessible via Core DOM navigation
facilities such as firstChild or nextSibling.
(See: shadow content.)
The term shadow content refers to the
various nodes in the shadow tree(s) of a bound element. Shadow content is
created by cloning shadow content templates during binding
attachment. (See: shadow content.)
In this specification, the term in error,
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 element, attribute, etc,
must be treated when it is in error are always given when the term is
used. Typically this will involve ignoring the erroneous nodes, meaning the UA must,
for the purposes of XBL processing, act as if those nodes were
absent. UAs must not, however, remove such nodes from the DOM in order to
ignore them. The nodes retain all their non-XBL semantics.
UAs should report all errors to users, although they may do this in an
unobtrusive way, for example in an error console.
In addition to the error handling rules given in this specification, UAs
may abort all processing when encountering an error.
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.
A correct element, attribute,
value, or binding is one which is not in
error.
The namespace of all the XBL elements and
XBL global attributes must be: data:,520e273a-62ad-4528-bb1e-9652bda76d62
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 [XMLNS].
For convenience, elements and attributes from specific namespaces are
sometimes referred to simply in the form prefix:localname,
without explicitly stating which namespace the prefix is bound to. When
this occurs, readers should assume the following prefix declarations are
in scope:
xmlns:xbl="data:,520e273a-62ad-4528-bb1e-9652bda76d62"
xmlns:xforms="http://www.w3.org/2002/xforms"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:html="http://www.w3.org/1999/xhtml"
When this specification refers to elements in a namespace, it
does not exclude elements in no namespace; the null namespace is
considered a namespace like any other for the purposes of XBL processing.
All element names, attribute names, and attribute values in XBL are case
sensitive.
An XML MIME type is text/xml,
application/xml, or any MIME type ending with the string
+xml (ignoring any MIME parameters).
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.
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.
User agents may optimise 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 over clarity than
over efficiency.)
XBL subtrees must satisfy the constraints described in this
specification.
An XBL user agent is an implementation that
attempts to support this specification.
XBL user agents must behave as described by this specification, even
when faced with non-conformant XBL subtrees.
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 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 fully expanded when implementing this
specification. 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 must be used as well.
1.2.1. Attributes Containing Selectors
The element attribute of the binding element and the includes
attribute of the content element, if
specified, must be parsed according to the rules in the Selectors
specification. [SELECTORS]
This specification does not specify what level of Selectors
support is required.
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 xmlns:* 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 ("*"). [XMLNS]
1.2.2. Attributes Containing
Space-Separated Values
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+0020, U+000A, and U+000D 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 occurance of a U+0020 character, dropping that character in the
process.
A space-separated attribute whole value is either the empty string or
that consists of only U+0020, U+000A, and U+000D characters has no values.
1.3. Security Concerns
This section is non-normative.
XBL raises a number of security concerns.
Data theft: 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.
XBL itself does not do anything to prevent this. However, it is strongly
suggested that an access control mechanism (such as that described in [ACCESSCONTROL]) be used to prevent such
cross-domain accesses unless the remote site has allowed accesses.
Privilege escalation: 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 bound document,
so that accessing a remote binding document does not provide the bound
document with any extra privileges on the remote domain.
Cookie theft: 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 cookie attribute on the
DocumentWindow interface be set to null.
Secure bindings: 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.
1.4. Relationship to XBL1
This specification is not backwards compatible with XBL1.
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 content is now called
template, and the XBL1 element children is now called content.
2. XBL Elements
The start of any XBL subtree is an xbl
element, which is described below.
When an XBL element is found inside an element other than that listed as
its "Expected context", it is in
error. 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 child is in error. In both cases, being in error 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.
However, non-XBL elements retain their semantics, even when considered
to be in error for the purposes of
XBL.
For cases where unexpected attributes are found on XBL elements, or XBL
attributes are found on elements other than those listed as the "Expected
context", the error handling is similar: the attributes must be considered
to be in error and the UA must
ignore them, meaning that the
presence of unexpected attributes in no way affects the XBL processing.
Further error handling rules for more specific cases are given where
appropriate.
XBL user agents that support CSS should act as if they had the following
rules in their UA style sheet:
@namespace xbl url(data:,520e273a-62ad-4528-bb1e-9652bda76d62);
xbl|* { display: none; }
XBL user agents that do not support CSS should not render the XBL
elements.
2.1. The xbl Element
- Expected contexts:
- In an XBL document, none
(this is the root element).
- In a non-XBL document, any non-XBL
element whose specification allows the
xbl element as a child.
- Expected children (in any order):
binding: zero or more.
script: zero or more.
- Any non-XBL element.
The xbl element is the root element of
all XBL subtrees.
Attributes
- id
- The
id
attribute.
- script-type
- The
script-type attribute specifies the MIME
type of the scripting language used by all bindings and XBL script blocks
in the XBL subtree. If the attribute is not specified, the default
language is ECMAScript. [ECMA262]
- style-type
- The
style-type attribute specifies the MIME
type of the styling language used by all bindings and XBL style blocks in
the XBL subtree. If the attribute is not specified, the default language
is CSS (text/css).
UAs must consider any xbl elements that
have another xbl element as an ancestor
as being in error and must then
ignore them, meaning those elements
must never be considered to declare any bindings. For example, UAs must
never bind elements to bindings defined by binding elements that have two xbl ancestors.
Similarly, XBL elements (other than the xbl element itself) that do not have a correct xbl
element as an ancestor are in error
too, and UAs must ignore them,
treating them as they would any arbitrary semantic-free XML element. For
example, UAs must never bind elements to bindings defined by binding elements that have no xbl ancestors at all.
The same does not apply to the style-type and script-type
attributes. If the UA does not support the specified styling language, it
must still apply bindings as appropriate; only style blocks must be ignored. Similarly, if the
UA does not support the specified scripting language, it must still apply
bindings as appropriate; only script,
handler and implementation sections must be
ignored.
The empty string is not a special value for these
attributes. Setting the style-type attribute to the empty string,
e.g., will result in all style blocks
being ignored, since the empty string is not a valid MIME type that the UA
supports.
2.2. The binding Element
- Expected context:
xbl
- Expected children (in any order):
implementation: zero or
one.
template: zero or one.
handlers: zero or one.
resources: zero or one.
- Any non-XBL element
The binding element describes a
single XBL binding that adds presentation and interactive behaviour to XML
or HTML elements. Each binding has these optional components:
Methods,
Properties, and Fields: 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:
binding implementations.)
Template: The optional template defines the initial shadow content for the bound element.
Behaviour: A binding
can define event listeners for various types of events. Some examples are:
UI events (e.g., key and mouse events) on the bound element or on elements
within the shadow content; mutation events on the bound element and its
descendants; and events having to do with XBL's binding operations (e.g.,
the binding and bound events).
(See: event handlers.)
Resources: 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: binding style
sheets, prefetching resources.)
Bindings may act as an attachment mechanism, specifying a namespace and
local name of elements to associate with the given binding when the
binding is imported, using the element
attribute.
In addition to the above, the binding 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 ignored by the XBL processing model.
Attributes
- id
- The
id
attribute.
- extends
- The
extends attribute is used to specify the URI
of a binding that this binding inherits from. (See: interpretation of URIs to XBL
bindings.) If the URI is in error or does not refer to another
binding, the UA must ignore it,
meaning that this binding does not explicitly inherit from another
binding. (See: explicit
inheritance.)
- element
-
This attribute specifies a selector. All elements in the binding
document, and in any documents that import the binding document, that match the
given selector, must be bound to the binding defined by this
binding 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.)
If an element attribute contains an invalid
selector, it is in error and must
be ignored, 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
element
attribute, as if the attribute had simply been omitted.
The binding element
defines a presentation and behaviour 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.
2.3. The implementation Element
- Expected context:
binding
- Expected children:
- Depends on the scripting language.
The implementation 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.
The implementation element,
if present, must either contain code in the language specified by the XBL
subtree's script-type attribute, or have a src attribute
that points to a resource containing code in the language specified by the
script-type attribute. The syntax and
semantics of this code depend on the specific language. This specification
defines the semantics for ECMAScript implementations. (See: binding implementations.)
Attributes
- id
- The
id
attribute.
- name
- The
name attribute can be used to provide a specific
name for an implementation. This name can then be used to reference the
implementation. For example, in ECMAScript the value of this attribute
represents the name of the corresponding class that is constructed for
the implementation. If no name attribute is specified, or if it is
specified but empty, then the binding's document URI and ID (if any) are
used to uniquely reference the binding's implementation.
- src
- The
src attribute specifies the URI to a resource of
the type given by the XBL subtree's script-type 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: binding implementations.)
If an implementation element
is marked (via the script-type attribute of the xbl element) as being in a language that the UA
does not support, or, if the implementation element points (using
the src
attribute) to a resource that is either unavailable, or not of the type
specified by the script-type attribute of the xbl element, then it is in error and the UA must ignore it, meaning it must not be used as an
implementation definition for any binding.
How UAs must handle nodes inside implementation elements depends on the
language used. (See: loading and running
scripts, binding
implementations.)
implementation blocks are
evaluated once, on first use. Changes to an implementation element or its contents
have no effect once the element has been evaluated. (See: binding implementations.)
User agents may support an additional attribute with the name
vendor-binary (e.g. moz-binary="" or
khtml-binary="") that contains information on native code
implementations of the binding, if necessary.
2.4. The template Element
- Expected context:
binding
- Expected children:
- Anything. Of particular interest, the
content and inherited elements may occur as
descendants, and non-XBL descendant elements may host xbl:inherits and
xbl:pseudo
attributes.
The template element contains
child nodes that can be in any namespace. The subtree specified by the
template element is referred to as
the shadow content template. When a binding is
attached, the template element's
child nodes are cloned and attached to the bound document under the bound
element. Because these cloned nodes are hidden from their parent and exist
outside the normal document tree, they are referred to as shadow content. (See: rules for shadow content generation.)
Dynamic changes to shadow content templates are reflected in
bindings. (See: shadow content.)
Attributes
- id
- The
id
attribute.
- apply-author-sheets
- The
apply-author-sheets attribute
indicates whether or not rules in author style sheets associated with the
bound element's document apply to the shadow content generated by the
binding. Its value must be either true (indicating that they
do) or false (indicating that they do not). The default
behaviour, 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
author style sheets (same as false). (See: binding style sheets.)
- allow-selectors-through
- The
allow-selectors-through
attribute indicates whether or not rules in CSS can cross scopes. Its
value must be either true (indicating that they can) or
false (indicating that they cannot). The default behaviour,
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
false). (See: binding style
sheets
The semantics of non-XBL elements inside this element are
untouched, which can lead to unintuitive results. (See: semantics of non-XBL elements in XBL
contexts.)
2.5. The content Element
- Expected context:
- Any, but there must be a correct
template element somewhere in the
ancestor chain, and there must not be any correct content elements anywhere in the ancestor
chain.
- Expected children:
- Anything.
The content element is used inside
shadow content to specify insertion
points for explicit children that
might already exist underneath the bound element. As far as the
presentation model is concerned, any shadow content the binding places
between the bound element and the content elements is interleaved between the
bound element and its explicit
children without affecting the document model. (See: processing content
elements.)
If the includes attribute successfully matches
against children of the bound element, then those children are inserted
into the final flattened tree in place
of the content element. If the includes
attribute does not match against any children, then the child elements of
the content element are inserted into
the final flattened tree in place of
the content element instead.
Attributes
- id
- The
id
attribute.
- includes
- The
includes attribute can be used to indicate
that only certain content should be placed at the content element. Its value is a selector. (See: processing content
elements.)
- apply-binding-sheets
- The
apply-binding-sheets attribute
indicates whether or not scoped style sheets loaded for an XBL binding
are applied to a bound element's explicit
children (in addition to the bound element itself) that are
inserted below this content element
when it is processed. Its value must be either true
(indicating that they are) or false (indicating that they
are not). The default behaviour, 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 false). (See: binding style sheets.)
- locked
- The
locked attribute indicates whether or not new
children may be inserted below this content element when it is processed. Its
value must be either true (indicating that they may not) or
false (indicating that they may). The default behaviour,
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
false). Elements already assigned to a content element whose locked attribute
is dynamically changed are not removed from that element. (See: processing content
elements.)
2.6. The inherited Element
- Expected context:
- Any, but there must be a correct
template element somewhere in the
ancestor chain.
- Expected children:
- Anything.
The inherited element represents
an insertion point for the next inherited shadow tree. 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
inherited elemen in the binding's
shadow tree, then the contents of the inherited element (if any) are used instead.
(See: rules for shadow content
generation.)
Attributes
- id
- The
id
attribute.
While it is legal to nest inherited elements, it is pointless, since
if one inherited element used its
fallback content, any subsequent such elements will too.
2.7. The xbl:inherits Attribute
- Expected element:
- Any, but there must be a correct
template element somewhere in the
ancestor chain.
The xbl:inherits 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 space-separated list of QNames or QName
pairs separated by equal signs, each possibly suffixed by a hash character
("#") and a type designation. (See: attribute
forwarding.)
2.8. The xbl:pseudo Attribute
- Expected element:
- Any, but there must be a correct
template element somewhere in the
ancestor chain.
The xbl:pseudo attribute is a global attribute
in the XBL namespace that specifies the pseudo-element that, when used on
the bound element, must be mapped to the element on which the attribute is
found. (See: matching
pseudo-elements.)
2.9. The handlers Element
- Expected context:
binding
- Expected children:
handler: zero or more.
The handlers element's event
handlers can be called for events that flow through the bound element.
During capture, target, bubbling, and default phases, when a given event is
received by a bound element, if a corresponding event listener has been
attached to the handlers element,
then the event will be forwarded to that event listener. (See:
event forwarding, binding attachment and detachment.)
Typically, event handlers are defined using handler elements.
Attributes
- id
- The
id
attribute.
2.10. The handler Element
- Expected context:
handlers
- Expected children:
- Depends on the scripting language.
The handler element describes a
single event handler. This handler is attached to its parent handlers element, which is used as an event
forwarding target when handling events on the bound element. (See:
event handlers.) It wraps a script
that is executed when the event handler is matched.
Attributes
- id
- The
id
attribute.
- event
- The
event attribute describes the specific event
that this handler is listening for. (See: registering event handlers with the
handler element.)
- phase
- This attribute specifies the phase of the event flow that this handler
should monitor. The possible values are
capture,
target, bubble, defaultActian. If
capture is specified, then the event handler must only be
fired during the capturing phase of event propagation. If
target is specified, then the event handler must only be
fired during the target phase. If default-action is
specified, then the event handler must only be fired during the default phase (if it occurs). Otherwise,
the handler must only be fired during the bubbling phase. (See: registering event handlers with the
handler element.)
- trusted
- This attribute specifies whether the handler should be limited to
trusted events. The possible values are
true and
false. If true is specified, then the event
handler must only be fired if the event's trusted attribute is true. Otherwise, the
value of the trusted flag does not
affect the event handler. (See: registering
event handlers with the handler element.)
- propagate
- The
propagate 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). It has
no effect if the phase attribute has the value
default-action. (See: registering event handlers with the
handler element.)
- default-action
- The
default-action 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: registering event handlers with the
handler element.)
- button
- The
button attribute imposes a filter on
the handler. It is used with mouse handlers to specify a particular
button. (See: mouse event handler
filters.)
- click-count
- The
click-count attribute imposes a
filter on the handler. It is used with mouse handlers to specify
how many clicks must have occured. (See: mouse
event handler filters.)
- modifiers
- The
modifiers attribute imposes a filter on key
and mouse handlers. It is used with mouse and key handlers to specify
particular modifier keys. (See: mouse event
handler filters, key event handler
filters, modifiers.)
- key
- The
key
attribute imposes a filter on key handlers. It is used with key handlers
to specify which keys to listen for. (See: key event handler filters.)
- key-location
- The
key-location attribute imposes a filter
on key handlers. It is used with key handlers to specify which keys to
listen for. (See: key event handler
filters.)
- text
- The
text
attribute imposes a filter on text input handlers. It is used with text
input handlers to specify which characters to listen for. (See: text input event handler filters.)
- prev-value
- The
prev-value attribute imposes a filter on
mutation handlers. It is used with mutation handlers to specify what
prev-value to listen for. (See: mutation event handler filters.)
- new-value
- The
new-value attribute imposes a filter on
mutation handlers. It is used with mutation handlers to specify what
new-value to listen for. (See: mutation event handler filters)
- attr-name
- The
attr-name attribute imposes a filter on
mutation handlers. It is used with attribute mutation handlers to specify
what attribute to listen for changes for. (See: mutation event handler filters)
- attr-change
- The
attr-change attribute imposes a filter on
mutation handlers. It is used with attribute mutation handlers to specify
what type of change to listen for changes for. (See: mutation event handler filters.)
If a handler element is marked (via
the script-type attribute of the xbl element) as being in a language that the UA
does not support then the UA must ignore it, meaning it must not be used for the
event handler definitions of any binding.
How UAs must handle nodes inside handler elements depends on the language used.
(See: loading and running scripts,
event handlers.)
handler blocks are evaluated each
time they are fired. Changes to the handler elements therefore take effect the
next time the an event is fired.
2.11. The resources Element
- Expected context:
binding
- Expected children (in any order):
style
prefetch
The resources 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.
Attributes
- id
- The
id
attribute.
2.12. The style Element
- Expected context:
resources
- Expected children:
- Depends on the styling language.
The style 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 explicit children (and their descendants)
assigned to insertion points in the shadow content whose apply-binding-sheets attribute is
set.
Attributes
- id
- The
id
attribute.
- media
- The
media
attribute specifies the intended destination medium for style
information. How the value of this attribute is interpreted is defined by
Media Queries [MQ]. If this attribute is not
specified, then there is no restriction on which media the style sheet
should be applied to (same as specifying media="all").
- src
- The
src
attribute specifies the URI to a resource of the type given by the XBL
subtree's style-type 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: binding style sheets.)
If a style element is marked (via the
style-type attribute of the xbl element) as being in a language that the UA
does not support, or, if the style
element points (using the src attribute) to a resource that is either
unavailable, or not of the type specified by the style-type
attribute of the xbl element, then it is
in error and the UA must ignore it, meaning it must not be used to
style anything.
How UAs must handle nodes inside style elements depends on the language used.
(See: binding style sheets.)
2.13. The prefetch Element
- Expected context:
resources
- Expected children:
- None.
The prefetch element can be used
to list resources that may be pre-loaded for performance reasons. Support
for this element is optional. UAs may ignore it.
Attributes
- id
- The
id
attribute.
- src
- A URI to a resource (such as an image) that the binding might use
later.
2.14. The script Element
- Expected context:
xbl
- Expected children:
- Depends on the scripting language.
The script 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.
The script element, when present,
must either contain code in the language specified by the XBL subtree's
script-type attribute, or have a src attribute that
points to a resource containing code in the language specified by the
script-type attribute. The syntax and
semantics of this code depend on the specific language. (See: loading and running scripts.)
Attributes
- id
- The
id
attribute.
- src
- The
src
attribute specifies the URI to a resource of the type given by the XBL
subtree's script-type 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: loading and running scripts.)
If an script element is marked (via
the script-type attribute of the xbl element) as being in a language that the UA
does not support, or, if the script
element points (using the src attribute) to a resource that is either
unavailable, or not of the type specified by the script-type
attribute of the xbl element, then it is
in error and the UA must ignore it, meaning it must not be executed.
How UAs must handle nodes inside script elements depends on the language used.
(See: loading and running scripts.)
script blocks must be evaluated when
their end-tag is parsed, or, for dynamically created elements, when they
are inserted into a document. Once evaluated, a script block is dead and changes to its
contents have no effect.
2.15. The id Attribute of XBL Elements
- Expected element:
- Any element in the XBL namespace.
The id attribute
assigns a name to an element. This name must be unique in the binding document. The id attribute is of type ID. [XML].
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).
3. Resources
3.1. Loading
External Resources
Several features in XBL allow external resources to be loaded.
When the specification says that the resource must be loaded unless
it has already been loaded, then references to the same resource
(even if they are somewhat indirect, for example via HTTP redirects) must
result in the same instance being reused, or shared. To determine if two
resources are the same, their final base URIs (after all redirects) are
compared.
A binding document A contains a
binding element that refers to a
second binding document X. A new DOM Document instance is
created to represent that instance and the relevant bindings are used.
Now assume RX is a resource that redirects to resource X using the HTTP
301 redirection mechanism. A second binding 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
Document, the existing one is reused.
Such resource sharing is limited to resources loaded by a document, its
binding documents, its scripts, and its style sheets. Nested documents and
images do not share resources with each other or with their container
document.
Resources that are currently loading count as resources that are already
loaded for the purposes of this reuse mechanism.
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
iframe whose document uses the same binding document, a new
instance will be used: the binding document instance from the outer
document is not reused.
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.
For example, two style elements whose src attributes
point to the same style sheet must create two different
Stylesheet instances, such that mutating one does not affect
the other.
Several XBL attributes are defined to contain URIs. All URIs may be
relative. For relative URIs, the rules given in [XMLBASE] must be used to resolve the value to an
absolute URI.
3.2. Loading and Running Scripts
Scripts in XBL may be found in script, implementation, and handler elements, or in resources that those
elements point to.
In the case of script and implementation
elements, if a src attribute is present then the
contents of the element must be ignored (even if
fetching the specified URI failed).
In any case, wherever the script is found, the rules for parsing it are
the same, but depend on the language specified by the author.
For non-XML languages, if the content is inline, UAs must concatenate
all the textual contents of text and CDATA child nodes, and must ignore 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. A script element labelled as
containing script in a non-XML language yet containing element nodes is
in error.
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 test property in the
binding document's global script scope to the string "undefinedABC":
<xbl xmlns="data:,520e273a-62ad-4528-bb1e-9652bda76d62">
<script>
alert('Two');
test += "B";
<script xmlns="http://www.w3.org/1999/xhtml">
alert('One');
test += "A";
</script>
alert('Three');
test += "C";
</script>
</xbl>
Authors must not ever consider doing this.
For XML-based scripting languages, handling of unknown elements and
unexpected nodes must be defined by that language.
If the content was in another file, and that file's Content-Type (or
equivalent for non-HTTP protocols), if any, was of the type specified
on the xbl element, then the contents of
that file are used directly, as specified by the relevant language
specification.
src attributes must only be examined once all the
element's children (if any) have been processed.
This section is only normative for implementations that support
XForms.
It is theoretically possible to use XForms Actions as the scripting
language in XBL [XFORMS]. The MIME type that
indicates this scripting language is tentatively defined to be application/x-xforms-actions+xml. XBL elements
have the following semantics when used with XForms Actions:
script elements
- These are exactly equivalent to
xforms:action elements
that trigger immediately upon being added to the document.
handler elements
- These are exactly equivalent to
xforms:action elements
that trigger when the appropriate event on the bound element is detected.
implementation elements
- Since XForms Actions cannot declare new interfaces,
implementation elements when the
script language is set to application/x-xforms-actions+xml are in error and the UA must ignore them, by treating implementation elements like
xforms:action elements that are not bound to any event.
3.2.2. Scripting Model
Each document that runs script (including bound documents and binding
documents) has a DocumentWindow object, a Window
object, a script scope, and a security context. In ECMAScript, the script
scope and the Window object are one and the same.
Script must always be executed in the context of the script scope of the
document specified by the script's element's ownerDocument
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.
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.
Security contexts are (or will be) described in the HTML5 specification.
[HTML5]
In binding documents, the location and history
properties of the Window object, and the
location and cookie properties of the
DocumentWindow object, must return null, and any methods that
are defined in terms of the browsing context's session history must do
nothing. [HTML5]
User agents should implement a security mechanism such as the proposed
<?access-control?> PI to prevent unauthorised
cross-domain access. [ACCESSCONTROL]
3.3. Loading Style Sheets
XBL style elements describe the style
sheets that apply to bindings.
If a style element's src attribute is
present, the contents of the element must be ignored (even if fetching the specified URI
failed). Otherwise, it is the element's contents that give the style
sheet.
Wherever the style is found, the rules for parsing it are the same, but
depend on the language specified by the author.
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 ignore 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 labelled as containing a style sheet in a non-XML language yet
containing element nodes is in error.
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:
<xbl xmlns="data:,520e273a-62ad-4528-bb1e-9652bda76d62">
<binding>
<template>
<div xmlns="http://www.w3.org/1999/xhtml">
<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 processor, 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>
For XML-based styling languages, handling of unknown elements and
unexpected nodes must be defined by that language.
If the content was in another file, and that file's Content-Type (or
equivalent for non-HTTP protocols), if any, was of the type specified on
the xbl element, then the contents of
that file must be used directly, as specified by the relevant language
specification. The src attribute must only be examined once all of
the element's children have been processed (if any).
3.4. Interpretation of URIs to XBL bindings
XBL attachment mechanisms use a URI to specify which binding to attach
to the designated element. For example:
my|foo {
-xbl-binding: url("http://www.example.org/bindings.xml#fooBinding");
}
This section defines how these URIs, which are used in the argument to
the addBinding() method, and in the
value of the '-xbl-binding' property, are to be interpreted.
The URI specifies a particular binding
document (an XBL
document or non-XBL
document containing one or more XBL subtrees). The user agent
must fetch this resource (unless it has already been loaded).
If the URI contains a fragment identifier, it must point to a specific
binding element (by id) within an XBL subtree in
the specified document, and that element must be a direct child of an
xbl element that does not itself have an
xbl element as an ancestor; if these
conditions are not met then the URI is in
error.
If there is no fragment identifier and the URI points to an XBL document
(not a non-XBL document) then the
first binding element in the binding
document that is a child of the root xbl
element is selected. Otherwise, the URI does not point to a correct binding and is in error.
When an attachment mechanism uses a URI that is in error (as per the
last two paragraphs), then the user agent must act as if the attachment
mechanism had not specified that binding.
Otherwise, the specified binding is attached to the element, as
described for the relevant attachment mechanism.
4. Binding
Attachment and Detachment
Bindings can be attached and detached dynamically, using several
mechanisms.
Bindings must be attached as soon as the following conditions have all
been met:
- it is known that the binding applies to the element,
- the element has been created, and
- the binding document defining the binding has loaded.
In particular, binding can happen before the element is inserted into
its document.
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 element attribute is mutated in a script), then
the binding must be applied such that to any running scripts it appears
that the binding was applied immediately.
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.
If the binding attachment mechanism is the
'-xbl-binding' 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.
Bindings must be detached as soon as it is known that the binding no
longer applies to the element.
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: binding attachment
model.)
4.1. Attachment using <binding element="">
The simplest binding mechanism is the binding element's element
attribute. It declares which bindings should be attached to which
elements. (See: attributes
containing selectors, the binding element.)
While an element matches the element attribute of one of the binding elements that is imported into, or defined
in, the element's document, the binding defined by the first such binding 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
final flattened tree.
4.1.1. Importing binding documents
There are two ways to import binding documents (and thus have their
<binding
element=""> bindings apply): the <?xbl?> processing
instruction, and the loadBindingDocument() method. The
latter is defined in the section on the DocumentXBL interface.
The <?xbl?>
processing instruction specifies a binding document to load. Any
bindings defined in that document must be applied to
matching elements in the document with the processing instruction.
<?xbl?> processing instructions that occur after the
root element's start tag in the markup are in
error. <?xbl?> 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 in error too.
A <?xbl?> processing instruction that is not in error
according to the above must be parsed using the same syntax as the XML
Stylesheet PI. [XMLSSPI] If there are any parse
errors, then the entire processing instruction is in error.
Otherwise, if it has an href pseudo-attribute then it
specifies the URI of the binding document to import. If the URI cannot be
resolved, or returns an error, or does not point to a resource with
an XML MIME type, or has any other problem
that makes it unusable, then the processing instruction is in error.
If a processing instruction is in error (as described in the previous
few paragraphs) then it must be ignored.
Otherwise, the referenced document must be loaded (unless it has already been
loaded), 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 bindingDocuments list of the document
with the PI.
Dynamic changes to <?xbl?> processing instructions
must be ignored from an XBL standpoint.
An imported binding document is live. For example, if new
binding elements are added to it
(via the DOM), then the new bindings are immediately applied to the
document that had the PI.
XBL bindings are always implicitly imported into the document in which
they are defined.
An XBL subtree that defines some bindings is automatically imported in
that document, so such mappings are always used. The following example
demonstrates this.
example.xml
<...>
<xbl xmlns="data:,520e273a-62ad-4528-bb1e-9652bda76d62" ...>
<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 -->
</...>
If the binding definitions are in a separate file, then that file needs
to be imported explicitly:
widgets.xml
<...>
<xbl xmlns="data:,520e273a-62ad-4528-bb1e-9652bda76d62" ...>
<binding element="foo">
...
<binding>
<binding element="bar">
...
<binding>
</xbl ...>
</...>
example.xml
<?xbl href="widgets.xml"?>
<...>
<foo/> <!-- bound -->
<bar/> <!-- bound -->
</...>
If a file imports some bindings and the file containing those bindings
has its own <?xbl?> processing instructions, that
second PI only affects nodes in the binding document, not the original
document. For example:
foo.xml
<...>
<xbl xmlns="data:,520e273a-62ad-4528-bb1e-9652bda76d62" ...>
<binding element="foo">
<content>
<bar xmlns=""/> <!-- not bound, not even when in shadow content -->
</content>
<binding>
</xbl>
</...>
bar.xml
<?xbl href="foo.xml"?>
<...>
<xbl xmlns="data:,520e273a-62ad-4528-bb1e-9652bda76d62" ...>
<binding element="bar">
<content>
<foo xmlns=""/> <!-- bound: this document imports foo.xml -->
<bar xmlns=""/> <!-- bound: bar binding is defined locally -->
</content>
<binding>
</xbl>
</...>
example.xml
<?xbl href="bar.xml"?>
<...>
<foo/> <!-- not bound: foo.xml not imported here -->
<bar/> <!-- bound -->
</...>
4.2. Attachment using CSS
Bindings can be attached to elements through CSS using the
'-xbl-binding' property.
In the following example, a binding is referenced that will be attached
to all XHTML checkbox elements.
input[type="checkbox"] {
binding: url("http://www.example.org/xbl/htmlBindings.xml#checkbox");
}
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 inheritance chain) must be detached.
Whenever an element is removed from a document, any bindings attached to
that element via CSS must be detached.
Attaching a binding using CSS does not import the binding document. The element
attributes of binding elements in
the binding document do not take effect unless the binding document is
imported. (See: importing
binding documents.)
4.2.1. The
'-xbl-binding' property
We have to do something about this section, we can't
just go around inventing new CSS properties. Either we'll submit this to
the CSS working group, or we'll use '-xbl-binding' as the property name.
A property to bind an XBL binding to a particular element.
'-xbl-binding'
| Value:
| none | [ <uri> ',' ]* <uri>
|
| Initial:
| none
|
| Applies To:
| all elements (but not pseudo-elements)
|
| Inherited:
| no
|
| Percentages:
| n/a
|
| Media:
| all
|
| Computed Value:
| specified value, with URIs resolved to absolute URIs
|
- none
- No bindings are to be attached through CSS.
- <uri>
- 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: binding inheritance.)
4.2.2. Processing model
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 either case, for each element the computed value of
'-xbl-binding' 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).
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 '-xbl-binding' property for the element, and then applying any
bindings, before any of its descendants.
4.3. Attachment using the
DOM
Bindings can be attached to elements through the DOM using the ElementXBL interface. The method
addBinding takes a binding URI and
attaches the binding to the element (in all views).
var checkbox = document.getElementById("mycheckbox");
checkbox.addBinding("http://www.example.org/xbl/htmlBindings.xml#checkbox");
This attachment is not necessarily synchronous. Scripts that invoke this
method should not assume that the binding is installed immediately after
this method returns.
When a binding is attached using the DOM, it inherits from the current
most derived binding that is
already attached to the element, if any. (See: binding inheritance.)
Any bindings attached to an element using the addBinding() method will remain on the
element until the element is destroyed or a corresponding removeBinding() call is made.
Attaching a binding using the addBinding() DOM APIs does not import the binding document. The element
attributes of binding elements in
the binding document do not take effect unless the binding document is
imported. (See: importing
binding documents.)
4.4. Binding Attachment Model
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.
- If the binding has an
extends 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 extends
attributes — then the user agent must only apply each binding in
the chain once. (See: explicit
inheritance, interpretation
of URIs to XBL bindings.)
- If other bindings are already attached to the bound element, then the
newly added binding will add a new chain to the element list of bindings. (See:
implicit inheritance.)
- 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: binding
implementations.)
- Events must start being routed through the binding's
handlers element, when there is one. (See:
event forwarding.)
- If the new binding changes which shadow trees contribute to the
final flattened tree then the
explicilt children must be redistributed.
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 xblBindingAttached() method must be
invoked on the binding's implementation, immediately followed,
if that bound element is in a document,
by the invocation of the xblEnteredDocument() method.
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 compareDocumentPosition() 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. [DOM3CORE]
The order that bindings on the same bound element have these methods
called must be the derivation order, with less derived bindings being
initialised before more derived bindings.
After all the appropriate methods have been called, an xbl-bound event in the
XBL namespace, that bubbles, is not cancelable, has no default action, and
uses the Event interface, must be fired on every bound
element that just got bound, in the same order as their xblBindingAttached() methods were
invoked. (See: binding inheritance.)
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: binding detachment
model.)
4.5. Handling Insertion and Removal from the Document
A bound element is in a document if it has a
Document node as an ancestor, of it is in a shadow tree and
that shadow tree's bound element is itself in a document.
When a bound element that is not in a document is affected in such a way that it
subsequently is in a document,
then the xblEnteredDocument() method must be
invoked on the binding's implementation.
Similarly in reverse: when a bound element that is in a document is affected in such a
way that it subsequently is not in a document, then the xblLeftDocument() method must be
invoked on the binding's implementation.
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).
4.6. Binding Inheritance
Bindings can inherit from each other explicitly using the extends
attribute. They can also inherit from each other implicitly if
multiple bindings are attached to an element.
A base binding is a binding that does not
inherit from any other binding, either explicit or implicity.
A base binding of the chain is any binding
that does not inherit explicitly from another, but may inherit implicitly
from other bindings.
A most derived binding is a binding that no
other binding inherits from.
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 base binding.
The results of inheritance are described in the sections on
binding implementations and shadow content.
4.6.1. Explicit inheritance
The binding element's extends 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: binding attachment model, binding
detachment model.)
The extends attribute thus
creates a binding inheritance
chain.
If a binding element's extends attribute is changed, then, for
each time the binding is bound to an element, the user agent must follow
these steps:
-
If the binding is attached to the bound element because another
binding is inheriting from it using the extends attribute, then, for this
instance of the binding on this bound element, repeat this process with
the derived binding instead.
Otherwise, the binding was attached to the bound element directly, and
is not being inherited by another binding using the extends attribute.
-
Detach the binding. (See: binding detachment model.)
-
Re-attach the binding so that it is in the same place in the binding
chain. (See: binding attachment
model, implicit
inheritance.)
It is possible to form a loop with the extends 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 most derived binding), derived from B,
derived from C, with C as the base
binding (chain A→B→C). If, given the same
definitions, the element was bound directly to C, then the chain would be
C-B.
4.6.2. Implicit inheritance
When two bindings are both attached to the same element, the base
binding at the end of the inheritance chain of the second binding
implicitly inherits from the most derived
binding of the inheritance chain of the first.
If one of the binding
chains is removed, then the remaining binding chains are
reconnected so that the base binding of the
chain after the break now inherits from the most derived binding before the break.
The order of bindings is always such that bindings added via the
binding 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 '-xbl-binding'
property), and the bindings added via addBinding are third (in the order they were
attached, most recently attached being the most derived binding).
For example, take a binding d1, which specifies a
base binding d2 using the extends
attribute such that its explicit inheritance chain is:
d1 → d2
If this element is attached to an element using addBinding that already has a binding chain
of:
s1 → s2 →
s3
...then the base binding at the end of the inheritance chain,
d2, is the one that will inherit from the most
derived binding that is already attached to the element,
s3. The resulting binding chain following the
addition of the binding is therefore:
d1 → d2 →
s1 → s2 →
s3
The inheritance between d3 and
s1 is implicit, 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 addBinding method.
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.)
4.7. Views and Attachment
Only one set of bindings is attached to the document, and they must
affect all views in a multi-view UA. Bindings attached via style sheets
must be attached based on the style sheets that apply to the default view.
4.8. Attachment During
Document Load
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
binding document is not yet loaded,
the load is started in the background and the binding is only attached
once the document is available. An author can ensure that all bindings are
synchronously attached by calling loadBindingDocument to pre-fetch
any binding documents that are required.
The bound document must wait until all XBL dependencies have loaded
before firing its load event.
4.9. Binding Detachment Model
When a binding is detached, the xblLeftDocument() method must be
invoked on the binding's implementation. Then, 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.
If the binding had an extends attribute when it was bound to the
element (it may have changed since then), then the user agent must then
detach the binding that was attached because of that attribute (if any).
(See: explicit inheritance, interpretation of URIs to XBL
bindings.)
If other bindings still apply to the element, the shadow tree must then
be regenerated. (See: rules for shadow content
generation.)
5. Shadow
Content
A binding can specify a shadow content
template using the template element. This template describes a
content tree that will be generated under the bound element during binding
attachment. An element declared in a bound document using a single element
can then be constructed out of multiple child elements, and this
implementation is hidden from the bound document.
When the shadow content template is cloned (as described in this
section), the clone is called a shadow
tree.
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:
<binding id="fileupload">
<template>
<html:input type="text"/>
<html:input type="button"/>
</template>
</binding>
Because this content is not visible to its parent element, it is said
to be shadow content.
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.
Whenever bindings are attached to an element, shadow content will
potentially be generated. Similarly, when a binding is removed
from an element, its shadow content, if any, is destroyed.
If a binding element that had no
template element has a template element added, then a shadow tree
must be generated. If the template
element is removed, then the shadow tree must be destroyed.
The template element used to
generate a binding is always the first such element in a binding element. If the binding element is mutated in a way which
changes which template element is
the first, then the corresponding shadow tree must be regenerated.
Similarly, when a template element
or any of its descendants is mutated in any way, any bindings whose shadow
tree was constructed from that element must be regenerated.
Regenerating a shadow
tree consists of first destroying the existing shadow
tree and then
