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

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

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