Elements

  • Revision slug: XBL/XBL_1.0_Reference/Elements
  • Revision title: Elements
  • Revision id: 41851
  • Created:
  • Creator: Nickolay
  • Is current revision? No
  • Comment /* handler */ mention that whitespace is valid separator for 'modifiers'

Revision Content

bindings

This section is tested and adjusted for the current Firefox implementation. Please edit only if an actual behavior differs from the described one. Please do not edit only on the basis of another XBL specification.

<!ELEMENT bindings ( binding* ) >

Hierarchy:   root element
May contain: <binding>

The bindings element is the root element of any XBL document. It must declare the default namespace and it may declare additional namespaces used in your binding.

bindings contains zero or more binding elements as children. Each binding child element defines a unique binding that can be attached to elements in other documents.

An element can have only one binding attached (explicetly or inherited) at one moment. From several bindings only the last in the sequence will be used (like with any CSS rule).

HelloWorld example:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<title>Hello world!</title>
<style type="text/css">
p {
 -moz-binding: url(hello.xml#default);
}
#p03 {
 -moz-binding: url(hello.xml#hello2);
}
</style>
</head>
<body

  ><p>Default content</p
  ><p>Default content</p
  ><p id="p03">Default content</p

></body>
</html>

// hello.xml

<?xml version="1.0"?>
<bindings xmlns="http://www.mozilla.org/xbl"
 xmlns:html="http://www.w3.org/1999/xhtml">
  <binding id="default">
    <content><html:b>Hello world! </html:b><children/></content>
  </binding>
  <binding id="hello2">
    <content><html:b>Hello from my binding! </html:b><children/></content>
  </binding>
</bindings>

View this example

Next: <big>bindings > binding</big> element.

Notes

  • In the current implementation it is impossible to attach bindings to table sub-elements (rows, cells etc.) You can attach binding only to the table element itself. See {{template.Bug(83830)}} for workarounds.
  • Default encoding in XML documents (uncluding XBL files) is UTF-8. An explicit encoding declarations may be present to override the default, for example <?xml version="1.0" encoding="ISO-8859-1"?>
  • URI in namespace declarations is an opaque string used to uniquely identify the namespace. It doesn't have to (and often it doesn't) point to some actual schema or a namespace-related resource. Namespaces in XML
  • Besides the default namespace, you can declare any amount of additional namespaces to handle your content. The most useful namespaces could be HTML/XHTML, XUL (XML User Interface Language), SVG (Scalable Vector Graphics) and XLink. This way a more-or-less universal namespace declaration in your bindings could be like:
<bindings xmlns="http://www.mozilla.org/xbl"
 xmlns:html = "http://www.w3.org/1999/xhtml"
 xmlns:xul  = "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
 xmlns:svg  = "http://www.w3.org/2000/svg"
 xmlns:xlink= "http://www.w3.org/1999/xlink">

binding

<!ENTITY % binding-content "(resources?,content?,implementation?,handlers?)">
<!ELEMENT binding %binding-content;>
<!ATTLIST binding
   id                     ID             #REQUIRED
   extends                CDATA          #IMPLIED
   display                CDATA          #IMPLIED
   inheritstyle           true           #IMPLIED
>

The binding element describes a single XBL binding. A XBL binding can add anonymous content, fields, properties, methods, and event handlers to HTML/XML elements.

A single XBL binding can be attached to an element by using style sheets or by scripting. (See {{template.Bug(83830)}} for <table> specifics).

CSS:

div {
 -moz-binding: url(myBinding.xml#default);
}

DOM:

elementReference.style.MozBinding = "url(myBinding.xml#default}";

In both cases above we are using binding with id="default" contained in file myBinding.xml

Only CSS declarations provide an easy way to attach bindings to any set of elements. It also makes your binding partially functional if scripting is disabled. In the latter case all methods and handlers will be blocked, but the anonymous content and styling will be still used. Given that the CSS declarations should be always used - unless you need to add bindings at runtime to individual elements.

A binding element may contain a resources tag, a content tag, a implementation tag and a handlers tag.

  • id - The id attribute is a document-unique identifier. For the binding element, this attribute is required, since it is used to attach bindings.
  • extends - The extends attribute is used to specify the URL of a binding that this binding inherits from (see Inheritance of Implementations). The URL specifies a particular binding document. The # notation must be used to point to a specific binding id within a binding document. Note that content cannot be inherited, only behavior.
  • display - This attribute specifies how the tag is displayed. By setting this attribute, you can have an element have the layout and display characteristics of an existing element. For example, use the value 'xul:button' to create an element that is displayed like a button. The part before the colon is a namespace prefix so you must declare the XUL namespace as well. Not all tags have a unique display type. The following XUL display types may be used: browser, button, checkbox, description, editor, grippy, iframe, image, label, menu, menuitem, menubar, progressmeter, radio, resizer, scrollbar, scrollbox, spacer, splitter, titlebar, treechildren and treecol. You may also use a number of HTML, MathML and SVG tags. The 'display' attribute does not work unless the extends attribute is set, see bug {{template.Bug(119389)}}. In that case, put the value of the display attribute into the extends attribute.
  • inheritstyle - The inheritstyle attribute indicates whether style rules from the document will affect anonymous content generated by the XBL binding. If this attribute is true, styles from the document will also be applied to the XBL generated anonymous content.

content

<!ELEMENT content ANY>
<!ATTLIST content
   id               ID           #IMPLIED
>

A binding can specify new content that is placed inside the bound element. Although you can see this content on screen as if it was directly in the file, this content is anonymous and is hidden from the normal DOM. To access anonymous nodes on an XBL bound element, you can use the getAnonymousElementByAttribute and getAnonymousNodes functions. The only XBL element that can appear inside the content tag is the children tag.

  • id - The id attribute is a document-unique identifier.

children

<!ELEMENT children EMPTY>
<!ATTLIST children
   id               ID                           #IMPLIED
   includes         CDATA                        #IMPLIED
>

Specifies the location where any child elements of the bound element are placed in the generated content.

Normally, if the element bound to has its own content, the anonymous content is not generated. However, with a children element, you can merge the content from the HTML/XML element and the XBL content.

If the children tag contains content itself, that content will become the default content. If the element the binding is attached to contains content, the default content will be ignored. If the element does not contain content, the default content will be added.

  • id - The id attribute is a document-unique identifier.
  • includes - The includes attribute can be used to indicate that only certain content should be placed at the insertion point specified by the children element. Its value can be a tag name or multiple tag names separated by commas. A child can only be placed within the insertion point if it is matched by the value in the includes attribute. Only immediate children are matched against the selector.

implementation

<!ENTITY % implementation-content "(method|property)*">
<!ELEMENT implementation %implementation-content;>
<!ATTLIST implementation
   id               ID           #IMPLIED
   name             CDATA        #IMPLIED
   implements       CDATA        #IMPLIED
>

The implementation element describes the set of methods and properties that are attached to the bound element. Once the binding is attached, these methods and properties can be invoked directly from the bound element.

  • id - The id attribute is a document-unique identifier.
  • 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 JavaScript the value of this attribute represents the name of the corresponding class that is constructed for the implementation. If no name attribute is specified then the binding's document URI and id are used to uniquely reference the binding's implementation.
  • implements - The implements attribute can be used to describe the set of interfaces that are implemented by the binding. Its value is a comma-separated list of named interfaces. If supported, in strongly typed languages the bound element can be referenced not only as any of the interfaces that the element might already support (e.g., HTMLElement) but also as any of the interfaces described by this attribute. Support of this capability is optional.

constructor

The code inside the constructor is called when a binding has just been attached to an element. So full access to anonymous nodes generated by the binding is already possible. The constructor tag must be placed inside the implementation tag.

  • id - The id attribute is a document-unique identifier.
  • action - The code inside theaction attribute is executed. Alternatively, you can put the code inside the constructor element itself.

destructor

The code inside the destructor is called when a binding is being removed from an element. You can use this to unload resources to free memory. However the destructor is often not called when it should, see {{template.Bug(230086)}}. The destructor tag must be placed inside the implementation tag.

  • id - The id attribute is a document-unique identifier.
  • action - The code inside theaction attribute is executed. Alternatively, you can put the code inside the destructor element itself.

method

<!ENTITY % method-content "(parameter*,body?)">
<!ELEMENT method %method-content;>
<!ATTLIST method
   id               ID           #IMPLIED
   name             CDATA        #REQUIRED
   type             CDATA        #IMPLIED
>

The method element is used to describe a single method of a binding implementation.

  • id - The id attribute is a document-unique identifier.
  • name - The name attribute's value is the name given to the method when it is attached to the bound element. The method can be invoked directly from the bound element using this value.

Example

<method name="scrollTo">
  <parameter name="index"/>
  <body>
    this.setAttribute("scrollpos", index);
  </body>
</method>

parameter

<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
   id               ID           #IMPLIED
   name             CDATA        #REQUIRED
>

The parameter element is used inside a method element. It represents a single parameter of a method.

  • id - The id attribute is a document-unique identifier.
  • name - The value of the name attribute is used by script within a method's body element to reference this parameter.

body

<!ELEMENT body CDATA>
<!ATTLIST body
   id               ID           #IMPLIED
>

The body element represents the implementation of its corresponding method. Its contents are the script that is executed when the method is invoked.

  • id - The id attribute is a document-unique identifier.

field

A field is similar to a property, except that it should not have a getter or setter. It is useful as a simple holder for a value. The field element may have content which is code that determines the initial value of the field. The field tag must be inside the implementation tag.

  • id - The id attribute is a document-unique identifier.
  • name - The name of the field. This is the name used to refer to the field on the bound element.

property

<!ENTITY % property-content "(getter?,setter?)|#PCDATA">
<!ELEMENT property %property-content;>
<!ATTLIST property
   id               ID                  #IMPLIED
   name             CDATA               #REQUIRED
   readonly         (true|false)        #IMPLIED
   onget            CDATA               #IMPLIED
   onset            CDATA               #IMPLIED
>

The property element represents a single property of an implementation. A property consists of a pair of getter/setter functions that can be defined using onget/onset attributes or getter/setter elements underneath the property element. Like methods, once the binding is attached, the property can be obtained directly from the bound element. The property tag must be inside the implementation tag.

  • id - The id attribute is a document-unique identifier.
  • name - The name of the property. This is the name used to refer to the property on the bound element.
  • readonly - The readonly attribute is used to designate a property as read-only. If set to true, the value of the property cannot be altered. If this attribute is omitted, the property will be readable and writable.
  • onget - The onget attribute's value is a script that executes when the value of the property is requested. If this attribute is set, any initial value contained underneath the element will be ignored. The return value of the script represents the value of the property that will be returned to the requestor. A property getter can also be specified as a child of the property element using the getter tag.
  • onset - The onset attribute's value is a script that executes when the value of the property is being altered. If this attribute is set, any initial value contained underneath the element will be ignored. Within the script, the parameter val represents the new value being assigned. The script should always return the actual value assigned in order to allow for chained assignment operations. A property setter can also be specified as a child of the property element using a setter tag.

getter

<!ELEMENT getter PCDATA>
<!ATTLIST getter
   id               ID                  #IMPLIED
>

The getter element contains script that gets executed when a specific property gets called. The getter tag must be inside the property tag.

  • id - The id attribute is a document-unique identifier.

setter

<!ELEMENT setter PCDATA>
<!ATTLIST setter
   id               ID                  #IMPLIED
>

The setter element contains script that gets executed when a specific property is being set. The setter tag must be inside the property tag.

  • id - The id attribute is a document-unique identifier.

handlers

<!ENTITY % handlers-content "handler*">
<!ELEMENT handlers %handlers-content;>
<!ATTLIST handlers
   id               ID                  #IMPLIED
>

The handlers element contains event handlers that can be attached to elements within the bound document. These handlers are installed when the binding is attached and removed when the binding is detached. The handlers tag must be inside the binding tag.

  • id - The id attribute is a document-unique identifier.

handler

<!ENTITY % handler-content "PCDATA">
<!ELEMENT handler %handler-content;>
<!ATTLIST handler
   id               ID                                  #IMPLIED
   event            NMREF                               #REQUIRED
   action           CDATA                               #IMPLIED
   phase            (capturing|bubbling|target)         #IMPLIED
   button           (1|2|3)                             #IMPLIED
   modifiers        CDATA                               #IMPLIED
   keycode          CDATA                               #IMPLIED
   key              CDATA                               #IMPLIED
   charcode         CDATA                               #IMPLIED
   clickcount       (1|2|3)                             #IMPLIED
   command          ID                                  #IMPLIED
   preventdefault   false|true                          #IMPLIED
>

The handler element describes a single event handler. This handler is attached to its target at the time the binding is attached and unhooked when the binding is detached from the bound element. The script inside the handler is executed when the event handler is matched. The handler tag must be inside the handlers tag.

  • id - The id attribute is a document-unique identifier.
  • event - The event attribute describes the specific event that this handler is listening for. Its value can be any legal DOM event name (including custom events created using the DocumentEvent interface of the DOM).
  • action - The action attribute contains script that is invoked when the handler fires. The type attribute on the enclosing handlers element determines the language of the script. The handler script can also be specified as a child of the handler element.
  • phase - This attribute specifies the phase of the event flow that this handler should monitor. The possible values are capturing, bubbling, and target. If a phase is specified, the handler will only be invoked during that phase of the event handling process. If no phase is specified, a default of bubbling is assumed.
  • button - The button attribute imposes a filter on the handler. It is used with mouse handlers to specify a particular button. The event handler will only be matched if the value of the button field in the DOM mouse event object matches the value of the attribute.
  • modifiers - The modifiers attribute imposes a filter on key and mouse handlers. Its value is a whitespace- or comma-separated list of modifier keys. Supported modifiers are shift, alt, control, meta, accel and accesskey. If present in the list, then the modifier key must be set in the DOM event object in order for the handler to be matched. If the handler is filtered and the modifier is not present in the list, then the modifier key must not be set in the DOM event object in order for the handler to be matched. The accel value provides a hint to the user agent that the platform's primary accelerator key should be used. It is left up to the user agent to decide which modifier key represents the primary key. The accesskey value provides a hint to the user agent that the platform's primary shortcut mnemonic key should be used.
  • keycode - The keycode attribute imposes a filter on key handlers. Its value is a key identifier for a specific keycode, e.g., vk_enter.
    {{mediawiki.external('Editor\'s Note: A forthcoming DOM events specification will presumably outline the list of valid keycode strings.')}}
    If this attribute is present, then its value must match the keyCode field of the DOM key event object in order for the handler to fire.
  • charcode - The charcode attribute imposes a filter on key handlers. Its value is a single character, e.g., "z". If this attribute is present, then its value must match the charCode field of the DOM key event object in order for the handler to fire.
    {{mediawiki.external('Editor\'s note: As DOM Events mature more attributes may be added. For example, mutation events define several new fields such as relatedTarget that could be supported in the filtering syntax.')}}
  • key - The key attribute has the same meaning as charcode.
  • clickcount - The clickcount attribute imposes a filter on the handler. It is used with mouse handlers to specify how many times a button has been clicked. The event handler will only be matched if the value of the clickcount field in the DOM mouse event object matches the value of the attribute.
  • command - The id of a command to invoke when the event occurs. If used in a non-chrome document, the entire handler will be ignored.
  • preventdefault - If set to true, the default action of the event is not performed. See also preventDefault method of the Event object.

resources

<!ENTITY % resources-content "(image?,stylesheet?)">
<!ELEMENT resources %resources-content;>
<!ATTLIST property
   id               ID                  #IMPLIED
>

Used for inclusion of image elements, to cache them for later use, and for inclusion of stylesheet elements. The resources tag must be used directly inside the binding tag.

  • id - The id attribute is a document-unique identifier.

stylesheet

<!ELEMENT stylesheet EMPTY>
<!ATTLIST stylesheet
   id               ID                  #IMPLIED
   src              URI                 #REQUIRED
>

The stylesheet element declares a style sheet used by the binding. Using this element is preferred over using an XML processing instruction. The style rules in the style sheet will only be applied to the binding, not to other elements in the document. The stylesheet tag must be inside the resources tag.

  • id - The id attribute is a document-unique identifier.
  • src - The URL of the style sheet to apply to the binding content.

image

<!ELEMENT image EMPTY>
<!ATTLIST image
   id               ID                  #IMPLIED
   src              URI                 #REQUIRED
>

Declares an image resource used by the binding. The image is loaded as soon as the binding is used. You can use this to preload a number of images for later use. The image tag must be inside the resources tag.

  • id - The id attribute is a document-unique identifier.
  • src - The URL of the image to load.

Revision Source

<p>
</p>
<h2 name="bindings">bindings</h2>
<p><span class="comment">This section is tested and adjusted for the current  Firefox implementation. Please edit only if an actual  behavior differs from the described one. Please do not  edit only on the basis of another XBL specification.</span>
</p>
<pre>&lt;!ELEMENT bindings ( binding* ) &gt;

Hierarchy:   root element
May contain: &lt;binding&gt;
</pre>
<p>The <code>bindings</code> element is the root element of any XBL document. It must declare the default namespace and it may declare additional namespaces used in your binding.
</p><p><code>bindings</code> contains zero or more <code><a href="en/XBL/XBL_1.0_Reference/Elements#binding">binding</a></code> elements as children. Each <code><a href="en/XBL/XBL_1.0_Reference/Elements#binding">binding</a></code> child element defines a unique binding that can be attached to elements in other documents.
</p><p>An element can have only one binding attached (explicetly or inherited) at one moment. From several bindings only the last in the sequence will be used (like with any CSS rule).
</p>
<pre>HelloWorld example:

&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Hello world!&lt;/title&gt;
&lt;style type="text/css"&gt;
p {
 -moz-binding: url(hello.xml#default);
}
#p03 {
 -moz-binding: url(hello.xml#hello2);
}
&lt;/style&gt;
&lt;/head&gt;
&lt;body

  &gt;&lt;p&gt;Default content&lt;/p
  &gt;&lt;p&gt;Default content&lt;/p
  &gt;&lt;p id="p03"&gt;Default content&lt;/p

&gt;&lt;/body&gt;
&lt;/html&gt;

// hello.xml

&lt;?xml version="1.0"?&gt;
&lt;bindings xmlns="http://www.mozilla.org/xbl"
 xmlns:html="http://www.w3.org/1999/xhtml"&gt;
  &lt;binding id="default"&gt;
    &lt;content&gt;&lt;html:b&gt;Hello world! &lt;/html:b&gt;&lt;children/&gt;&lt;/content&gt;
  &lt;/binding&gt;
  &lt;binding id="hello2"&gt;
    &lt;content&gt;&lt;html:b&gt;Hello from my binding! &lt;/html:b&gt;&lt;children/&gt;&lt;/content&gt;
  &lt;/binding&gt;
&lt;/bindings&gt;
</pre>
<p><a class="external" href="http://www.nskom.com/external/xbl/mdc/HelloWorld.html">View this example</a>
</p><p>Next: <code><big>bindings &gt; <a href="en/XBL/XBL_1.0_Reference/Elements#binding">binding</a></big></code> element.
</p>
<h3 name="Notes">Notes</h3>
<ul><li> In the current implementation it is impossible to attach bindings to table sub-elements (rows, cells etc.) You can attach binding only to the table element itself. See {{template.Bug(83830)}} for workarounds.
</li><li> Default encoding in XML documents (uncluding XBL files) is UTF-8. An explicit encoding declarations may be present to override the default, for example <code>&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;</code>
</li><li> URI in namespace declarations is an opaque string used to uniquely identify the namespace. It doesn't have to (and often it doesn't) point to some actual schema or a namespace-related resource. <a class="external" href="http://www.w3.org/TR/REC-xml-names/#ns-decl">Namespaces in XML</a>
</li><li> Besides the default namespace, you can declare any amount of additional namespaces to handle your content. The most useful namespaces could be HTML/XHTML, <a href="en/XUL">XUL</a> (XML User Interface Language), <a href="en/SVG">SVG</a> (Scalable Vector Graphics) and <a class="external" href="http://www.w3.org/TR/xlink/">XLink</a>. This way a more-or-less universal namespace declaration in your <code>bindings</code> could be like:
</li></ul>
<pre>&lt;bindings xmlns="http://www.mozilla.org/xbl"
 xmlns:html = "http://www.w3.org/1999/xhtml"
 xmlns:xul  = "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
 xmlns:svg  = "http://www.w3.org/2000/svg"
 xmlns:xlink= "http://www.w3.org/1999/xlink"&gt;
</pre>
<h2 name="binding">binding</h2>
<pre>&lt;!ENTITY % binding-content "(resources?,content?,implementation?,handlers?)"&gt;
&lt;!ELEMENT binding %binding-content;&gt;
&lt;!ATTLIST binding
   id                     ID             #REQUIRED
   extends                CDATA          #IMPLIED
   display                CDATA          #IMPLIED
   inheritstyle           true           #IMPLIED
&gt;
</pre>
<p>The <code>binding</code> element describes a single XBL binding. A XBL binding can add <i><a href="en/XBL/XBL_1.0_Reference/Elements#_content">anonymous content</a></i>, 
<i><a href="en/XBL/XBL_1.0_Reference/Elements#field">fields</a></i>,
<i><a href="en/XBL/XBL_1.0_Reference/Elements#property">properties</a></i>,
<i><a href="en/XBL/XBL_1.0_Reference/Elements#method">methods</a></i>, and <i><a href="en/XBL/XBL_1.0_Reference/Elements#handlers">event handlers</a></i> to HTML/XML elements.
</p><p>A single XBL binding can be attached to an element by using style sheets or by scripting. (See {{template.Bug(83830)}} for &lt;table&gt; specifics).
</p><p>CSS:
</p>
<pre>div {
 -moz-binding: url(myBinding.xml#default);
}
</pre>
<p>DOM:
</p>
<pre>elementReference.style.MozBinding = "url(myBinding.xml#default}";
</pre>
<p>In both cases above we are using binding with <code>id="default"</code> contained in file <code>myBinding.xml</code>
</p><p>Only CSS declarations provide an easy way to attach bindings to any set of elements. It also makes your binding partially functional if scripting is disabled. In the latter case all methods and handlers will be blocked, but the anonymous content and styling will be still used.  Given that the CSS declarations should be always used - unless you need to add bindings at runtime to individual elements.
</p><p>A binding element may contain a <a href="en/XBL/XBL_1.0_Reference/Elements#resources">resources</a> tag, a <a href="en/XBL/XBL_1.0_Reference/Elements#_content">content</a> tag, a <a href="en/XBL/XBL_1.0_Reference/Elements#implementation">implementation</a> tag and a <a href="en/XBL/XBL_1.0_Reference/Elements#handlers">handlers</a> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. For the binding element, this attribute is required, since it is used to attach bindings. 
</li><li> <code><b>extends</b></code> - The <code>extends</code> attribute is used to specify the URL of a binding that this binding inherits from (see <a href="en/XBL/XBL_1.0_Reference/Binding_Implementations#Inheritance_of_Implementations">Inheritance of Implementations</a>). The URL specifies a particular binding document. The # notation must be used to point to a specific binding <code>id</code> within a binding document. Note that content cannot be inherited, only behavior.
</li><li> <code><b>display</b></code> - This attribute specifies how the tag is displayed. By setting this attribute, you can have an element have the layout and display characteristics of an existing element. For example, use the value 'xul:button' to create an element that is displayed like a button. The part before the colon is a namespace prefix so you must declare the XUL namespace as well. Not all tags have a unique display type. The following XUL display types may be used: browser, button, checkbox, description, editor, grippy, iframe, image, label, menu, menuitem, menubar, progressmeter, radio, resizer, scrollbar, scrollbox, spacer, splitter, titlebar, treechildren and treecol. You may also use a number of HTML, MathML and SVG tags. The 'display' attribute does not work unless the <code>extends</code> attribute is set, see bug {{template.Bug(119389)}}. In that case, put the value of the <code>display</code> attribute into the <code>extends</code> attribute.
</li><li> <code><b>inheritstyle</b></code> - The <code>inheritstyle</code> attribute indicates whether style rules from the document will affect anonymous content generated by the XBL binding. If this attribute is true, styles from the document will also be applied to the XBL generated anonymous content.
</li></ul>
<p><span id="_content"></span>
</p>
<h2 name="content"> content</h2>
<pre>&lt;!ELEMENT content ANY&gt;
&lt;!ATTLIST content
   id               ID           #IMPLIED
&gt;
</pre>
<p>A binding can specify new content that is placed inside the bound element.  Although you can see this content on screen as if it was directly in the file, this content is anonymous and is hidden from the normal <a href="en/DOM">DOM</a>. To access anonymous nodes on an XBL bound element, you can use the <a href="en/XBL/XBL_1.0_Reference/DOM_Interfaces#getAnonymousElementByAttribute">getAnonymousElementByAttribute</a> and <a href="en/XBL/XBL_1.0_Reference/DOM_Interfaces#getAnonymousNodes">getAnonymousNodes</a> functions.
The only XBL element that can appear inside the content tag is the <a href="en/XBL/XBL_1.0_Reference/Elements#children">children</a> tag.
</p>
<ul><li> <code><b>id</b></code> - The id attribute is a document-unique identifier.
</li></ul>
<h2 name="children">children</h2>
<pre>&lt;!ELEMENT children EMPTY&gt;
&lt;!ATTLIST children
   id               ID                           #IMPLIED
   includes         CDATA                        #IMPLIED
&gt;
</pre>
<p>Specifies the location where any child elements of the bound element are placed in the generated content.
</p><p>Normally, if the element bound to has its own content, the anonymous content is not generated. However, with a <code>children</code> element, you can merge the content from the HTML/XML element and the XBL content.
</p><p>If the children tag contains content itself, that content will become the default content. If the element the binding is attached to contains content, the default content will be ignored. If the element does not contain content, the default content will be added. 
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. 
</li><li> <code><b>includes</b></code> - The <code>includes</code> attribute can be used to indicate that only certain content should be placed at the insertion point specified by the <code>children</code> element. Its value can be a tag name or multiple tag names separated by commas. A child can only be placed within the insertion point if it is matched by the value in the <code>includes</code> attribute. Only immediate children are matched against the selector.
</li></ul>
<h2 name="implementation">implementation</h2>
<pre>&lt;!ENTITY % implementation-content "(method|property)*"&gt;
&lt;!ELEMENT implementation %implementation-content;&gt;
&lt;!ATTLIST implementation
   id               ID           #IMPLIED
   name             CDATA        #IMPLIED
   implements       CDATA        #IMPLIED
&gt;
</pre>
<p>The <code>implementation</code> element describes the set of methods and properties that are attached to the bound element. Once the binding is attached, these methods and properties can be invoked directly from the bound element.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. 
</li><li> <code><b>name</b></code> - The <code>name</code> 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 JavaScript the value of this attribute represents the name of the corresponding class that is constructed for the implementation. If no name attribute is specified then the binding's document URI and id are used to uniquely reference the binding's implementation. 
</li><li> <code><b>implements</b></code> - The <code>implements</code> attribute can be used to describe the set of interfaces that are implemented by the binding. Its value is a comma-separated list of named interfaces. If supported, in strongly typed languages the bound element can be referenced not only as any of the interfaces that the element might already support (e.g., HTMLElement) but also as any of the interfaces described by this attribute. Support of this capability is optional.
</li></ul>
<h2 name="constructor">constructor</h2>
<p>The code inside the <code>constructor</code> is called when a <code>binding</code> has just been attached to an element. So full access to anonymous nodes generated by the binding is already possible. The <code>constructor</code> tag must be placed inside the <code>implementation</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li><li> <code><b>action</b></code> - The code inside the<code>action</code> attribute is executed. Alternatively, you can put the code inside the <code>constructor</code> element itself.
</li></ul>
<h2 name="destructor">destructor</h2>
<p>The code inside the <code>destructor</code> is called when a <code>binding</code> is being removed from an element. You can use this to unload resources to free memory. However the <code>destructor</code> is often not called when it should, see {{template.Bug(230086)}}. The <code>destructor</code> tag must be placed inside the <code>implementation</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li><li> <code><b>action</b></code> - The code inside the<code>action</code> attribute is executed. Alternatively, you can put the code inside the <code>destructor</code> element itself.
</li></ul>
<h2 name="method">method</h2>
<pre>&lt;!ENTITY % method-content "(parameter*,body?)"&gt;
&lt;!ELEMENT method %method-content;&gt;
&lt;!ATTLIST method
   id               ID           #IMPLIED
   name             CDATA        #REQUIRED
   type             CDATA        #IMPLIED
&gt;
</pre>
<p>The <code>method</code> element is used to describe a single method of a binding implementation.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. 
</li><li> <code><b>name</b></code> - The <code>name</code> attribute's value is the name given to the method when it is attached to the bound element. The method can be invoked directly from the bound element using this value. 
</li></ul>
<p><i>Example</i>
</p>
<pre>&lt;method name="scrollTo"&gt;
  &lt;parameter name="index"/&gt;
  &lt;body&gt;
    this.setAttribute("scrollpos", index);
  &lt;/body&gt;
&lt;/method&gt;
</pre>
<h2 name="parameter">parameter</h2>
<pre>&lt;!ELEMENT parameter EMPTY&gt;
&lt;!ATTLIST parameter
   id               ID           #IMPLIED
   name             CDATA        #REQUIRED
&gt;
</pre>
<p>The <code>parameter</code> element is used inside a <code>method</code> element. It represents a single parameter of a method.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. 
</li><li> <code><b>name</b></code> - The value of the <code>name</code> attribute is used by script within a method's <code>body</code> element to reference this parameter.
</li></ul>
<h2 name="body">body</h2>
<pre>&lt;!ELEMENT body CDATA&gt;
&lt;!ATTLIST body
   id               ID           #IMPLIED
&gt;
</pre>
<p>The <code>body</code> element represents the implementation of its corresponding <code>method</code>. Its contents are the script that is executed when the method is invoked.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li></ul>
<h2 name="field">field</h2>
<p>A field is similar to a <code><a href="en/XBL/XBL_1.0_Reference/Elements#property">property</a></code>, except that it should not have a getter or setter. It is useful as a simple holder for a value. The field element may have content which is code that determines the initial value of the field. The <code>field</code> tag must be inside the <code>implementation</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. 
</li><li> <code><b>name</b></code> - The name of the field. This is the name used to refer to the field on the bound element. 
</li></ul>
<h2 name="property">property</h2>
<pre>&lt;!ENTITY % property-content "(getter?,setter?)|#PCDATA"&gt;
&lt;!ELEMENT property %property-content;&gt;
&lt;!ATTLIST property
   id               ID                  #IMPLIED
   name             CDATA               #REQUIRED
   readonly         (true|false)        #IMPLIED
   onget            CDATA               #IMPLIED
   onset            CDATA               #IMPLIED
&gt;
</pre>
<p>The <code>property</code> element represents a single property of an implementation. A property consists of a pair of getter/setter functions that can be defined using <code>onget</code>/<code>onset</code> attributes or <a href="en/XBL/XBL_1.0_Reference/Elements#getter">getter</a>/<a href="en/XBL/XBL_1.0_Reference/Elements#setter">setter</a> elements underneath the <code>property</code> element. Like methods, once the binding is attached, the property can be obtained directly from the bound element.
The <code>property</code> tag must be inside the <code>implementation</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. 
</li><li> <code><b>name</b></code> - The name of the property. This is the name used to refer to the property on the bound element.
</li><li> <code><b>readonly</b></code> - The <code>readonly</code> attribute is used to designate a property as read-only. If set to <code>true</code>, the value of the property cannot be altered. If this attribute is omitted, the property will be readable and writable. 
</li><li> <code><b>onget</b></code> - The <code>onget</code> attribute's value is a script that executes when the value of the property is requested. If this attribute is set, any initial value contained underneath the element will be ignored. The return value of the script represents the value of the property that will be returned to the requestor. A property getter can also be specified as a child of the <code>property</code> element using the <code>getter</code> tag. 
</li><li> <code><b>onset</b></code> - The <code>onset</code> attribute's value is a script that executes when the value of the property is being altered. If this attribute is set, any initial value contained underneath the element will be ignored. Within the script, the parameter <code>val</code> represents the new value being assigned. The script should always return the actual value assigned in order to allow for chained assignment operations. A property setter can also be specified as a child of the <code>property</code> element using a <code>setter</code> tag.
</li></ul>
<h2 name="getter">getter</h2>
<pre>&lt;!ELEMENT getter PCDATA&gt;
&lt;!ATTLIST getter
   id               ID                  #IMPLIED
&gt;
</pre>
<p>The <code>getter</code> element contains script that gets executed when a specific property gets called. The <code>getter</code> tag must be inside the <code>property</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li></ul>
<h2 name="setter">setter</h2>
<pre>&lt;!ELEMENT setter PCDATA&gt;
&lt;!ATTLIST setter
   id               ID                  #IMPLIED
&gt;
</pre>
<p>The <code>setter</code> element contains script that gets executed when a specific property is being set. The <code>setter</code> tag must be inside the <code>property</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li></ul>
<h2 name="handlers">handlers</h2>
<pre>&lt;!ENTITY % handlers-content "handler*"&gt;
&lt;!ELEMENT handlers %handlers-content;&gt;
&lt;!ATTLIST handlers
   id               ID                  #IMPLIED
&gt;
</pre>
<p>The <code>handlers</code> element contains event handlers that can be attached to elements within the bound document. These handlers are installed when the binding is attached and removed when the binding is detached. The <code>handlers</code> tag must be inside the <code>binding</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li></ul>
<h2 name="handler">handler</h2>
<pre>&lt;!ENTITY % handler-content "PCDATA"&gt;
&lt;!ELEMENT handler %handler-content;&gt;
&lt;!ATTLIST handler
   id               ID                                  #IMPLIED
   event            NMREF                               #REQUIRED
   action           CDATA                               #IMPLIED
   phase            (capturing|bubbling|target)         #IMPLIED
   button           (1|2|3)                             #IMPLIED
   modifiers        CDATA                               #IMPLIED
   keycode          CDATA                               #IMPLIED
   key              CDATA                               #IMPLIED
   charcode         CDATA                               #IMPLIED
   clickcount       (1|2|3)                             #IMPLIED
   command          ID                                  #IMPLIED
   preventdefault   false|true                          #IMPLIED
&gt;
</pre>
<p>The <code>handler</code> element describes a single event handler. This handler is attached to its target at the time the binding is attached and unhooked when the binding is detached from the bound element. The script inside the <code>handler</code> is executed when the event handler is matched. The <code>handler</code> tag must be inside the <code>handlers</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier. 
</li><li> <code><b>event</b></code> - The <code>event</code> attribute describes the specific event that this handler is listening for. Its value can be any legal DOM event name (including custom events created using the DocumentEvent interface of the DOM).
</li><li> <code><b>action</b></code> - The <code>action</code> attribute contains script that is invoked when the handler fires. The <code>type</code> attribute on the enclosing <code>handlers</code> element determines the language of the script. The handler script can also be specified as a child of the <code>handler</code> element. 
</li><li> <code><b>phase</b></code> - This attribute specifies the phase of the event flow that this handler should monitor. The possible values are <code>capturing</code>, <code>bubbling</code>, and <code>target</code>. If a phase is specified, the handler will only be invoked during that phase of the event handling process. If no phase is specified, a default of <code>bubbling</code> is assumed. 
</li><li> <code><b>button</b></code> - The <code>button</code> attribute imposes a <i>filter</i> on the handler. It is used with mouse handlers to specify a particular button. The event handler will only be matched if the value of the <code>button</code> field in the DOM mouse event object matches the value of the attribute. 
</li><li> <code><b>modifiers</b></code> - The <code>modifiers</code> attribute imposes a filter on key and mouse handlers. Its value is a whitespace- or comma-separated list of modifier keys. Supported modifiers are <code>shift</code>, <code>alt</code>, <code>control</code>, <code>meta</code>, <code>accel</code> and <code>accesskey</code>. If present in the list, then the modifier key must be set in the DOM event object in order for the handler to be matched. If the handler is filtered and the modifier is not present in the list, then the modifier key must not be set in the DOM event object in order for the handler to be matched. The <code>accel</code> value provides a hint to the user agent that the platform's primary accelerator key should be used. It is left up to the user agent to decide which modifier key represents the primary key. The <code>accesskey</code> value provides a hint to the user agent that the platform's primary shortcut mnemonic key should be used. 
</li><li> <code><b>keycode</b></code> - The <code>keycode</code> attribute imposes a filter on key handlers. Its value is a key identifier for a specific keycode, e.g., <code>vk_enter</code>.<br> <i>{{mediawiki.external('Editor\'s Note: A forthcoming DOM events specification will presumably outline the list of valid keycode strings.')}}</i><br> If this attribute is present, then its value must match the <a href="en/DOM/event.keyCode">keyCode</a> field of the DOM key event object in order for the handler to fire. 
</li><li> <code><b>charcode</b></code> - The <code>charcode</code> attribute imposes a filter on key handlers. Its value is a single character, e.g., "<code>z</code>". If this attribute is present, then its value must match the <a href="en/DOM/event.charCode">charCode</a> field of the DOM key event object in order for the handler to fire.<br> <i>{{mediawiki.external('Editor\'s note: As DOM Events mature more attributes may be added. For example, mutation events define several new fields such as relatedTarget that could be supported in the filtering syntax.')}}</i>
</li><li> <code><b>key</b></code> - The <code>key</code> attribute has the same meaning as <code>charcode</code>.
</li><li> <code><b>clickcount</b></code> - The <code>clickcount</code> attribute imposes a <i>filter</i> on the handler. It is used with mouse handlers to specify how many times a button has been clicked. The event handler will only be matched if the value of the <code>clickcount</code> field in the DOM mouse event object matches the value of the attribute.
</li><li> <code><b>command</b></code> - The id of a command to invoke when the event occurs. If used in a non-chrome document, the entire handler will be ignored.
</li><li> <code><b>preventdefault</b></code> - If set to true, the default action of the event is not performed. See also <a href="en/DOM/event.preventDefault">preventDefault</a> method of the Event object.
</li></ul>
<h2 name="resources">resources</h2>
<pre>&lt;!ENTITY % resources-content "(image?,stylesheet?)"&gt;
&lt;!ELEMENT resources %resources-content;&gt;
&lt;!ATTLIST property
   id               ID                  #IMPLIED
&gt;
</pre>
<p>Used for inclusion of <a href="en/XBL/XBL_1.0_Reference#image">image</a> elements, to cache them for later use, and for inclusion of <a href="en/XBL/XBL_1.0_Reference#stylesheet">stylesheet</a> elements.
The <code>resources</code> tag must be used directly inside the <code>binding</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li></ul>
<h2 name="stylesheet">stylesheet</h2>
<pre>&lt;!ELEMENT stylesheet EMPTY&gt;
&lt;!ATTLIST stylesheet
   id               ID                  #IMPLIED
   src              URI                 #REQUIRED
&gt;
</pre>
<p>The <code>stylesheet</code> element declares a style sheet used by the binding. Using this element is preferred over using an XML processing instruction. The style rules in the style sheet will only be applied to the binding, not to other elements in the document. The <code>stylesheet</code> tag must be inside the <code>resources</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li><li> <code><b>src</b></code> - The URL of the style sheet to apply to the binding content.
</li></ul>
<h2 name="image">image</h2>
<pre>&lt;!ELEMENT image EMPTY&gt;
&lt;!ATTLIST image
   id               ID                  #IMPLIED
   src              URI                 #REQUIRED
&gt;
</pre>
<p>Declares an image resource used by the binding. The image is loaded as soon as the binding is used. You can use this to preload a number of images for later use.  The <code>image</code> tag must be inside the <code>resources</code> tag.
</p>
<ul><li> <code><b>id</b></code> - The <code>id</code> attribute is a document-unique identifier.
</li><li> <code><b>src</b></code> - The URL of the image to load.
</li></ul>
Revert to this revision