Annotation of books/www/chapters/ch07.html, revision 1.8

1.8     ! petejc      1:     <style type="text/css">
        !             2:       div.c19 {font-weight: bold; text-align: center}
        !             3:       div.c18 {text-align: center}
        !             4:     </style>
        !             5:     <h2>Chapter 7</h2>
        !             6: 
        !             7:     <h1><a name="77027"></a> Extending the UI with XBL</h1>
        !             8:     <p>You now know that XUL is the basic tool set for creating
        !             9:     your application interface, but even it has limitations. It is
        !            10:     just a finite set of widgets that your programming needs may
        !            11:     transcend. If you find that you reimplement many of the same
        !            12:     groups of widgets in different applications, or if you want to 
        !            13:     <!--INDEX XBL (eXtensible Binding Language) --> extend your
        !            14:     application's interface in some other way, you will find the
        !            15:     eXtensible Binding Language (XBL) an invaluable tool.</p>
        !            16:     <p>This chapter describes what XBL is and how it is used.
        !            17:     Basically, XBL provides a way to attach new content or behavior
        !            18:     to your application by using XBL bindings. XBL can extend, add
        !            19:     to, and reorganize user interfaces. XBL can also help you
        !            20:     organize scattered XUL code into a set of self-contained
        !            21:     widgets that make building and maintaining your Mozilla
        !            22:     application much easier. <a href="appc.html#77003">Appendix
        !            23:     C</a> provides a reference for the XBL element set, with which
        !            24:     new elements can be created.</p>
        !            25:     <h2><a name="77028"></a> What Is XBL?</h2>
        !            26:     <p>XBL is an XML markup 
        !            27:     <!--INDEX XBL (eXtensible Binding Language):overview -->
        !            28:     language invented specifically for creating widgets. XBL looks
        !            29:     similar to XUL, and may even contain XUL or HTML and other
        !            30:     markup (see the <a href="#77031">"Namespaces and XBL</a>"
        !            31:     section later in this chapter for more information about how
        !            32:     other markup is used in XBL bindings), but its purpose is
        !            33:     different. Flexibility and interoperability are the point of
        !            34:     XBL.</p>
        !            35:     <p>If the XUL <tt>textbox</tt> is inadequate, for example, you
        !            36:     can use XBL to create and attach a new widget called
        !            37:     <tt>&lt;datafield/&gt;</tt>, possibly based on
        !            38:     <tt>textbox</tt>, that provides special attributes and
        !            39:     functionality for validating input data against a database.</p>
        !            40:     <p>A <i>binding</i> is a single XBL language 
        !            41:     <!--INDEX bindings --> entity that can contain content as other
        !            42:     markup (such as XUL) behavior that is represented as methods
        !            43:     and properties, and event-handling capabilities. Bindings can
        !            44:     be anything from small widget objects to large, complex blocks
        !            45:     of code with extensive functionality. <a href="#77002">Figure
        !            46:     7-1</a> shows the different components that make up a binding:
        !            47:     fields, properties, functions, event handlers, and content. The
        !            48:     section <a href="#77033">"Anatomy of a Binding</a>," later in
        !            49:     this chapter, provides more detail about a binding's
        !            50:     structure.</p>
        !            51:     <div class="c18">
        !            52:       <img src="foo.gif">
        !            53:     </div>
        !            54:     <p><i>Figure 7-1: <a name="77002"></a></i> <i>Mozilla XBL
        !            55:     binding structure</i></p>
        !            56:     <p>Bindings differ from XUL overlays because they are fully
        !            57:     self-contained, reusable, and generally have no dependencies
        !            58:     outside of the binding itself. Although XUL is used most often
        !            59:     as content in an XBL binding, XBL can also bind to and from
        !            60:     HTML and XML. If you have worked with Java or C#, you may
        !            61:     recognize some parallels between XBL bindings and Java
        !            62:     objects.</p>
        !            63:     <h3><a name="77029"></a> XBL Terminology</h3>
        !            64:     <p>The following terms are used to describe XBL and its use in
        !            65:     the XPFE:</p>
        !            66:     <dl>
        !            67:       <dt>XBL</dt>
        !            68:       <dd>An acronym for 
        !            69:       <!--INDEX XBL (eXtensible Binding Language) --> the
        !            70:       eXtensible Binding Language. In some contexts, the term XBL
        !            71:       refers to actual code (e.g., "the XBL in this example . . .
        !            72:       "). XBL is an XML syntax.</dd>
        !            73:       <dt>Binding</dt>
        !            74:       <dd>A single unit of <!--INDEX bindings:XBL --> the XBL
        !            75:       language, one 
        !            76:       <!--INDEX XBL (eXtensible Binding Language):bindings --> or
        !            77:       more of which is contained in a binding document. Most
        !            78:       bindings are made up of content and implementation, although
        !            79:       each are mutually exclusive; if you add event handlers to
        !            80:       that list, each one can appear on its own in a binding.</dd>
        !            81:       <dt>Binding document</dt>
        !            82:       <dd>An XBL file with an <i>.xml</i> extension 
        !            83:       <!--INDEX binding documents, XBL --> that 
        !            84:       <!--INDEX XBL (eXtensible Binding Language):binding documents -->
        !            85:       contains one or more bindings.</dd>
        !            86:       <dt>Bound document</dt>
        !            87:       <dd>A XUL (or HTML) document 
        !            88:       <!--INDEX bound documents, XBL --> that 
        !            89:       <!--INDEX XBL (eXtensible Binding Language):bound documents -->
        !            90:       has one or more bindings attached to it as content.</dd>
        !            91:       <dt>Bound element</dt>
        !            92:       <dd>A bound element is a widget 
        !            93:       <!--INDEX bound elements:XBL;elements:bound elements:XBL -->
        !            94:       or 
        !            95:       <!--INDEX XBL (eXtensible Binding Language):bound elements -->
        !            96:       element that uses a particular binding. It can be an existing
        !            97:       element in the XUL or HTML set or a newly invented one.</dd>
        !            98:       <dt>Anonymous content</dt>
        !            99:       <dd>Content (e.g., XUL elements) 
        !           100:       <!--INDEX anonymous content, XBL --> 
        !           101:       <!--INDEX XBL (eXtensible Binding Language):anonymous content -->
        !           102:       contained in a binding that is hidden from the document
        !           103:       object (DOM). Refer to the section <a href="#77047">"XBL and
        !           104:       the DOM</a>," later in this chapter, for a more detailed
        !           105:       discussion of its characteristics and how to programmatically
        !           106:       gain access to the content.</dd>
        !           107:       <dt>Attachment and detachment</dt>
        !           108:       <dd>Attachment is the process through 
        !           109:       <!--INDEX attachment, XBL;XBL (eXtensible Binding Language):attachment -->
        !           110:       which a 
        !           111:       <!--INDEX detachment, XBL;XBL (eXtensible Binding Language):detachment -->
        !           112:       binding is associated with a bound element. It is essentially
        !           113:       a way of telling the element which binding to use. Detachment
        !           114:       is the process of removing that link and with it, the binding
        !           115:       display.</dd>
        !           116:       <dt>Insertion point</dt>
        !           117:       <dd>The point in anonymous content at which 
        !           118:       <!--INDEX insertion point, XBL;XBL (eXtensible Binding Language):insertion point -->
        !           119:       children of the bound element are inserted. The section <a
        !           120:       href="#77057">"Extra Binding Content and Insertion
        !           121:       Points</a>," later in this chapter, details the insertion
        !           122:       process.</dd>
        !           123:       <dt>Inheritance</dt>
        !           124:       <dd>During inheritance, characteristics of one object 
        !           125:       <!--INDEX inheritance:XBL;XBL (eXtensible Binding Language):inheritance -->
        !           126:       are passed on to another object. In XBL, this process is
        !           127:       multifaceted. Bindings can inherit from other bindings,
        !           128:       anonymous content can inherit attributes from the bound
        !           129:       element, and a binding implementation can inherit the
        !           130:       behavior of another widget. All concepts are explained in the
        !           131:       section <a href="#77060">"Inheritance</a>," later in this
        !           132:       chapter.</dd>
        !           133:     </dl>
        !           134:     <h3><a name="77030"></a> An XBL Document</h3>
        !           135:     <p>XBL documents are files saved 
        !           136:     <!--INDEX XBL documents;documents:XBL documents --> with an
        !           137:     <i>.xml</i> filename extension. Most bindings implement XUL
        !           138:     content and behavior with script, so XBL files reside in your
        !           139:     XUL application's chrome content area and have full access to
        !           140:     XPConnect-wrapped XPCOM objects.</p>
        !           141:     <p>Several bindings often reside inside the same XBL file.
        !           142:     Performance benefits from this arrangement, if you have
        !           143:     multiple related bindings, because only one XBL document needs
        !           144:     to be loaded, rather than multiple documents. Organization is
        !           145:     another factor. Mozilla has dozens of bindings that are
        !           146:     interrelated by either inheritance or filename identifiers.
        !           147:     Individual pieces to a menu widget reside in a file called
        !           148:     <i>menu.xml</i>, button bindings are in <i>button.xml</i>, and
        !           149:     so forth. Keeping these bindings together is wise.</p>
        !           150:     <p>The XBL document's root container is the <tt>
        !           151:     <!--INDEX bindings element, XBL --> &lt;bindings&gt;</tt> tag.
        !           152:     Inside this element is one or more individual child bindings,
        !           153:     defined by the <tt>&lt;binding&gt;</tt> tag. A simple XBL
        !           154:     document is as follows:</p>
        !           155: <pre>
        !           156: &lt;?xml version="1.0"?&gt;
1.1       david     157: &lt;bindings id="dataBindings" ...&gt;
                    158: &lt;binding /&gt;
                    159: &lt;binding /&gt;
1.8     ! petejc    160: &lt;/bindings&gt;
        !           161: </pre>
        !           162:     <p>An XBL document is 
        !           163:     <!--INDEX XML documents;XBL documents;XBL documents:XML documents -->
        !           164:     a valid XML document. The XML preamble you are used to seeing
        !           165:     in XUL files is present. It also contains the single root
        !           166:     element (in this case, <tt>&lt;bindings&gt;</tt>) and the child
        !           167:     nodes that define the bindings (empty).</p>
        !           168:     <p>Bindings are the 
        !           169:     <!--INDEX bindings:XBL:XBL documents;XBL documents:bindings -->
        !           170:     atomic units of an XBL document. An XBL document may define any
        !           171:     number of individual bindings, each of which is bound (i.e.,
        !           172:     associated with other XML/XUL elements by way of CSS class
        !           173:     definitions) somewhere in the interface. In other words, an XBL
        !           174:     document may be a set of unrelated or barely related bindings
        !           175:     that are picked up by the XUL interface.</p>
        !           176:     <h3><a name="77031"></a> Namespaces and XBL</h3>
        !           177:     <p>Because XBL is 
        !           178:     <!--INDEX namespaces:XBL and;XBL (eXtensible Binding Language):namespaces -->
        !           179:     a binding language for other markup, remember to distinguish
        !           180:     between the XBL markup (such as <tt>&lt;binding&gt;</tt> and
        !           181:     <tt>&lt;handler&gt;</tt>) and markup from another language
        !           182:     (such as XUL). Namespaces are a feature of the XML language
        !           183:     that was invented to handle this separation of intermingled
        !           184:     markup, and XBL uses namespaces. For more information on
        !           185:     namespaces, refer to the W3C at <i><a href=
        !           186:     "http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a></i>.</p>
        !           187:     <p>Namespaces are declared in the root element of an XML
        !           188:     document. The most common implementation is the declaration of
        !           189:     two namespaces: a default namespace for XBL and a namespace for
        !           190:     the other markup. This code shows the root of a bindings
        !           191:     document in which the XUL namespace declaration
        !           192:     (<tt>xmlns:xul</tt>) and the XBL default namespace are
        !           193:     declared:</p>
        !           194: <pre>
        !           195: &lt;bindings id="dataBindings"
        !           196: xmlns=<a href=
        !           197: "http://www.mozilla.org/xbl">http://www.mozilla.org/xbl</a>
1.1       david     198: xmlns:xul=
1.8     ! petejc    199: <a href=
        !           200: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul%3E">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul&gt;</a>;
        !           201: </pre>
        !           202:     <p>An <i>NCName</i> is the 
        !           203:     <!--INDEX NCName, namespace declaration and --> part of a
        !           204:     namespace declaration that qualifies the markup type for that
        !           205:     particular namespace. It is placed after a colon, and in many
        !           206:     XPFE documents, is the markup language name (<tt>xul</tt>,
        !           207:     <tt>xbl</tt>, or <tt>rdf</tt>). The XBL namespace is the
        !           208:     default in this instance because it does not declare a
        !           209:     namespace prefix (<tt>NCName</tt>).</p>
        !           210:     <p>You can choose to namespace your document in a different
        !           211:     way. For example, if you have a large mass of XUL code in your
        !           212:     binding and do not wish to use the <tt>xul</tt>: prefix
        !           213:     repeatedly, you can declare the XBL namespace as
        !           214:     <tt>xmlns:xbl</tt>; you won't need to use prefixes on the XUL
        !           215:     content since it is set as the default. Another option is to
        !           216:     namespace a parent element:</p>
        !           217: <pre>
        !           218: &lt;box xmlns="<a href=
        !           219: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
        !           220: </pre>
        !           221:     <p>This code enables all children inside the
        !           222:     <tt>&lt;box&gt;</tt> to be in the scope of the XUL namespace;
        !           223:     therefore the explicit <tt>xul</tt>: tag prefix declaration is
        !           224:     not necessary.</p>
        !           225:     <h3><a name="77032"></a> XBL and HTML</h3>
        !           226:     <p>Although XUL usually makes 
        !           227:     <!--INDEX XBL (eXtensible Binding Language):HTML and;HTML (Hypertext Markup Language):XBL and -->
        !           228:     up the content of an XBL binding in Mozilla, HTML is another
        !           229:     valid and popular binding format. Using the XBL with HTML
        !           230:     combination can be advantageous. With it, web pages (rendered
        !           231:     in Mozilla) can be more feature-rich and move beyond the
        !           232:     limitations of the HTML specification's finite element set. It
        !           233:     means a possible mingling of one or many markup languages,
        !           234:     including HTML, XUL, and RDF.</p>
        !           235:     <p>The following snippet, in which a simple binding defines the
        !           236:     name of the browser in an HTML <tt>div</tt>, gives you a feel
        !           237:     for its potential:</p>
        !           238: <pre>
        !           239: &lt;binding id="browser"&gt;
1.1       david     240: &lt;content&gt;
                    241: &lt;html:div&gt;Mozilla 1.0&lt;/html:div&gt;
                    242: &lt;children /&gt;
                    243: &lt;/content&gt;
1.8     ! petejc    244: &lt;/binding&gt;
        !           245: </pre>
        !           246:     <p>The bound element in HTML is called <tt>browser_name</tt>
        !           247:     and is attached to the anonymous content in the HTML document's
        !           248:     inline style.</p>
        !           249: <pre>
        !           250: &lt;head&gt;
1.1       david     251: &lt;title&gt;Browser Information&lt;/title&gt;
                    252: &lt;style&gt;
                    253: browser_name  {
                    254: -moz-binding: url("brand.xml#browser");
                    255: }
                    256: &lt;/style&gt;
                    257: &lt;/head&gt;
                    258: &lt;body&gt;
                    259: &lt;h1&gt;&lt;browser_name /&gt; Guide&lt;/h1&gt;
1.8     ! petejc    260: ...
        !           261: </pre>
        !           262:     <p>Although the <tt>&lt;browser_name/&gt;</tt> element is not a
        !           263:     valid HTML element, one of XBL's great capabilities is that
        !           264:     Mozilla finds the binding, reads the content there, and makes
        !           265:     the substitution. The browser name can be included in several
        !           266:     places in the HTML document. Like a poor man's DTD, the binding
        !           267:     lets you change the definition of <tt>browser_name</tt> in one
        !           268:     place and propagate that change to every instance of its use.
        !           269:     This feature is useful because it requires the touching of
        !           270:     fewer files during code maintenance.</p>
        !           271:     <h2><a name="77033"></a> Anatomy of a Binding</h2>
        !           272:     <p>The best way to understand a binding 
        !           273:     <!--INDEX bindings:XBL --> is 
        !           274:     <!--INDEX XBL (eXtensible Binding Language):bindings --> to
        !           275:     watch one evolve from start to finish. This section examines a
        !           276:     binding from its inception, into the construction of the
        !           277:     binding, and through its use in a XUL document. At the end of
        !           278:     the section, you should be able to take the pieces and
        !           279:     construct your own binding, so try to follow it like a
        !           280:     step-by-step guide.</p>
        !           281:     <p>Design is important in XBL. The implementation can sometimes
        !           282:     be tricky; for example, when you intend to reuse the binding
        !           283:     elsewhere or when others use it in a way you don't foresee.
        !           284:     Ideally, a binding should be as small as possible to facilitate
        !           285:     reuse. And it's a good idea to separate your binding into
        !           286:     smaller pieces-perhaps smaller "subbindings"-so you can
        !           287:     recombine when necessary. You could design the
        !           288:     <tt>&lt;datafield/&gt;</tt> widget mentioned in the
        !           289:     introduction-for example, as a combination of the XUL
        !           290:     <tt>&lt;textfield/&gt;</tt> widget and your own new binding,
        !           291:     <tt>&lt;validator/&gt;</tt>, which you could then use
        !           292:     elsewhere.</p>
        !           293:     <p>The widget constructed in this section is a good example of
        !           294:     a small, reusable binding. It is a special text input widget
        !           295:     called <tt>inputfield-</tt>a self-contained extension to a XUL
        !           296:     textbox that can be used on its own or as part of another
        !           297:     binding. The binding combines a <tt>
        !           298:     <!--INDEX label element, XUL --> &lt;label&gt;</tt> and a <tt>
        !           299:     <!--INDEX textbox element, XUL --> &lt;textbox&gt;</tt>, allows
        !           300:     child elements, and offers functions that work with the data
        !           301:     and style of the <tt>&lt;textbox&gt;</tt>.</p>
        !           302:     <h3><a name="77034"></a> CSS Attachment</h3>
        !           303:     <p><i>Attachment</i> is the process 
        !           304:     <!--INDEX attachment, XBL:CSS;XBL (eXtensible Binding Language):attachment:CSS;CSS (Cascading Style Sheets):attachment, XBL -->
        !           305:     through which the binding is connected to the bound document
        !           306:     that uses it. This process is most commonly achieved through
        !           307:     CSS, but can also be done by using the DOM. The section <a
        !           308:     href="#77047">"XBL and the DOM</a>," later in this chapter,
        !           309:     details the interaction between XBL and the document object
        !           310:     model. The CSS connection begins where the bound element is
        !           311:     placed in the XUL file:</p>
        !           312: <pre>
        !           313: &lt;inputfield/&gt;
        !           314: </pre>
        !           315:     <p>Remember that XML ignores 
        !           316:     <!--INDEX XML (Extensible Markup Language):elements, ignoring -->
        !           317:     elements it doesn't recognize, so this new element won't be
        !           318:     rendered until you add information to the stylesheet; a binding
        !           319:     is attached with the special <tt>-moz-binding</tt> attribute.
        !           320:     The style selector must be associated with the bound element in
        !           321:     the XUL file. In the following example, the binding is attached
        !           322:     to every <tt>&lt;inputfield&gt;</tt> tag because the element
        !           323:     name itself is used as the style selector. However,
        !           324:     <tt>-moz-binding</tt> can also be inside a class selector, an
        !           325:     ID selector, or any other CSS selector you wish to use:</p>
        !           326: <pre>
        !           327: inputfield {
1.1       david     328: -moz-binding: url("inputfield.xml#inputfield");
1.8     ! petejc    329: }
        !           330: </pre>
        !           331:     <p>It also can be from an inline style:</p>
        !           332: <pre>
        !           333: &lt;inputfield
1.1       david     334: id="ifd"
1.8     ! petejc    335: style="-moz-binding: url("inputfield.xml#inputfield")"/&gt;
        !           336: </pre>
        !           337:     <p>The constituent parts of this style rule are the
        !           338:     <tt>-moz-binding</tt> property, the <tt>url</tt> binding
        !           339:     locator that takes the bindings file (and possibly the path to
        !           340:     it) as a parameter, and the <tt>id</tt> of the binding denoted
        !           341:     with the <tt>#</tt> notation. For the binding to take, the XBL
        !           342:     file must contain a binding with the same <tt>id</tt>.</p>
        !           343: <pre>
        !           344: &lt;binding id="inputfield"&gt;
1.1       david     345: &lt;!-- binding content / behavior / handlers --&gt;
1.8     ! petejc    346: &lt;/binding&gt;
        !           347: </pre>
        !           348:     <p>The ID of <tt>inputfield</tt> matches the value specified in
        !           349:     the URL after the <tt>#</tt> symbol. When the UI is drawn in
        !           350:     Mozilla, the binding content, behavior, and handlers are
        !           351:     applied to the bound document at the point where the <tt>
        !           352:     <!--INDEX inputfield element, XBL --> &lt;inputfield&gt;</tt>
        !           353:     element appears in the document. <a href="#77004">Figure
        !           354:     7-2</a> shows a visual representation of the constituent parts
        !           355:     of a binding attachment occurring via CSS.</p>
        !           356:     <div class="c18">
        !           357:       <img src="foo.gif">
        !           358:     </div>
        !           359:     <p><i>Figure 7-2: <a name="77004"></a></i> <i>CSS binding
        !           360:     attachment components</i></p>
        !           361:     <p>In this example, we use our own new element name called
        !           362:     <tt>&lt;inputfield&gt;</tt>, but you can also extend existing
        !           363:     XUL widgets by including:</p>
        !           364: <pre>
        !           365: &lt;box id="inputfield" flex="1"/&gt;
        !           366: </pre>
        !           367:     <p>Because they are bound through CSS, bindings cannot be
        !           368:     guaranteed to be loaded until the whole document is loaded,
        !           369:     which means that any inline scripts accessing bindings should
        !           370:     be considered incorrect because you cannot guarantee that the
        !           371:     binding is loaded.</p>
        !           372:     <p>XBL content 
        !           373:     <!--INDEX XBL (eXtensible Binding Language):invisible content -->
        !           374:     is considered "invisible" in the context of the document object
        !           375:     because it is not contained directly in the XUL document. Refer
        !           376:     to the later section <a href="#77047">"XBL and the DOM</a>" for
        !           377:     more information on this concept.</p>
        !           378:     <blockquote>
        !           379:       <div class="c19">
        !           380:         NOTE
        !           381:       </div>
        !           382:       <p>Because a document binding can have multiple instances,
        !           383:       something must happen to make the content unique in each one.
        !           384:       When a binding is attached to a document, its content is
        !           385:       automatically cloned in memory. Every instance of a binding
        !           386:       shares the same fields, properties, methods, and event
        !           387:       handlers because separate copies of those are simply not
        !           388:       necessary. These elements cannot be changed dynamically, but
        !           389:       the content document model can.</p>
        !           390:     </blockquote>
        !           391:     <h3><a name="77035"></a> The XBL Content Element</h3>
        !           392:     <p>The <tt><!--INDEX binding element, XBL -->
        !           393:     &lt;binding&gt;</tt> element 
        !           394:     <!--INDEX XBL (eXtensible Binding Language):content element;content element, XBL -->
        !           395:     requires an <tt>id</tt> attribute to make the binding unique
        !           396:     within the entire document. In the general XML specification,
        !           397:     there can only be one element in a document that has a certain
        !           398:     ID string. As in XUL, if you use an ID twice, the last one
        !           399:     parsed is the only one seen. This situation can lead to
        !           400:     unexpected behavior. <a href="#77006">Figure 7-3</a> shows the
        !           401:     appearance of an <tt>inputfield</tt> binding.</p>
        !           402:     <div class="c18">
        !           403:       <img src="foo.gif">
        !           404:     </div>
        !           405:     <p><i>Figure 7-3: <a name="77006"></a></i> <i>The inputfield
        !           406:     alone in the XUL document</i></p>
        !           407:     <p>An <tt><!--INDEX inputfield element, XBL -->
        !           408:     &lt;inputfield&gt;</tt> has a <tt>&lt;label&gt;</tt> attached 
        !           409:     <!--INDEX XBL (eXtensible Binding Language):input --> to it,
        !           410:     shown here as "Input Field." It also has a regular
        !           411:     <tt>&lt;textbox&gt;</tt>. The "Eric's" label is not part of the
        !           412:     binding, but is still displayed inside of it as a child. Child
        !           413:     content is discussed later in the section "Extra Binding
        !           414:     Content and Insertion Points." The binding content is defined
        !           415:     as:</p>
        !           416: <pre>
        !           417: &lt;content&gt;
1.1       david     418: &lt;children/&gt;
                    419: &lt;xul:label xbl:inherits="value=label"/&gt;
                    420: &lt;xul:textbox anonid="input" flex="1"/&gt;
1.8     ! petejc    421: &lt;/content&gt;
        !           422: </pre>
        !           423:     <p><tt>&lt;children/&gt;</tt>, the first element in the
        !           424:     binding, lets any elements that existed in the original XUL
        !           425:     document pass through the binding's display if it exists inside
        !           426:     the <tt>&lt;inputfield&gt;</tt> tag.</p>
        !           427: <pre>
        !           428: &lt;inputfield id="ifd" label="Input Field"&gt;
1.1       david     429: &lt;label value="Eric's"/&gt;
1.8     ! petejc    430: &lt;/inputfield&gt;
        !           431: </pre>
        !           432:     <p>In this case, the XUL label is inserted into the anonymous
        !           433:     content at the point of the <tt>&lt;children/&gt;</tt> element
        !           434:     when the binding is rendered. This ability is useful for
        !           435:     changing the ordering of content and adding extra content
        !           436:     within a binding.</p>
        !           437:     <blockquote>
        !           438:       <div class="c19">
        !           439:         NOTE
        !           440:       </div>
        !           441:       <p>You can limit which tags are displayed as child content by
        !           442:       using something like:</p>
        !           443:     </blockquote>
        !           444:     &lt;children includes="treehead|treechildren"/&gt; 
        !           445:     <blockquote>
        !           446:       <p>These filtering capabilities open the possibility of
        !           447:       multiple <tt>&lt;children/&gt;</tt> in your binding.</p>
        !           448:     </blockquote>
        !           449:     <p>The next content element is <tt>&lt;xul:label/&gt;</tt>.
        !           450:     Notice how the XML namespace of <tt>xul</tt> is used in the
        !           451:     content. Using this notation is the most common way to apply
        !           452:     namespace XUL elements in bindings.</p>
        !           453:     <p>The <tt>label</tt> element has an XBL-namespaced
        !           454:     <tt>inherits</tt> attribute. This code translates an attribute
        !           455:     used on the original bounded tag into something usable by a
        !           456:     content element:</p>
        !           457: <pre>
        !           458: &lt;inputfield id="ifd" label="Input Field"&gt;
        !           459: </pre>
        !           460:     <p>The final element in the content is a typical XUL
        !           461:     <tt>textbox</tt> that has a namespace like the label. The
        !           462:     <tt>anonid</tt> attribute on the textbox is fabricated and used
        !           463:     here to avoid bugs and scope issues with the <tt>id</tt>
        !           464:     attribute in content. The <tt>id</tt> attribute should be used
        !           465:     only on the <tt>&lt;binding&gt;</tt> and
        !           466:     <tt>&lt;bindings&gt;</tt> tags, but <tt>anonid</tt> works well
        !           467:     as direct DOM access to this element and is shown in the next
        !           468:     section.</p>
        !           469:     <h3><a name="77036"></a> The Implementation Element</h3>
        !           470:     <p>The next part of the 
        !           471:     <!--INDEX XBL (eXtensible Binding Language):implementation element -->
        !           472:     binding, and also the most complex, is the behavior. The <tt>
        !           473:     <!--INDEX implementation element, XBL -->
        !           474:     &lt;implementation&gt;</tt> element contains the
        !           475:     <tt>&lt;constructor&gt;</tt>, <tt>&lt;destructor&gt;</tt>,
        !           476:     <tt>&lt;field&gt;</tt>, <tt>&lt;property&gt;</tt>, and
        !           477:     <tt>&lt;method&gt;-</tt>all of which handle the binding's
        !           478:     implementation features.</p>
        !           479:     <p>All elements can contain JavaScript, which changes the
        !           480:     binding into a dynamic widget that does more than display
        !           481:     content on the screen. The binding implementation accepts user
        !           482:     input, dynamically changes the UI, interacts with remote sites
        !           483:     through web protocols, and surfaces Mozilla library functions
        !           484:     in widgets.</p>
        !           485:     <h4><a name="77037"></a> Constructor</h4>
        !           486:     <p>In the example binding, some 
        !           487:     <!--INDEX constructors:implementation element, XBL -->
        !           488:     variables and style rules are set up for access by the rest of
        !           489:     the binding to make the code cleaner. These rules are set up by
        !           490:     using the <tt>constructor</tt>:</p>
        !           491: <pre>
        !           492: &lt;constructor&gt;&lt;![CDATA[
1.1       david     493: this.input=document.getAnonymousElementByAttribute
                    494: (this,"anonid","input");
                    495: // Initialize color and backgroundColor to something besides a "" value
                    496: this.input.inputField.style.backgroundColor="white";
                    497: this.input.inputField.style.color="black";
                    498: this.input.inputField.setAttribute("onchange","");
1.8     ! petejc    499: ]]&gt;&lt;/constructor&gt;
        !           500: </pre>
        !           501:     <p>The first JavaScript command accesses the
        !           502:     <tt>&lt;textbox&gt;</tt> with the <tt>anonid</tt> label and
        !           503:     puts it into the <i>this.input</i> variable.
        !           504:     <tt>getAnonymousElementByAttribute</tt> is a custom DOM method
        !           505:     used to access anonymous content. The section <a href=
        !           506:     "#77048">"The XBL DOM Interfaces</a>," later in this chapter,
        !           507:     talks more about the XBL DOM methods.</p>
        !           508:     <p>The use of the <tt>this</tt> keyword and the "dot notation"
        !           509:     comes from Java. If you have programmed in Java, these bindings
        !           510:     can be considered similar to Java classes. They are
        !           511:     self-contained and can be extended. Using <tt>this</tt> is not
        !           512:     necessary but it's common practice and clarifies that the
        !           513:     variable or property is a member of the binding, especially if
        !           514:     you define elements in the binding's constructor.</p>
        !           515:     <p>In the next two commands, an object called
        !           516:     <tt>inputField</tt> contains the <tt>style</tt> object
        !           517:     property. You may be familiar with this structure in HTML
        !           518:     elements, and in fact, this <tt>inputField</tt> is a version of
        !           519:     the HTML <tt>&lt;input&gt;</tt> textbox. The
        !           520:     <tt>&lt;textbox&gt;</tt> in XUL derives from that HTML
        !           521:     element.</p>
        !           522:     <p>The <tt>color</tt> and <tt>backgroundColor</tt> are set here
        !           523:     manually to return something other than the initial value of a
        !           524:     blank string when they are accessed. The last line in the
        !           525:     <tt>&lt;constructor&gt;</tt> sets up the <tt>onchange</tt>
        !           526:     event handler for the textbox. This event handler is also used
        !           527:     in a property for this binding.</p>
        !           528:     <h4><a name="77038"></a> Destructor</h4>
        !           529:     <p>This section of a binding 
        !           530:     <!--INDEX destructors, XBL implementation element --> executes
        !           531:     anything that needs to be done immediately before a binding is
        !           532:     unloaded. Here is an example:</p>
        !           533: <pre>
        !           534: &lt;destructor&gt;
1.1       david     535: this.input=null;
1.8     ! petejc    536: &lt;/destructor&gt;
        !           537: </pre>
        !           538:     <p>The code you see here is not necessary in this binding, but
        !           539:     it shows you the format for executing code in the destructor.
        !           540:     Destructors are great to use when you have loaded a component
        !           541:     in the binding and want to set the variable representing the
        !           542:     component to null to avoid memory leaks. If you have a lot of
        !           543:     bindings that load and then unload components while a Mozilla
        !           544:     session is still running, a significant amount of memory can be
        !           545:     eaten up unless you take this kind of step.</p>
        !           546:     <h4><a name="77039"></a> Properties</h4>
        !           547:     <p>Like Java properties, 
        !           548:     <!--INDEX properties:XBL;XBL (eXtensible Binding Language):properties -->
        !           549:     an XBL <tt><!--INDEX property element, XBL -->
        !           550:     &lt;property&gt;</tt> has getters and setters, so they can
        !           551:     behave differently when you read or write data. Here is a
        !           552:     subset of properties used in this binding:</p>
        !           553: <pre>
        !           554: &lt;property name="value" readonly="true"&gt;
1.1       david     555: &lt;getter&gt;
                    556: return this.input.value;
                    557: &lt;/getter&gt;
                    558: &lt;/property&gt;
                    559: &lt;property name="uppercase" readonly="true"
                    560: onget="return this.value.toUpperCase( );"/&gt;
                    561: &lt;property name="backgroundColor"&gt;
                    562: &lt;getter&gt;
                    563: return this.input.inputField.style.backgroundColor;
                    564: &lt;/getter&gt;
                    565: &lt;setter&gt;
                    566: this.input.inputField.style.backgroundColor=val;
                    567: return val;
                    568: &lt;/setter&gt;
1.8     ! petejc    569: &lt;/property&gt;
        !           570: </pre>
        !           571:     <p>At this point, the characteristics of properties to watch
        !           572:     out for include the <tt>readonly</tt> attribute, the getter and
        !           573:     setter elements, and the existence of a <tt>val</tt> keyword
        !           574:     that is used internally for accessing a property's current
        !           575:     value. For your reference, this binding's property extracts are
        !           576:     used for getting the value of the input field, returning an
        !           577:     uppercase version of the inputted text, and getting or setting
        !           578:     the input field's background color.</p>
        !           579:     <h4><a name="77040"></a> Methods</h4>
        !           580:     <p>Methods in XBL are 
        !           581:     <!--INDEX methods:XBL;XBL (eXtensible Binding Language):methods -->
        !           582:     self-contained functions represented by the
        !           583:     <tt>&lt;method&gt;</tt> tag and encapsulated within the
        !           584:     <tt>&lt;implementation&gt;</tt> element. They usually provide a
        !           585:     binding object with a specific function like copying and saving
        !           586:     some data or showing and hiding widget controls. Like
        !           587:     properties, they can be called from within the binding, from
        !           588:     another binding that subclasses that binding, and directly from
        !           589:     the bound element.</p>
        !           590: <pre>
        !           591: &lt;method name="clear"&gt;
1.1       david     592: &lt;body&gt;
                    593: this.input.value='';
                    594: &lt;/body&gt;
                    595: &lt;/method&gt;
                    596: &lt;method name="setValue"&gt;
                    597: &lt;parameter name="newValue"/&gt;
                    598: &lt;body&gt;
                    599: this.input.value=newValue;
                    600: &lt;/body&gt;
1.8     ! petejc    601: &lt;/method&gt;
        !           602: </pre>
        !           603:     <p>The method code is contained in a <tt>&lt;body&gt;</tt> tag,
        !           604:     and each method can have 0 or more parameters, which gather the
        !           605:     values passed into the method when called.</p>
        !           606:     <h3><a name="77041"></a> Handlers</h3>
        !           607:     <p>Handlers in XBL mimic 
        !           608:     <!--INDEX handlers, XBL;XBL (eXtensible Binding Language):handlers -->
        !           609:     regular document events like <tt>onclick</tt> and
        !           610:     <tt>onmousedown</tt>, and provide a means for trapping them
        !           611:     within your binding and carrying out tasks associated with
        !           612:     them.</p>
        !           613: <pre>
        !           614: &lt;handlers&gt;
1.1       david     615: &lt;handler event="mouseover"&gt;
                    616: this.input.focus( );
                    617: &lt;/handler&gt;
1.8     ! petejc    618: &lt;/handlers&gt;
        !           619: </pre>
        !           620:     <p>Each handler is contained in a <tt>
        !           621:     <!--INDEX handler element, XBL --> &lt;handler&gt;</tt> tag and
        !           622:     the event name is placed in the <tt>event</tt> attribute-minus
        !           623:     the "on" prefix. The handler in the code shown above places the
        !           624:     focus in the <tt>inputfield</tt> when the mouse goes over it.
        !           625:     See the section "Event Handling," later in this chapter, for
        !           626:     more details.</p>
        !           627:     <h3><a name="77042"></a> Style</h3>
        !           628:     <p>The sample binding's last piece 
        !           629:     <!--INDEX styles:XBL;XBL (eXtensible Binding Language):styles -->
        !           630:     of the puzzle is style. Any XUL elements used in the content
        !           631:     inherit the default styles for those widgets, but if you want
        !           632:     to add more, you can include your own stylesheet like this:</p>
        !           633: <pre>
        !           634: &lt;resources&gt;
1.1       david     635: &lt;stylesheet src="inputfield.css"/&gt;
1.8     ! petejc    636: &lt;/resources&gt;
        !           637: </pre>
        !           638:     <p>Notice the <tt>
        !           639:     <!--INDEX resources container element, XBL -->
        !           640:     &lt;resources&gt;</tt> container element, which is a
        !           641:     prerequisite for this feature. The use of stylesheets in
        !           642:     bindings is covered more thoroughly at the end of the chapter
        !           643:     in the section <a href="#77066">"Resources for
        !           644:     Bindings</a>."</p>
        !           645:     <p>At this point, you should be familiar with the pieces that
        !           646:     make up a binding, which, at the top level, are the content,
        !           647:     implementation, event handlers, and extra resources. The
        !           648:     binding that you have constructed is small, yet it shows all
        !           649:     the main concepts involved in structuring a binding. With some
        !           650:     personalizing, it could be included in potentially any
        !           651:     application.</p>
        !           652:     <h2><a name="77043"></a> Adding Behavior to Bindings</h2>
        !           653:     <p>Like XUL widgets, XBL uses JavaScript 
        !           654:     <!--INDEX bindings:XBL:behaviors;XBL (eXtensible Binding Language):bindings:behaviors -->
        !           655:     to provide functionality to bindings by accessing XPCOM methods
        !           656:     via XPConnect. Like binding content, behavior is optional in a
        !           657:     binding. Each can exist without the other. At times, you might
        !           658:     want only implementations, such as a base binding that contains
        !           659:     certain properties that are inherited by other bindings.</p>
        !           660:     <p>The <tt>&lt;implementation&gt;</tt> element is the container
        !           661:     for all other elements that make up a binding's behavioral
        !           662:     portion. <a href="#77008">Example 7-1</a> shows an empty
        !           663:     implementation shell that highlights the element's contained
        !           664:     hierarchy.</p>
        !           665:     <p><i>Example 7-1: <a name="77008"></a></i> <i>XBL
        !           666:     implementation element</i></p>
        !           667: <pre>
        !           668:  &lt;implementation&gt;
1.1       david     669:    &lt;constructor /&gt;
                    670:    &lt;destructor /&gt;
                    671:    &lt;method name=""&gt;
                    672:      &lt;parameter name="" /&gt;
                    673:      &lt;body /&gt;
                    674:    &lt;/method&gt;
                    675:    &lt;property&gt;
                    676:      &lt;getter /&gt;
                    677:      &lt;setter /&gt;
                    678:    &lt;/property&gt;
                    679:    &lt;field /&gt;
1.8     ! petejc    680:  &lt;/implementation&gt;
        !           681: </pre>
        !           682:     <p>The code in <a href="#77008">Example 7-1</a> shows the
        !           683:     <tt>&lt;implementation&gt;</tt> element having a constructor,
        !           684:     destructor, method, property, and field as possible children.
        !           685:     Each component can exist in quantities of zero or more, with
        !           686:     the exception of the constructor and destructor, of which there
        !           687:     can be only zero or one. The rest of this section describes
        !           688:     each binding implementation component in more detail.</p>
        !           689:     <h3><a name="77044"></a> Binding Methods</h3>
        !           690:     <p>Bindings can exist solely as content 
        !           691:     <!--INDEX bindings:XBL:methods;XBL (eXtensible Binding Language):bindings:methods;methods:XBL bindings -->
        !           692:     generators, acting passively when they are drawn. But you can
        !           693:     also create bindings that provide new capabilities and more
        !           694:     interactive functions or that execute routines in your
        !           695:     application.</p>
        !           696:     <p>In the spirit of self-containment, functions can be added to
        !           697:     a binding that carry out functionality related to that binding.
        !           698:     These functions are the behavior of a binding. The ideal way to
        !           699:     add behavior is to add methods to your binding with the
        !           700:     <tt>&lt;method&gt;</tt> element. Each parameter for a method
        !           701:     defined in the <tt><!--INDEX method element, XBL -->
        !           702:     &lt;method&gt;</tt> element is contained within its own
        !           703:     <tt>&lt;parameter&gt;</tt> tag.</p>
        !           704: <pre>
        !           705: &lt;method name="dumpString"&gt;
1.1       david     706: &lt;parameter name="aString1"/&gt;
                    707: &lt;parameter name="aString2"/&gt;
                    708: &lt;body&gt;
                    709: &lt;![CDATA[
                    710: if (!aString1 &amp;&amp; aString2)
                    711: return;
                    712: return dump(aString1+" "+aString2+"\n");
                    713: ]]&gt;
                    714: &lt;/body&gt;
1.8     ! petejc    715: &lt;/method&gt;
        !           716: </pre>
        !           717:     <p>To use the method to print text to the command shell, call
        !           718:     the name that is specified in the <tt>name</tt> attribute. All
        !           719:     methods created in a binding are added to the binding element
        !           720:     object and called as members of that object, as shown here:</p>
        !           721: <pre>
        !           722: &lt;mybinding id="myNewWidget"&gt;
        !           723: &lt;image src="<a href=
        !           724: "http://www.mozdev.org/sharedimages/header.gif">http://www.mozdev.org/sharedimages/header.gif</a>" /&gt;
1.1       david     725: &lt;/mybinding&gt;
                    726: &lt;button label="test method"
                    727: oncommand="document.getElementById('myNewWidget')
1.8     ! petejc    728: .dumpString('hello', 'there!');"/&gt;
        !           729: </pre>
        !           730:     <p>Using the &lt;![CDATA XML entity is also important. The
        !           731:     purpose of &lt;![CDATA is to escape JavaScript that may
        !           732:     otherwise cause conflicts with the XML parser. Having
        !           733:     characters like quotes and slashes in XML is problematic when
        !           734:     they are not escaped. Using <tt>&lt;!CDATA</tt> with large
        !           735:     portions of JavaScript in a binding can improve performance and
        !           736:     minimize bugs.</p>
        !           737:     <p>Methods were designed for language neutrality with the
        !           738:     <tt>type</tt> attribute and getter and setter elements.
        !           739:     Currently, bindings support only JavaScript, which is the
        !           740:     default when no type is specified. However, this may change as
        !           741:     other scripting engines are plugged into Gecko.</p>
        !           742:     <h4><a name="77045"></a> Attachment and detachment</h4>
        !           743:     <p>Two special methods exist in XBL that 
        !           744:     <!--INDEX bindings:XBL:methods;XBL (eXtensible Binding Language):bindings:methods;methods:XBL bindings:attachment;methods:XBL:detachment -->
        !           745:     allow 
        !           746:     <!--INDEX attachment, XBL:methods;detachment, XBL:methods -->
        !           747:     you to manipulate what happens when a binding is added or
        !           748:     removed from a document. These methods use the native
        !           749:     <tt>&lt;constructor&gt;</tt> and <tt>&lt;destructor&gt;</tt>
        !           750:     tags. A constructor is valuable, for example, when you need to
        !           751:     initialize a binding object or prefill the UI based on stored
        !           752:     values. Destructors can clean up when a binding is
        !           753:     discarded.</p>
        !           754:     <p>When bindings are attached, their content is inserted into
        !           755:     the document at the point you specify. After insertion-or, more
        !           756:     specifically, after the attachment occurs-the code in the
        !           757:     <tt>&lt;constructor&gt;</tt> executes. Similarly, you can use
        !           758:     the <tt>&lt;destructor&gt;</tt> element to execute functions
        !           759:     when a binding is destroyed.</p>
        !           760: <pre>
        !           761: &lt;implementation&gt;
1.1       david     762: &lt;constructor&gt;
                    763: &lt;![CDATA[ dump("\n********\nCreate\n********\n");]]&gt;
                    764: &lt;/constructor&gt;
                    765: &lt;destructor&gt;
                    766: &lt;![CDATA[ dump("\n********\nDestroy\n********\n");]]&gt;
                    767: &lt;/destructor&gt;
1.8     ! petejc    768: &lt;/implementation&gt;
        !           769: </pre>
        !           770:     <p>This example prints some text to output, but you can include
        !           771:     code that carries out variable initialization or anything else
        !           772:     you want to occur at these stages of the binding's life. Bound
        !           773:     elements constructed before the document <tt>load</tt> event
        !           774:     execute this script before the document <tt>load</tt> event
        !           775:     fires. In the case of extended bindings, base handlers are
        !           776:     fired first, followed by derived handlers.</p>
        !           777:     <h3><a name="77046"></a> Binding Properties</h3>
        !           778:     <p>Properties on a binding are 
        !           779:     <!--INDEX bindings:XBL:properties;XBL (eXtensible Binding Language):bindings:properties;properties:XBL:bindings -->
        !           780:     included by using the <tt><!--INDEX property element, XBL -->
        !           781:     &lt;property&gt;</tt> element. Fundamentally, properties are
        !           782:     used to hold and manipulate values that are used elsewhere in
        !           783:     the binding, such as when a text widget has its displayed value
        !           784:     changed periodically by the application. Currently, there are
        !           785:     two classifications for properties, one of which gets a raw
        !           786:     value directly on the element.</p>
        !           787: <pre>
        !           788: &lt;property name="someAttribute"&gt;
1.1       david     789: false;
1.8     ! petejc    790: &lt;/property&gt;
        !           791: </pre>
        !           792:     <p>This example always sets the attribute named
        !           793:     <tt>someAttribute</tt> to false. Though still supported, this
        !           794:     use of the <tt>&lt;property&gt;</tt> element was replaced by a
        !           795:     new element called <tt>&lt;field&gt;</tt>. Although it is not
        !           796:     in the XBL 1.0 specification, the <tt>&lt;field&gt;</tt>
        !           797:     element is implemented and used in the Mozilla code base. It
        !           798:     has the same syntax but a different name. We recommend using
        !           799:     the <tt>&lt;field&gt;</tt> element.</p>
        !           800: <pre>
        !           801: &lt;field name="someAttribute"&gt;
1.1       david     802: false;
1.8     ! petejc    803: &lt;/field&gt;
        !           804: </pre>
        !           805:     <p>The second property usage defines functions that are carried
        !           806:     out when getting and setting a property's value. Take this
        !           807:     anonymous content with a <tt>label</tt> child:</p>
        !           808: <pre>
        !           809: &lt;xul:box align="left" flex="1"&gt;
1.1       david     810: &lt;xul:label xbl:inherits="value=title"/&gt;
                    811: &lt;xul:spacer flex="1"/&gt;
1.8     ! petejc    812: &lt;/xul:box&gt;
        !           813: </pre>
        !           814:     <p>This content simply shows some text on the screen. The bound
        !           815:     element that uses this content looks like this:</p>
        !           816: <pre>
        !           817: &lt;mybinding id="my-binding" title="For Those Who Love to Use XBL" /&gt;
        !           818: </pre>
        !           819:     <p>The XUL <tt>label</tt> used in the binding inherits the
        !           820:     <tt>title</tt> attribute value that is set on the bound
        !           821:     element. <a href="#77010">Example 7-2</a> shows how to set this
        !           822:     title and its retrieval. Both access the bound element, and any
        !           823:     changes filter down to the label.</p>
        !           824:     <p><i>Example 7-2: <a name="77010"></a></i> <i>An XBL property
        !           825:     setting and getting a value</i></p>
        !           826: <pre>
        !           827:  &lt;property name="title"&gt;
1.1       david     828:    &lt;setter&gt;
1.8     ! petejc    829:      &lt;!&lt;/td&gt;[CDATA[
        !           830:        this.setAttribute('title',val); return val&lt;/td&gt;;
1.1       david     831:      ]]&gt;
                    832:    &lt;/setter&gt;
                    833:    &lt;getter&gt;
1.8     ! petejc    834:      &lt;!&lt;/td&gt;[CDATA[
1.1       david     835:        return this.getAttribute('title');
                    836:      ]]&gt;
                    837:    &lt;/getter&gt;
1.8     ! petejc    838:  &lt;/property&gt;
        !           839: </pre>
        !           840:     <p>The script keyword <tt>val</tt> is used 
        !           841:     <!--INDEX val keyword, XBL and;XBL (eXtensible Binding Language):val keyword -->
        !           842:     internally to represent the latest property value. The request
        !           843:     to change the property or retrieve its value can come from
        !           844:     another property in the same binding
        !           845:     (<tt>this.&lt;propertyName&gt;</tt>), from a binding method, or
        !           846:     from a method in the bound document that accesses the binding
        !           847:     object directly. This Java-Script sets the value of a property
        !           848:     named <tt>title</tt> on the binding object:</p>
        !           849: <pre>
        !           850: var titleElement = document.getElementById("my-binding");
        !           851: titleElement.title = "The Adventures of an XBL hacker";
        !           852: </pre>
        !           853:     <p>You can use the <tt>onget</tt> and <tt>onset</tt> attribute
        !           854:     as an alternative to <tt>&lt;getter&gt;</tt> and
        !           855:     <tt>&lt;setter&gt;</tt> elements. Properties are initialized
        !           856:     after the content is generated but before the binding attached
        !           857:     event is set off. This ensures that all properties are
        !           858:     available once that event occurs.</p>
        !           859:     <p>Although it is most commonly used just for getting and
        !           860:     setting values on the property, nothing stops you from putting
        !           861:     more code in the <tt>&lt;properties&gt;</tt> element that
        !           862:     carries out other actions on the binding. One scenario shown in
        !           863:     <a href="#77012">Example 7-3</a> is if you have a property that
        !           864:     holds a search value, you can send that text to the Google <a
        !           865:     name="b253"></a><a href="#253">[*]</a> API, and fill another
        !           866:     widget in the UI with the results every time the value is
        !           867:     updated. <a name="b254"></a><a href="#254">[*]</a></p>
        !           868:     <p><i>Example 7-3: <a name="77012"></a></i> <i>Performing a
        !           869:     Google search when setting a property</i></p>
        !           870: <pre>
        !           871:  &lt;property name="searchString"&gt;
1.1       david     872:    &lt;setter&gt;
1.8     ! petejc    873:      &lt;!&lt;/td&gt;[CDATA[
1.1       david     874:        var s = new SOAPCall( );
1.8     ! petejc    875:        &lt;/td&gt;var q = val;
1.1       david     876:        if (!s)
                    877:          return "Error creating SOAPCall object";
                    878:        var soapversion = 0;
                    879:        var method = "doGoogleSearch";
                    880:        var object = "urn:GoogleSearch";
1.8     ! petejc    881:        var headers = &lt;/td&gt;[ ];
        !           882:        var params = &lt;/td&gt;[
1.1       david     883:          new SOAPParameter(this.googleKey, "key"),
                    884:          new SOAPParameter(q, "q"),
                    885:          new SOAPParameter(this.start, "start"),
                    886:          new SOAPParameter(this.maxResults, "maxResults"),
                    887:          new SOAPParameter(this.filter, "filter"),
                    888:          new SOAPParameter(this.restrict, "restrict"),
                    889:          new SOAPParameter(this.safeSearch, "safeSearch"),
                    890:          new SOAPParameter(this.lr, "lr"),
                    891:          new SOAPParameter("utf8", "ie"),
                    892:          new SOAPParameter("utf8", "oe")
                    893:        ];
                    894:        s.encode(soapversion, method, object, headers.length, headers,
                    895:          params.length, params);
1.8     ! petejc    896:        s.transportURI = "<a href=
        !           897: "http://api.google.com/search/beta2">http://api.google.com/search/beta2</a>"
1.1       david     898:        var response = s.invoke( );
                    899:        if (response.fault)
                    900:          return { msg : "SOAP call error", fault : response.fault };
                    901:        // At this point you would pass the results back to the UI
                    902:        return response.message;
                    903:      ]]&gt;
                    904:    &lt;/setter&gt;
1.8     ! petejc    905:  &lt;/property&gt;
        !           906: </pre>
        !           907:     <p>The value of the search string is set to the value that has
        !           908:     been given to the property: <tt>var q = val</tt>. This value is
        !           909:     then added to the parameter list (<tt>SOAPParameter</tt>) for
        !           910:     the SOAP call, along with other parameters that are obtained
        !           911:     from other properties in the binding (e.g.,
        !           912:     <tt>this.maxResults</tt>).</p>
        !           913:     <h2><a name="77047"></a> XBL and the DOM</h2>
        !           914:     <p>This section introduces 
        !           915:     <!--INDEX XBL (eXtensible Binding Language):DOM and;DOM (Document Object Model):XBL and -->
        !           916:     the DOM interfaces in XBL, illustrates how they work, and
        !           917:     explains the core concepts involved in XBL interaction with the
        !           918:     DOM, such as scope characteristics and insertion points.</p>
        !           919:     <h3><a name="77048"></a> The XBL DOM Interfaces</h3>
        !           920:     <p>XBL has two 
        !           921:     <!--INDEX DocumentXBL interface;ElementXBL interface;DOM (Document Object Model):DocumentXBL interface;DOM (Document Object Model):ElementXBL interface -->
        !           922:     core DOM interfaces, <tt>DocumentXBL</tt> and
        !           923:     <tt>ElementXBL</tt>. These extensions to the <i>Document</i>
        !           924:     and <i>Element</i> interfaces are not part of the formal DOM
        !           925:     specifications. All methods can be accessed and used from
        !           926:     JavaScript. Here is a list of these interface methods.</p>
        !           927:     <h4><a name="77049"></a> DocumentXBL methods</h4>
        !           928:     <p>The <i>
        !           929:     <!--INDEX DocumentXBL interface:methods;methods:DocumentXBL interface -->
        !           930:     DocumentXBL</i> interface gains access to and interacts with an
        !           931:     XBL document. The methods of this interface are as follows:</p>
        !           932:     <dl>
        !           933:       <dt>loadBindingDocument(URL)</dt>
        !           934:       <dd>XBL documents are loaded 
        !           935:       <!--INDEX loadBindingDocument( ) method, DocumentXBL interface -->
        !           936:       only the first time a bound document uses a binding from it.
        !           937:       You can get around this problem and load the binding
        !           938:       documents synchronously by using this method. It returns an
        !           939:       XBL document for use within a bound document. If your
        !           940:       document is large and you need to optimize performance, this
        !           941:       method may provide better performance.</dd>
        !           942:     </dl>
        !           943:     document.loadBindingDocument('chrome://package/content/myBindings.xml');
        !           944:     
        !           945:     <dl>
        !           946:       <dt>getBindingParent(element)</dt>
        !           947:       <dd>For use only within a binding, this 
        !           948:       <!--INDEX getBindingParent( ) method, DocumentXBL interface -->
        !           949:       method returns the bound element-i.e., the top-level node of
        !           950:       the binding, when passed an element within a binding.</dd>
        !           951:     </dl>
        !           952:     var listbox = document.getBindingParent(this); var cellValue =
        !           953:     listbox.childNodes[3].firstChild.label; 
        !           954:     <dl>
        !           955:       <dt>getAnonymousNodes(element)</dt>
        !           956:       <dd>Returns an array with the input 
        !           957:       <!--INDEX getAnonymousNodes( ) method, XBL --> binding's
        !           958:       top-level content nodes. Refer to the section <a href=
        !           959:       "#77054">"Accessing Anonymous Nodes</a>," later in this
        !           960:       chapter, for more details.</dd>
        !           961:       <dt>getAnonymousElementByAttribute(element, attribute,
        !           962:       value)</dt>
        !           963:       <dd>Returns a single anonymous 
        !           964:       <!--INDEX getAnonymousElementByAttribute( ) method, XBL -->
        !           965:       element when passed an element, an attribute from that
        !           966:       element, and its value. Refer to the section <a href=
        !           967:       "#77054">"Accessing Anonymous Nodes</a>" for more
        !           968:       details.</dd>
        !           969:     </dl>
        !           970:     <h4><a name="77050"></a> ElementXBL methods</h4>
        !           971:     <p>The <i>ElementXBL</i> interface adds and 
        !           972:     <!--INDEX ElementXBL interface --> removes bindings from a
        !           973:     bound element. The methods of this interface are as
        !           974:     follows:</p>
        !           975:     <dl>
        !           976:       <dt>addBinding(element, URL)</dt>
        !           977:       <dd>Dynamically attaches a binding, 
        !           978:       <!--INDEX addBinding( ) method, ElementXBL interface -->
        !           979:       given as a parameter, to an element. Refer to the following
        !           980:       sections for more details.</dd>
        !           981:       <dt>removeBinding(element, URL)</dt>
        !           982:       <dd>Dynamically removes the 
        !           983:       <!--INDEX removeBinding( ) method, ElementXBL interface -->
        !           984:       given binding. Refer to the following sections for more
        !           985:       details.</dd>
        !           986:     </dl>
        !           987:     <h4><a name="77051"></a> Dynamically adding a binding</h4>
        !           988:     <p>The section <a href="#77033">"Anatomy of a Binding</a>"
        !           989:     covered the attachment of a binding to a bound element using
        !           990:     CSS. This technique 
        !           991:     <!--INDEX bound elements:bindings:adding dynamically;bindings:bound elements:adding dynamically -->
        !           992:     is the most common method, but you can also attach bindings
        !           993:     with the <tt>addBinding</tt> method.</p>
        !           994:     <p>Using this method as an alternative to CSS attachment is
        !           995:     useful when you do not want to attach a binding in all
        !           996:     circumstances. In an application based on user input, you may
        !           997:     not want to load a binding until certain values are entered.
        !           998:     For example, in a membership database, the information that
        !           999:     appears on screen may depend on the user's level of membership.
        !          1000:     The following snippets show how it is used.</p>
        !          1001: <pre>
        !          1002: &lt;mybinding id="myNewWidget" class="attached" /&gt;
        !          1003: </pre>
        !          1004:     <p>To load a binding, add these two lines in your script.</p>
        !          1005: <pre>
        !          1006: var binding = document.getElementById("myNewWidget");
        !          1007: document.addBinding(binding, "chrome://mypackage/content/myBindings.xml#super");
        !          1008: </pre>
        !          1009:     <p>Notice that the URL used to access the binding takes the
        !          1010:     same format as in the CSS property-i.e., the path to the file
        !          1011:     and the <tt>id</tt> of the binding qualified by <tt>#</tt>.</p>
        !          1012:     <blockquote>
        !          1013:       <div class="c19">
        !          1014:         NOTE
        !          1015:       </div>
        !          1016:       <p>Neither <tt>addBinding</tt> nor <tt>removeBinding</tt> are
        !          1017:       implemented at the time of writing. They are covered because
        !          1018:       they are part of the XBL 1.0 specification. When implemented,
        !          1019:       they offer crucial alternatives for attaching and detaching
        !          1020:       bindings, making XBL a more interactive technology.</p>
        !          1021:     </blockquote>
        !          1022:     <h4><a name="77052"></a> Removing bindings</h4>
        !          1023:     <p>The best way to remove a binding 
        !          1024:     <!--INDEX bound elements:bindings:removing;bindings:bound elements:removing from -->
        !          1025:     attached via CSS is to change the style rule for that element.
        !          1026:     You can change the <tt>class</tt> to one that does not have a
        !          1027:     different or null binding reference, for example. Then a
        !          1028:     stylesheet can be set up to provide binding references for both
        !          1029:     an attached and unattached element.</p>
        !          1030:     <p>This example shows how to remove a reference to a binding by
        !          1031:     resetting it to an empty reference:</p>
        !          1032: <pre>
        !          1033: mybinding.attached {
1.1       david    1034: -moz-binding : url("mybindings.xml#my-binding");
                   1035: }
                   1036: mybinding.unattached {
                   1037: -moz-binding : url("");
1.8     ! petejc   1038: }
        !          1039: </pre>
        !          1040:     <p>When you want to detach the binding from an element, you can
        !          1041:     do this:</p>
        !          1042: <pre>
        !          1043: var mywidget = document.getElementById("binding1");
        !          1044: mywidget.setAttribute("class","unattached");
        !          1045: </pre>
        !          1046:     <p>An element can have only one binding attached at a time, so
        !          1047:     this is a programmatic trick for knocking the "real" binding
        !          1048:     out of its place with an empty one, rather than actually
        !          1049:     removing it.</p>
        !          1050:     <blockquote>
        !          1051:       <div class="c19">
        !          1052:         NOTE
        !          1053:       </div>
        !          1054:       <p><tt>-moz-binding:url("")</tt> can be used at this time as
        !          1055:       a hack around the <tt>-moz-binding:none</tt> binding. The
        !          1056:       later binding does not currently work in Mozilla.</p>
        !          1057:     </blockquote>
        !          1058:     <p>The other method used to detach a binding, which is more
        !          1059:     intuitive from a DOM perspective, uses the
        !          1060:     <tt>removeBinding</tt> method:</p>
        !          1061: <pre>
        !          1062: var binding = document.getElementById("myNewWidget");
        !          1063: document.removeBinding(binding, "chrome://mypackage/content/myBindings.xml#super");
        !          1064: </pre>
        !          1065:     <p>This method ensures that other style information is not lost
        !          1066:     if you have it attached to a particular class.</p>
        !          1067:     <p>When a binding is removed, the anonymous content is
        !          1068:     destroyed and the methods, properties, and event handlers no
        !          1069:     longer apply.</p>
        !          1070:     <p>In the case of an inheritance chain (see the <a href=
        !          1071:     "#77060">"Inheritance</a>" section later in this chapter for
        !          1072:     more details), the bindings are destroyed from the bottom
        !          1073:     upwards. This means that if there is tear-down code in the form
        !          1074:     of a destructor, it is executed last on the base binding.</p>
        !          1075:     <h3><a name="77053"></a> Binding Parents</h3>
        !          1076:     <p>Although a document cannot access 
        !          1077:     <!--INDEX bindings:parents;parents, bindings;XBL (eXtensible Binding Language):bindings:parents -->
        !          1078:     the content of bindings attached to it, a binding can access
        !          1079:     the document it is attached to (bound document). This gives
        !          1080:     bindings the ability to provide more than just additional
        !          1081:     content to the document. It also means that you can find
        !          1082:     information about the context of bound element in a document
        !          1083:     and provide information about it from within the binding.</p>
        !          1084:     <p>From the perspective of nodes inside the anonymous content,
        !          1085:     you can use DOM properties to find a higher-level node and then
        !          1086:     in turn use that to get to other nodes:</p>
        !          1087:     <dl>
        !          1088:       <dt><tt>parentNode</tt></dt>
        !          1089:       <dd>This property is the bound element for the top-most
        !          1090:       element in the anonymous content. This bound element resides
        !          1091:       in the document that the binding is attached to.</dd>
        !          1092:       <dt><tt>ownerDocument</tt></dt>
        !          1093:       <dd>For all elements in the anonymous content, this is the
        !          1094:       document the bound element resides in.</dd>
        !          1095:     </dl>
        !          1096:     <blockquote>
        !          1097:       <div class="c19">
        !          1098:         NOTE
        !          1099:       </div>
        !          1100:       <p>While higher-level nodes can be accessed from anonymous
        !          1101:       content, parents do not have explicit access to their
        !          1102:       anonymous children using the DOM <tt>childNodes</tt>
        !          1103:       property. Using <tt>firstChild</tt> or <tt>nextSibling</tt>
        !          1104:       will also not work.</p>
        !          1105:     </blockquote>
        !          1106:     <p><a href="#77014">Example 7-4</a> illustrates both properties
        !          1107:     in use.</p>
        !          1108:     <p><i>Example 7-4: <a name="77014"></a></i> <i>Accessing a
        !          1109:     bound document from a binding</i></p>
        !          1110: <pre>
        !          1111:  &lt;binding id="my-binding"&gt;
1.1       david    1112:    &lt;content&gt;
                   1113:      &lt;xul:vbox&gt;
                   1114:        &lt;xul:button label="A" id="button1"
1.8     ! petejc   1115:          oncommand="alert(this.parentNode.parentNode.nodeName)"&lt;/td&gt;/&gt;
1.1       david    1116:        &lt;xul:button label="B" id="button2"
1.8     ! petejc   1117:          oncommand="alert(this.ownerDocument.firstChild.nodeName)"&lt;/td&gt;/&gt;
1.1       david    1118:      &lt;/xul:vbox&gt;
                   1119:    &lt;/content&gt;
1.8     ! petejc   1120:  &lt;/binding&gt;
        !          1121: </pre>
        !          1122:     <p><a href="#77014">Example 7-4</a> is a binding with two
        !          1123:     buttons, each of which brings up an alert when activated. The
        !          1124:     alert simply shows the name of an element that is accessed in
        !          1125:     the code attached to the button. In Button A, the parent node
        !          1126:     is the containing box. One level further is the bound element,
        !          1127:     <tt>&lt;mybinding&gt;-</tt>the parent node of the <tt>box</tt>
        !          1128:     parent. The alert dialog raised by the alert shows "mybinding."
        !          1129:     Once a binding is applied, the binding's owner
        !          1130:     (<tt>ownerDocument</tt>) is the bound document. Assuming that
        !          1131:     Button B is a XUL window, the alert, when activated, shows
        !          1132:     "window." This property can be used to access properties of the
        !          1133:     document object.</p>
        !          1134:     <h3><a name="77054"></a> Accessing Anonymous Nodes</h3>
        !          1135:     <p>Content bound to a document can 
        !          1136:     <!--INDEX anonymous nodes;nodes:anonymous, access --> 
        !          1137:     <!--INDEX XBL (eXtensible Binding Language):nodes, anonymous -->
        !          1138:     introduce different levels of scope. Some of the scope is
        !          1139:     available at the document level, and some is at the binding
        !          1140:     level. With content in different scopes, there are limits to
        !          1141:     which standard DOM methods can be used to access other elements
        !          1142:     and objects in and above a binding. XBL contains some special
        !          1143:     methods to help work around some of the limitations caused by
        !          1144:     these barriers, such as not being able to change binding
        !          1145:     content dynamically or access certain property values.</p>
        !          1146:     <p>The two XBL-specific interfaces that exist on the document
        !          1147:     to get a handle on this content are <i>getAnonymousNodes</i>
        !          1148:     and <i>getAnonymousElementByAttribute</i>. The advantage of
        !          1149:     using these interfaces is that they provide a bridge between
        !          1150:     behavior and content. Use them when you want to dynamically
        !          1151:     manipulate content or get a value-for example, when accessing a
        !          1152:     particular textbox contained in binding, reminiscent of the one
        !          1153:     used earlier in the chapter when you were introduced to the
        !          1154:     <tt>&lt;inputfield /&gt;</tt> binding.</p>
        !          1155:     <h4><a name="77055"></a> getAnonymousNodes</h4>
        !          1156:     <p>The method <tt>getAnonymousNodes(element)</tt> takes 
        !          1157:     <!--INDEX getAnonymousNodes( ) method, XBL --> a node as a
        !          1158:     parameter and returns a list of nodes that are in the anonymous
        !          1159:     content. The following code uses script in the
        !          1160:     <tt>&lt;getter&gt;</tt> to access the anonymous node and return
        !          1161:     a value contained in it.</p>
        !          1162: <pre>
        !          1163: &lt;getter&gt;
1.1       david    1164: &lt;![CDATA[
                   1165: var list = document.getAnonymousNodes(this)[0];
                   1166: return list.selectedItem.getAttribute('label');
                   1167: ]]&gt;
1.8     ! petejc   1168: &lt;/getter&gt;
        !          1169: </pre>
        !          1170:     <p>If we assume that this binding's content is a XUL menu list,
        !          1171:     then this code gets the <tt>label</tt> attribute of the menu
        !          1172:     item that is currently selected in that list
        !          1173:     (<tt>list.selectedItem</tt>). The list variable contains the
        !          1174:     value returned by the <tt>getAnonymousNodes</tt> function,
        !          1175:     which is passed the binding node (<tt>this</tt>). The method
        !          1176:     returns an array, so the item is accessed via the first index
        !          1177:     of 0.</p>
        !          1178:     <h4><a name="77056"></a> getAnonymousElementByAttribute</h4>
        !          1179:     <p>The method <tt>getAnonymousElementByAttribute(element, attr,
        !          1180:     value)</tt> returns a single anonymous node rather than a list.
        !          1181:     This node is 
        !          1182:     <!--INDEX getAnonymousElementByAttribute( ) method, XBL -->
        !          1183:     qualified by an element name, a particular attribute, and the
        !          1184:     value of that attribute, and returns this specific node. This
        !          1185:     retrieval provides faster access to anonymous content elements
        !          1186:     when you know an attribute's value.</p>
        !          1187: <pre>
        !          1188: &lt;property name="emailID" onget="return document.getAnonymousElementByAttribute(this, 'id', 'emailAddressNode');" readonly="true"/&gt;
        !          1189: </pre>
        !          1190:     <p>This example uses an <tt>id</tt> attribute to retrieve a
        !          1191:     specific node. You can use this method when multiple elements
        !          1192:     of the same type exist and you need to get access to a
        !          1193:     particular one-for example, a particular field on a database
        !          1194:     entry submission form like an email address or a telephone
        !          1195:     number.</p>
        !          1196:     <p>Although these two functions (<tt>getAnonymousNodes</tt> and
        !          1197:     <tt>getAnonymous-Elements-ByAttribute</tt>) were probably
        !          1198:     designed to be used within a binding scope, they can be used
        !          1199:     both inside and outside a binding to access anonymous content.
        !          1200:     Bindings are meant to be self-contained, and getting anonymous
        !          1201:     nodes outside a binding breaks this philosophy. However, these
        !          1202:     functions can act as a bridge between scopes if you are
        !          1203:     careful.</p>
        !          1204:     <h3><a name="77057"></a> Extra Binding Content and Insertion
        !          1205:     Points</h3>
        !          1206:     <p>All examples in the chapter have so far dealt with standard
        !          1207:     binding content rendering within a bound document. The
        !          1208:     processes outlined in this section can, in one sense, be seen
        !          1209:     as abnormal because they allow ordering of the content to
        !          1210:     change based on insertion points defined in the binding. This
        !          1211:     process is done with the XBL <tt>&lt;children&gt;</tt>
        !          1212:     element</p>
        !          1213:     <h4><a name="77058"></a> Working with children of the bound
        !          1214:     element</h4>
        !          1215:     <p>Zero or more children can be contained 
        !          1216:     <!--INDEX bound elements:children;XBL (eXtensible Binding Language):bound elements:children;elements:bound elements:children -->
        !          1217:     in anonymous content. These children are marked up with the
        !          1218:     XBL-specific <tt>&lt;children&gt;</tt> tag. They can be either
        !          1219:     the content of the element using the binding or anonymous
        !          1220:     content generated by the base binding. If the <tt>
        !          1221:     <!--INDEX children tag, XBL --> &lt;children&gt;</tt> tag
        !          1222:     contains its own elements, then it will be used as the default
        !          1223:     content. If the element the binding is attached to contains
        !          1224:     children, the default content will be ignored.</p>
        !          1225:     <p>The location of the <tt>&lt;children&gt;</tt> tags
        !          1226:     determines the content's insertion point. Insertion points play
        !          1227:     an important role in the generation of content within a
        !          1228:     template because they affect how the content is displayed and
        !          1229:     accessed by the DOM.</p>
        !          1230: <pre>
        !          1231: &lt;binding id="my-binding"&gt;
1.1       david    1232: &lt;content&gt;
                   1233: &lt;xul:vbox&gt;
                   1234: &lt;children /&gt;
                   1235: &lt;/xul:vbox&gt;
                   1236: &lt;/content&gt;
1.8     ! petejc   1237: &lt;/binding&gt;
        !          1238: </pre>
        !          1239:     <p>This stripped-down binding has only a vertical box as its
        !          1240:     own content and looks to the children of the bound element for
        !          1241:     more content by using the <tt>&lt;children&gt;</tt> element.
        !          1242:     Here is the XUL content that uses the binding:</p>
        !          1243: <pre>
        !          1244: &lt;mybinding id="myNewWidget" flex="1" class="attached"&gt;
1.1       david    1245: &lt;label value="this is child 1" /&gt;
                   1246: &lt;label value="this is child 2" /&gt;
1.8     ! petejc   1247: &lt;/mybinding&gt;
        !          1248: </pre>
        !          1249:     <p>When the binding is attached and the content is drawn, the
        !          1250:     insertion point for the two labels is inside the container
        !          1251:     vertical box inside the binding. This scenario could be used
        !          1252:     when a binding is used multiple times. Each time, it needs to
        !          1253:     be rendered differently with extra content that can be provided
        !          1254:     this way.</p>
        !          1255:     <h4><a name="77059"></a> Selective inclusion</h4>
        !          1256:     <p>Sometimes multiple siblings are located 
        !          1257:     <!--INDEX bound elements:children:selective inclusion;XBL (eXtensible Binding Language):bound elements:children;elements:bound elements:children -->
        !          1258:     within a box in the XUL, but you want to use only some of them
        !          1259:     in the binding, such as when a user logs into a system and
        !          1260:     content is displayed depending on its level of membership. In
        !          1261:     these cases, you can be selective about which children should
        !          1262:     be included in the binding. <a href="#77016">Example 7-5</a>
        !          1263:     shows how to use the <tt>includes</tt> attribute on the
        !          1264:     <tt>&lt;children&gt;</tt> element.</p>
        !          1265:     <p><i>Example 7-5: <a name="77016"></a></i> <i>Selective
        !          1266:     inclusion of child content in a binding</i></p>
        !          1267: <pre>
        !          1268:  &lt;binding id="my-binding"&gt;
1.1       david    1269:    &lt;content&gt;
                   1270:      &lt;xul:vbox class="insideBox"&gt;
                   1271:        &lt;xul:description value="Top" /&gt;
                   1272:        &lt;xul:box&gt;
1.8     ! petejc   1273:          &lt;/td&gt;&lt;children includes="image" /&gt;
1.1       david    1274:        &lt;/xul:box&gt;
                   1275:        &lt;xul:description value="Bottom" /&gt;
                   1276:      &lt;/xul:vbox&gt;
                   1277:    &lt;/content&gt;
1.8     ! petejc   1278:  &lt;/binding&gt;
        !          1279: </pre>
        !          1280:     <p>The children element in <a href="#77016">Example 7-5</a>
        !          1281:     essentially tells, "Of all the content contained in the bound
        !          1282:     element, insert only the <tt>image</tt> element at this
        !          1283:     particular insertion point." Here is the XUL code that goes
        !          1284:     with this example:</p>
        !          1285: <pre>
        !          1286: &lt;mybinding id="myNewWidget" flex="1"&gt;
        !          1287: &lt;image src="<a href=
        !          1288: "http://www.mozdev.org/sharedimages/header.gif">http://www.mozdev.org/sharedimages/header.gif</a>" /&gt;
1.1       david    1289: &lt;label value="a non includes element" /&gt;
1.8     ! petejc   1290: &lt;/mybinding&gt;
        !          1291: </pre>
        !          1292:     <p>The image is the only child taken from the XUL content and
        !          1293:     the label is ignored.</p>
        !          1294:     <p>If you have children that are not defined in the
        !          1295:     <tt>includes</tt> attribute, then the binding is discarded and
        !          1296:     not used. If the bound element uses another element in addition
        !          1297:     to an image element, the binding is discarded and only the
        !          1298:     explicit content is used. If the image element isn't used at
        !          1299:     all, the binding is discarded.</p>
        !          1300: <pre>
        !          1301: &lt;mybinding id="myNewWidget" flex="1"&gt;
        !          1302: &lt;image src="<a href=
        !          1303: "http://www.mozdev.org/sharedimages/header.gif">http://www.mozdev.org/sharedimages/header.gif</a>" /&gt;
1.1       david    1304: &lt;label value="an element" /&gt;
1.8     ! petejc   1305: &lt;/mybinding&gt;
        !          1306: </pre>
        !          1307:     <p>This example renders the image and the label and discards
        !          1308:     the binding. The anonymous content does not appear because the
        !          1309:     binding is discarded and only the explicit content is used.</p>
        !          1310:     <h2><a name="77060"></a> Inheritance</h2>
        !          1311:     <p>In XBL, inheritance is the process in 
        !          1312:     <!--INDEX XBL (eXtensible Binding Language):inheritance;inheritance:XBL -->
        !          1313:     which one object included in another object is allowed to use
        !          1314:     properties from that parent object. These properties can be
        !          1315:     many things, depending on the implementation, ranging from
        !          1316:     methods to attribute property values. Inheritance is a concept
        !          1317:     familiar in programming languages, most notably object-oriented
        !          1318:     ones. It's not something alien to markup, however, and it is
        !          1319:     deployed effectively in XBL. This section examines three forms
        !          1320:     of XBL inheritance: binding, attribute, and implementation. As
        !          1321:     you will see, inheritance promotes self-contained (modular) and
        !          1322:     flexible bindings that permit shared content across and within
        !          1323:     XBL documents.</p>
        !          1324:     <h3><a name="77061"></a> Binding Inheritance</h3>
        !          1325:     <p>Binding inheritance occurs when one 
        !          1326:     <!--INDEX XBL (eXtensible Binding Language):inheritance:bindings -->
        !          1327:     binding <!--INDEX inheritance:XBL:bindings --> is 
        !          1328:     <!--INDEX bindings:inheritance --> linked to another binding or
        !          1329:     XUL element and uses some or all properties of it, whether they
        !          1330:     are content or behavior. A binding can inherit from another
        !          1331:     binding that exists in the same or different file. In one way,
        !          1332:     this useful feature makes a binding like a class, with content
        !          1333:     and methods that can be used elsewhere. Bindings become
        !          1334:     modules, which prevents code duplication, makes maintenance
        !          1335:     easier, and gets slotted in and out of documents.</p>
        !          1336:     <p>Linkage or inheritance is enabled by the <tt>extends</tt>
        !          1337:     attribute on the <tt>&lt;binding&gt;</tt> element. This
        !          1338:     attribute contains the URL of the binding that you inherit
        !          1339:     from. This URL is made up of the location and name of the file
        !          1340:     that contains the binding (the <tt>#</tt> symbol), and the
        !          1341:     <tt>id</tt> of the specific binding being used. In this way, it
        !          1342:     is similar to the access method used in CSS attachment.</p>
        !          1343:     <p>Although it is in the XBL 1.0 specification, Mozilla hasn't
        !          1344:     fully implemented <tt>type="inherits"</tt> on the children tag
        !          1345:     yet, so the best way to work with binding inheritance is to use
        !          1346:     the <tt>extends</tt> attribute. <a href="#77018">Example
        !          1347:     7-6</a> shows a few bindings used in the implementation of the
        !          1348:     <tt>listbox</tt> cell in the Mozilla tree. It illustrates how
        !          1349:     <tt>extends</tt> is used to inherit from another binding.</p>
        !          1350:     <p><i>Example 7-6: <a name="77018"></a></i> <i>Binding
        !          1351:     inheritance</i></p>
        !          1352: <pre>
        !          1353:  &lt;binding id="listbox-base"&lt;/td&gt;&gt;
1.1       david    1354:    &lt;resources&gt;
                   1355:      &lt;stylesheet src="chrome://global/skin/listbox.css"/&gt;
                   1356:    &lt;/resources&gt;
                   1357:  &lt;/binding&gt;
                   1358:  &lt;binding id="listcell"
1.8     ! petejc   1359:      extends="chrome://global/content/bindings/listbox.xml#listbox-base"&lt;/td&gt;&gt;
1.1       david    1360:    &lt;content&gt;
                   1361:      &lt;children&gt;
                   1362:        &lt;xul:label class="listcell-label"
                   1363:            xbl:inherits="value=label,flex=flexlabel,crop,disabled"
                   1364:            flex="1" crop="right"/&gt;
                   1365:      &lt;/children&gt;
                   1366:    &lt;/content&gt;
                   1367:  &lt;/binding&gt;
                   1368:  &lt;binding id="listcell-iconic"
1.8     ! petejc   1369:      extends="chrome://global/content/bindings/listbox.xml#listcell"&lt;/td&gt;&gt;
1.1       david    1370:    &lt;content&gt;
                   1371:      &lt;children&gt;
                   1372:        &lt;xul:image class="listcell-icon" xbl:inherits="src=image"/&gt;
                   1373:        &lt;xul:label class="listcell-label"
                   1374:            xbl:inherits="value=label,flex=flexlabel,crop,disabled"
                   1375:            flex="1" crop="right"/&gt;
                   1376:      &lt;/children&gt;
                   1377:     &lt;/content&gt;
1.8     ! petejc   1378:  &lt;/binding&gt;
        !          1379: </pre>
        !          1380:     <p>In <a href="#77018">Example 7-6</a>,
        !          1381:     <tt>listcell-iconic</tt> inherits <tt>listcell</tt>. In turn,
        !          1382:     <tt>listcell</tt> inherits <tt>list-box-base</tt>, which holds
        !          1383:     resources. The <tt>listcell</tt> binding is a cell with text
        !          1384:     only and the <tt>listcell-iconic</tt> binding has text and an
        !          1385:     image. Thus, the user has a choice of using a list cell binding
        !          1386:     with an icon or no icon. Yet both of these bindings have access
        !          1387:     to the stylesheet resource declared in the base binding. If
        !          1388:     <tt>listcell-iconic</tt> is used, the duplicate
        !          1389:     <tt>xul:label</tt> is ignored in the inherited binding and the
        !          1390:     stylesheet inherited from the base binding via the inherited
        !          1391:     binding is used. We've used this technique to illustrate how
        !          1392:     resources in multiple bindings are shared.</p>
        !          1393:     <p>With binding extensions that use the <tt>extends</tt>
        !          1394:     attribute, you can also extend a XUL element as a model, using
        !          1395:     extensions as a proxy to mimic that XUL element. The element
        !          1396:     may not be included directly in the anonymous content, but its
        !          1397:     characteristics are still present on the bound element. If you
        !          1398:     use the XUL namespace <tt>xul</tt>: in the same way you use it
        !          1399:     for XUL content in a binding, you can inherit the XUL element
        !          1400:     properties as illustrated in <a href="#77020">Example
        !          1401:     7-7</a>.</p>
        !          1402:     <p><i>Example 7-7: <a name="77020"></a></i> <i>Inheriting XUL
        !          1403:     widget characteristics using extends</i></p>
        !          1404: <pre>
        !          1405:  &lt;binding id="Widget1" extends="xul:vbox"&lt;/td&gt;&gt;
1.1       david    1406:    &lt;content&gt;
                   1407:      &lt;xul:description value="Top" /&gt;
                   1408:      &lt;children includes="image" /&gt;
                   1409:      &lt;xul:description value="Bottom" /&gt;
                   1410:    &lt;/content&gt;
1.8     ! petejc   1411:  &lt;/binding&gt;
        !          1412: </pre>
        !          1413:     <p>In <a href="#77020">Example 7-7</a>, the binding has all of
        !          1414:     the attributes and behavior of a XUL box. Because you extend a
        !          1415:     box element, the base widget <tt>&lt;mybinding&gt;</tt> is now
        !          1416:     a vertical box. The anonymous content is laid out according to
        !          1417:     the box model, and all attributes that are recognized on the
        !          1418:     bound element are applied to the box.</p>
        !          1419:     <h3><a name="77062"></a> Attribute Inheritance</h3>
        !          1420:     <p>Also known as "attribute forwarding," <i>attribute
        !          1421:     inheritance</i> is a way for anonymous content to link to the
        !          1422:     attributes from the <!--INDEX inheritance:XBL:attributes --> 
        !          1423:     <!--INDEX XBL (eXtensible Binding Language):inheritance:attributes -->
        !          1424:     bound element. When the bound element attribute is changed,
        !          1425:     this modification filters down to the binding attribute list.
        !          1426:     The code in <a href="#77022">Example 7-8</a> shows anonymous
        !          1427:     content where multiple attributes are picked up by the
        !          1428:     <tt>xbl:inherits</tt> attribute, with each one separated by a
        !          1429:     comma.</p>
        !          1430:     <p><i>Example 7-8: <a name="77022"></a></i> <i>XBL attribute
        !          1431:     inheritance</i></p>
        !          1432: <pre>
        !          1433:  &lt;xul:box class="insideBox" xbl:inherits="orient, flex, align"&lt;/td&gt;&gt;
1.1       david    1434:    &lt;xul:description value="Top" /&gt;
                   1435:      &lt;xul:box&gt;
                   1436:        &lt;children includes="image" /&gt;
                   1437:      &lt;/xul:box&gt;
                   1438:      &lt;xul:description value="Bottom" /&gt;
                   1439:    &lt;/xul:box&gt;
1.8     ! petejc   1440:  &lt;/xul:box&gt;
        !          1441: </pre>
        !          1442:     <p>The element that inherits the attributes can be anywhere in
        !          1443:     the chain of anonymous content. In this case, it is on the
        !          1444:     top-level box. It assumes the value given to these attributes
        !          1445:     in the bound element. Here is the XUL that uses the binding
        !          1446:     content from <a href="#77022">Example 7-8</a>:</p>
        !          1447: <pre>
        !          1448: &lt;mywidget orient="vertical" flex="1" align="center" /&gt;
        !          1449: </pre>
        !          1450:     <p>The <tt>xul:box</tt> element inherits the attribute values
        !          1451:     <tt>vertical</tt>, <tt>1</tt>, and <tt>middle</tt>,
        !          1452:     respectively, from the bound element (<tt>mywidget</tt>). The
        !          1453:     box in the anonymous content contains three children: two text
        !          1454:     (description) elements and an image contained in another box.
        !          1455:     The default orientation for a box is horizontal, but these
        !          1456:     child elements are now positioned vertically.</p>
        !          1457:     <blockquote>
        !          1458:       <div class="c19">
        !          1459:         NOTE
        !          1460:       </div>
        !          1461:       <p>You may notice that the <tt>inherits</tt> attribute is
        !          1462:       preceded with the <tt>xbl</tt>: prefix, unlike other
        !          1463:       attributes in the XBL element set. Why is this unique? It
        !          1464:       guarantees that the effect is on the binding and not directly
        !          1465:       on the element that uses it. This ensures that the element
        !          1466:       can have an <tt>inherits</tt> attribute of its own if needed.
        !          1467:       This scenerio is unlikely and you might wonder why this rule
        !          1468:       does not apply to other attributes used on XBL elements. To
        !          1469:       achieve correct binding, the XBL namespace must be declared
        !          1470:       on an element at a higher level than the element using it,
        !          1471:       most commonly the <tt>&lt;bindings&gt;</tt> container, as
        !          1472:       explained earlier. Here is what the code will look like:</p>
        !          1473:     </blockquote>
        !          1474:     &lt;binding id="my-bindings" xmlns="<a href=
        !          1475:     "http://www.mozilla.org/xbl">http://www.mozilla.org/xbl</a>"
        !          1476:     xmlns:html="<a href=
        !          1477:     "http://www.w3.org/1999/xhtsml">http://www.w3.org/1999/xhtsml</a>"
        !          1478:     xmlns:xbl="<a href=
        !          1479:     "http://www.mozilla.org/xbl">http://www.mozilla.org/xbl</a>"&gt;
        !          1480:     
        !          1481:     <h3><a name="77063"></a> Implementation Inheritance</h3>
        !          1482:     <p>The third type of inheritance, inheritance 
        !          1483:     <!--INDEX inheritance:XBL:implementation inheritance;implementation, XBL inheritance;XBL (eXtensible Binding Language):inheritance:implementation inheritance -->
        !          1484:     of behavior, is also achieved by using the <tt>extends</tt>
        !          1485:     attribute and is useful when you want to use methods or
        !          1486:     properties in another binding. <a href="#77024">Example 7-9</a>
        !          1487:     shows how one binding inherits implementation from another in
        !          1488:     the same file.</p>
        !          1489:     <p><i>Example 7-9: <a name="77024"></a></i> <i>Inheritance of
        !          1490:     behavior between bindings</i></p>
        !          1491: <pre>
        !          1492:  &lt;binding id="Widget1" extends="test.xml#Widget2"&lt;/td&gt;&gt;
1.1       david    1493:    &lt;content&gt;
                   1494:      &lt;xul:box class="insideBox"&gt;
                   1495:        &lt;xul:description value="Top" /&gt;
                   1496:        &lt;xul:box&gt;
                   1497:          &lt;children includes="image" /&gt;
                   1498:        &lt;/xul:box&gt;
                   1499:        &lt;xul:description value="Bottom" /&gt;
                   1500:      &lt;/xul:box&gt;
                   1501:    &lt;/content&gt;
                   1502:  &lt;/binding&gt;
                   1503:  &lt;binding id="Widget2"&gt;
                   1504:    &lt;implementation&gt;
1.8     ! petejc   1505:      &lt;/td&gt;&lt;constructor&gt;
1.1       david    1506:        this.init( );
                   1507:      &lt;/constructor&gt;
                   1508:      &lt;method name="init"&gt;
                   1509:        &lt;body&gt;
1.8     ! petejc   1510:        &lt;!&lt;/td&gt;[CDATA[ dump("This is Widget2");]]&gt;
1.1       david    1511:        &lt;/body&gt;
                   1512:      &lt;/method&gt;
                   1513:    &lt;/implementation&gt;
1.8     ! petejc   1514:  &lt;/binding&gt;
        !          1515: </pre>
        !          1516:     <p>The <tt>Widget1</tt> binding in <a href="#77024">Example
        !          1517:     7-9</a> pulls in <tt>Widget2</tt> using <tt>extends</tt>.
        !          1518:     <tt>Widget2</tt> has implemented a constructor that dumps some
        !          1519:     text to output. When <tt>Widget1</tt> is bound and it does not
        !          1520:     find any implementation to initiate, it looks to the inherited
        !          1521:     binding and, in this case, dumps "This is Widget2" to
        !          1522:     output.</p>
        !          1523:     <p>In a bindings inheritance tree, more than one implementation
        !          1524:     could have a method with the same name. In this case, the most
        !          1525:     derived binding-the one nested deepest in the inheritance
        !          1526:     chain-is the one used. It is even possible for some common DOM
        !          1527:     functions used on the bound element outside of the anonymous
        !          1528:     content to find imitators when implementing the attached
        !          1529:     bindings.</p>
        !          1530: <pre>
        !          1531: &lt;method name="getElementById"&gt;
1.1       david    1532: &lt;parameter name="id" /&gt;
                   1533: &lt;body&gt;
                   1534: &lt;!-- implementation here --&gt;
                   1535: &lt;/body&gt;
1.8     ! petejc   1536: &lt;/method&gt;
        !          1537: </pre>
        !          1538:     <p>If you glance through the source code for the Mozilla
        !          1539:     chrome, you may notice that many of the standard XUL widgets
        !          1540:     used were extended by using XBL. The button is a good
        !          1541:     example.</p>
        !          1542:     <p>On its own, the button can display text with the
        !          1543:     <tt>value</tt> attribute and an image with the <tt>src</tt>
        !          1544:     attribute. Usually, this is sufficient, and you can color the
        !          1545:     button and change the text font with CSS. But you may want to
        !          1546:     take advantage of inherent behaviors in other elements or
        !          1547:     inherit from other bindings. Mozilla buttons are a mix of
        !          1548:     <tt>&lt;box&gt;</tt>, <tt>&lt;text&gt;</tt>, and
        !          1549:     <tt>&lt;image&gt;</tt> elements, and they take on the
        !          1550:     characteristics of each.</p>
        !          1551:     <h2><a name="77064"></a> Event Handling</h2>
        !          1552:     <p><i>Event handlers</i> are attributes that listen 
        !          1553:     <!--INDEX event handling:XBL;XBL (eXtensible Binding Language):event handling -->
        !          1554:     for events. They intercept events raised by certain user
        !          1555:     actions, such as button clicks. When intercepted, control is
        !          1556:     given to the application to carry out some functionality.</p>
        !          1557:     <p>Mouse and keyboard actions are included in these events. XBL
        !          1558:     uses all events that are available on an element in XUL and
        !          1559:     calls them by their name, minus the <tt>on</tt> prefix. Thus,
        !          1560:     for example, the <tt>onmouseclick</tt> event handler becomes
        !          1561:     <tt>mouseclick</tt> in XBL. Refer to <a href=
        !          1562:     "appc.html#77003">Appendix C</a> for a full list of these
        !          1563:     events, which also describes the difference between XUL and XBL
        !          1564:     event handling.</p>
        !          1565:     <p>The <tt><!--INDEX handler element, XBL -->
        !          1566:     &lt;handler&gt;</tt> element contains a single event. Sets of
        !          1567:     individual <tt>&lt;handler&gt;</tt> elements need to be
        !          1568:     included in a <tt>&lt;handlers&gt;</tt> element. The event that
        !          1569:     sets off the action is contained in the <tt>event</tt>
        !          1570:     attribute.</p>
        !          1571: <pre>
        !          1572: &lt;handlers&gt;
1.1       david    1573: &lt;handler event="mousedown" action="dumpString('hello', 'there!')" /&gt;
1.8     ! petejc   1574: &lt;/handlers&gt;
        !          1575: </pre>
        !          1576:     <p>This code uses the <tt>action</tt> attribute to point to
        !          1577:     script that is executed when the event is triggered. The
        !          1578:     alternative way to set up the actions is to put the executable
        !          1579:     script between the handler tags, like you can with the XUL
        !          1580:     <tt>&lt;script&gt;</tt> element. If you use this "embedded"
        !          1581:     syntax, wrap your script in a <tt>CDATA</tt> section so it gets
        !          1582:     interpreted and executed properly:</p>
        !          1583: <pre>
        !          1584: &lt;handlers&gt;
1.1       david    1585: &lt;handler event="mousedown"&gt;
                   1586: &lt;![CDATA[
                   1587: var list = document.getElementById('someElement');
                   1588: list.setAttribute('style', 'display:block;');
                   1589: ]]&gt;
                   1590: &lt;/handler&gt;
1.8     ! petejc   1591: &lt;/handlers&gt;
        !          1592: </pre>
        !          1593:     <p>You cannot use both inline and external scripts in an XBL
        !          1594:     event handler. If this instance does occur, the <tt>action</tt>
        !          1595:     attribute is used. Like code decisions in other contexts, which
        !          1596:     one you use depends on whether you want to reuse the code. In
        !          1597:     our experience, using inline scripts is best in most
        !          1598:     circumstances unless useful code libraries can be accessed in
        !          1599:     external scripts.</p>
        !          1600:     <h3><a name="77065"></a> The Time and Venue</h3>
        !          1601:     <p>Event handlers in XBL allow for fine-tuning, using built-in
        !          1602:     attributes that control when, where, and how they are executed.
        !          1603:     Events are not limited to bindings. They can be registered with
        !          1604:     other UI elements that pre-empt behavior when, for example, a
        !          1605:     <tt>create</tt> or <tt>load</tt> event occurs. This
        !          1606:     registration occurs when using the <tt>attachto</tt>
        !          1607:     attribute.</p>
        !          1608: <pre>
        !          1609: &lt;handler event="create" attachto="window" action="returnNode( )"&gt;
        !          1610: </pre>
        !          1611:     <p>The handler is designed to update the list in the binding
        !          1612:     when the application is loaded up and the window shows. Other
        !          1613:     possible values for <tt>attachto</tt> are <tt>document</tt> and
        !          1614:     <tt>element</tt>.</p>
        !          1615:     <blockquote>
        !          1616:       <div class="c19">
        !          1617:         WARNING
        !          1618:       </div>
        !          1619:       <p>The <tt>attachto</tt> feature is disabled for Mozilla 1.0,
        !          1620:       but it is included here for completeness and to highlight
        !          1621:       XBL's full capabilities.</p>
        !          1622:     </blockquote>
        !          1623:     <p>Another nice feature of event handlers in XBL is the
        !          1624:     existence of extra modifiers on mouse and key events using the
        !          1625:     <tt>modifiers</tt> and the <tt>key</tt> or <tt>keycode</tt>
        !          1626:     attributes. The value is a list of one or more modifier keys
        !          1627:     separated by a comma. The most common combination is the use of
        !          1628:     the <tt>alt</tt>, <tt>control</tt>, or <tt>shift</tt>
        !          1629:     modifiers. The key codes have special identifiers like
        !          1630:     <tt>VK_INSERT</tt> and <tt>VK_UP</tt>.</p>
        !          1631: <pre>
        !          1632: &lt;handler event="keypress" modifiers="control, alt" keycode="VK_UP" action="goUp( )"&gt;
        !          1633: </pre>
        !          1634:     <p>Finally, when talking about event handlers, the
        !          1635:     <tt>phase</tt> attribute allows you to control the point in the
        !          1636:     event's lifecycle when the code is to be executed.</p>
        !          1637: <pre>
        !          1638: &lt;handler event="mouseup" phase="capturing" action="goUp( )"&gt;
        !          1639: </pre>
        !          1640:     <p>The possible values are <tt>bubbling</tt> (the default),
        !          1641:     <tt>targeting</tt>, and <tt>capturing</tt>.</p>
        !          1642:     <p>Here is an example of a handler implementation that fills a
        !          1643:     tooltip when the <tt>popup</tt> element displaying it is
        !          1644:     shown:</p>
        !          1645: <pre>
        !          1646: &lt;handler event="popupshowing"&gt;
1.1       david    1647: &lt;![CDATA[
                   1648: var label = "";
                   1649: var tipNode = document.tooltipNode;
                   1650: if (tipNode &amp;&amp; tipNode.hasAttribute("tooltiptext"))
                   1651: this.label = tipNode.getAttribute("tooltiptext");
                   1652: ]]&gt;
1.8     ! petejc   1653: &lt;/handler&gt;
        !          1654: </pre>
        !          1655:     <p>This event handler first checks that the current
        !          1656:     <tt>popup</tt> is in fact a tooltip via the document's
        !          1657:     <tt>tooltipNode</tt> property and then extracts the text from
        !          1658:     it. This text is assigned to the binding's label, which will
        !          1659:     propagate via inheritance to the text display content widget
        !          1660:     used in the binding, which could be a <tt>label</tt> or
        !          1661:     <tt>description</tt> element.</p>
        !          1662:     <h2><a name="77066"></a> Resources for Bindings</h2>
        !          1663:     <p>This chapter stresses that 
        !          1664:     <!--INDEX bindings:XBL:resources;XBL (eXtensible Binding Language):bindings:resources;resources:bindings, XBL -->
        !          1665:     bindings used in XUL documents are designed to be modular,
        !          1666:     self-contained widgets that have a certain appearance and carry
        !          1667:     out a specific set of functionality. This final section extends
        !          1668:     the notion of XBL as an organization of content, behavior, and
        !          1669:     event handling by describing extra resources (such as
        !          1670:     stylesheets and pictures) that are available in the XBL
        !          1671:     framework for use in your bindings. If you are creating
        !          1672:     templates, for example, you should consider using these
        !          1673:     approaches to application development.</p>
        !          1674:     <h3><a name="77067"></a> Stylesheets in XBL</h3>
        !          1675:     <p>You can include stylesheets 
        !          1676:     <!--INDEX XBL (eXtensible Binding Language):stylesheets;stylesheets:XBL -->
        !          1677:     in an XBL document by using the XBL-specific element <tt>
        !          1678:     <!--INDEX stylesheet element, XBL --> &lt;stylesheet&gt;</tt>.
        !          1679:     The example below shows the color-picker stylesheet as it would
        !          1680:     be included in a <tt>&lt;resources&gt;</tt>-containing element,
        !          1681:     allowing styles contained therein to be used by the bindings
        !          1682:     that referenced it.</p>
        !          1683: <pre>
        !          1684: &lt;stylesheet src="chrome://xfly/skin/color-picker.css" /&gt;
        !          1685: </pre>
        !          1686:     <p>The <tt>&lt;stylesheet&gt;</tt> element is intended for the
        !          1687:     styling of bound elements and anonymous content. It can be used
        !          1688:     on anonymous content generated by the binding and in explicit
        !          1689:     children in documents that use the bindings. Typically, you
        !          1690:     would include this element in a binding and inherit it to style
        !          1691:     other bindings when there are many bindings that have a similar
        !          1692:     appearance.</p>
        !          1693: <pre>
        !          1694: &lt;binding id="popup-base"&gt;
1.1       david    1695: &lt;resources&gt;
                   1696: &lt;stylesheet src="chrome://global/skin/popup.css" /&gt;
                   1697: &lt;/resources&gt;
1.8     ! petejc   1698: &lt;/binding&gt;
        !          1699: </pre>
        !          1700:     <p>Then you can access the stylesheet in your binding by using
        !          1701:     the <tt>extends</tt> attribute:</p>
        !          1702: <pre>
        !          1703: &lt;binding id="popup" extends="chrome://global/content/bindings/popup.xml#popup-base"&gt;
        !          1704: </pre>
        !          1705:     <p>Beyond this static usage of stylesheets, two attributes,
        !          1706:     <tt>applyauthorstyles</tt> and <tt>styleexplicitcontent</tt>,
        !          1707:     can affect the appearance of a binding element if a stylesheet
        !          1708:     is applied to it. Although they are part of the XBL 1.0
        !          1709:     specification, these attributes were not implemented at the
        !          1710:     time of writing. They are attributes of the <tt>
        !          1711:     <!--INDEX binding element, XBL:attributes;attributes:binding element -->
        !          1712:     &lt;binding&gt;</tt> element.</p>
        !          1713:     <dl>
        !          1714:       <dt>applyauthorstyles</dt>
        !          1715:       <dd>A Boolean value that determines the use of stylesheets
        !          1716:       from the document that contains the bound element. The
        !          1717:       default is false.</dd>
        !          1718:       <dt>styleexplicitcontent</dt>
        !          1719:       <dd>A Boolean value that indicates whether the stylesheets
        !          1720:       loaded in the XBL document can be applied to a bound
        !          1721:       element's explicit children and not just the bound element
        !          1722:       itself. The default is false.</dd>
        !          1723:     </dl>
        !          1724:     <p>Stylesheets take effect from the inside scope and move
        !          1725:     outwards. This means that styles on a binding can be overridden
        !          1726:     easily by styles attached to elements contained in anonymous
        !          1727:     content.</p>
        !          1728:     <p>The <tt>&lt;image&gt;</tt> XBL element works much like a XUL
        !          1729:     element and pulls in the image by using the <tt>src</tt>
        !          1730:     attribute.</p>
        !          1731: <pre>
        !          1732: &lt;binding id="images"&gt;
1.1       david    1733: &lt;resources&gt;
                   1734: &lt;image src="plane.png"/&gt;
                   1735: &lt;image src="boat.png"/&gt;
                   1736: &lt;image src="bicycle.png"/&gt;
                   1737: &lt;/resources&gt;
1.8     ! petejc   1738: &lt;/binding&gt;
        !          1739: </pre>
        !          1740:     <p>If an element calls this binding, the pictures would lay out
        !          1741:     side-by-side horizontally in the bound document.</p>
        !          1742:     <hr>
        !          1743:     <hr>
        !          1744:     <a name="253"></a><a href="#b253">[Back]</a> <a name=
        !          1745:     "77025"></a> This example is modified code taken from <i><a
        !          1746:     href=
        !          1747:     "http://www.segment7.net/mozilla/GoogleAPI/GoogleAPI.html">http://www.segment7.net/mozilla/GoogleAPI/GoogleAPI.html</a></i>
        !          1748:     , and is covered by a three-clause BSD license. More on SOAP
        !          1749:     and the SOAP API in Mozilla can be found at <i><a href=
        !          1750:     "http://lxr.mozilla.org/mozilla/source/extensions/xmlextras/docs/Soap_">
        !          1751:     http://lxr.mozilla.org/mozilla/source/extensions/xmlextras/docs/Soap_</a></i>
        !          1752:     Scripts_in_Mozilla.html . 
        !          1753:     <hr>
        !          1754:     <a name="254"></a><a href="#b254">[Back]</a> <a name=
        !          1755:     "77026"></a> The Google API requires a Google Key, and more
        !          1756:     information can be found at <i><a href=
        !          1757:     "http://www.google.com/apis/">http://www.google.com/apis/</a></i>
        !          1758:     . 
        !          1759:     <hr>
        !          1760:     <br>
        !          1761:     <br>
        !          1762:     File a <a href=
        !          1763:     "http://mozdev.org/bugs/enter_bug.cgi?product=books">Bug</a>
        !          1764:     for chapter 7. <!-- ?php require(NOTES); ? -->
        !          1765:     <?php $post_to_list=NO; $author='reviewers@mozdev.org'; $target_page='ch07'; require(NOTES); ?>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>