File:  [mozdev] / books / www / chapters / ch07.html
Revision 1.18: download - view: text, annotated - select for diffs - revision graph
Wed Apr 2 19:35:41 2003 UTC (17 years, 2 months ago) by brian
Branches: MAIN
CVS tags: HEAD
consistent way of hiding notes

    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: 
    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;
  160: &lt;bindings id="dataBindings" ...&gt;
  161: &lt;binding /&gt;
  162: &lt;binding /&gt;
  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>
  201: xmlns:xul=
  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;
  243: &lt;content&gt;
  244: &lt;html:div&gt;Mozilla 1.0&lt;/html:div&gt;
  245: &lt;children /&gt;
  246: &lt;/content&gt;
  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;
  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;
  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 {
  331: -moz-binding: url("inputfield.xml#inputfield");
  332: }
  333: </pre>
  334:     <p>It also can be from an inline style:</p>
  335: <pre>
  336: &lt;inputfield
  337: id="ifd"
  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;
  348: &lt;!-- binding content / behavior / handlers --&gt;
  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;
  421: &lt;children/&gt;
  422: &lt;xul:label xbl:inherits="value=label"/&gt;
  423: &lt;xul:textbox anonid="input" flex="1"/&gt;
  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;
  432: &lt;label value="Eric's"/&gt;
  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[
  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","");
  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;
  538: this.input=null;
  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;
  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;
  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;
  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;
  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;
  618: &lt;handler event="mouseover"&gt;
  619: this.input.focus( );
  620: &lt;/handler&gt;
  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;
  638: &lt;stylesheet src="inputfield.css"/&gt;
  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;
  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;
  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;
  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;
  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;
  728: &lt;/mybinding&gt;
  729: &lt;button label="test method"
  730: oncommand="document.getElementById('myNewWidget')
  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;
  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;
  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;
  792: false;
  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;
  805: false;
  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;
  813: &lt;xul:label xbl:inherits="value=title"/&gt;
  814: &lt;xul:spacer flex="1"/&gt;
  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;
  831:    &lt;setter&gt;
  832:      &lt;!&lt;/td&gt;[CDATA[
  833:        this.setAttribute('title',val); return val&lt;/td&gt;;
  834:      ]]&gt;
  835:    &lt;/setter&gt;
  836:    &lt;getter&gt;
  837:      &lt;!&lt;/td&gt;[CDATA[
  838:        return this.getAttribute('title');
  839:      ]]&gt;
  840:    &lt;/getter&gt;
  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;
  875:    &lt;setter&gt;
  876:      &lt;!&lt;/td&gt;[CDATA[
  877:        var s = new SOAPCall( );
  878:        &lt;/td&gt;var q = val;
  879:        if (!s)
  880:          return "Error creating SOAPCall object";
  881:        var soapversion = 0;
  882:        var method = "doGoogleSearch";
  883:        var object = "urn:GoogleSearch";
  884:        var headers = &lt;/td&gt;[ ];
  885:        var params = &lt;/td&gt;[
  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);
  899:        s.transportURI = "<a href=
  900: "http://api.google.com/search/beta2">http://api.google.com/search/beta2</a>"
  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;
  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 {
 1037: -moz-binding : url("mybindings.xml#my-binding");
 1038: }
 1039: mybinding.unattached {
 1040: -moz-binding : url("");
 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;
 1115:    &lt;content&gt;
 1116:      &lt;xul:vbox&gt;
 1117:        &lt;xul:button label="A" id="button1"
 1118:          oncommand="alert(this.parentNode.parentNode.nodeName)"&lt;/td&gt;/&gt;
 1119:        &lt;xul:button label="B" id="button2"
 1120:          oncommand="alert(this.ownerDocument.firstChild.nodeName)"&lt;/td&gt;/&gt;
 1121:      &lt;/xul:vbox&gt;
 1122:    &lt;/content&gt;
 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;
 1167: &lt;![CDATA[
 1168: var list = document.getAnonymousNodes(this)[0];
 1169: return list.selectedItem.getAttribute('label');
 1170: ]]&gt;
 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;
 1235: &lt;content&gt;
 1236: &lt;xul:vbox&gt;
 1237: &lt;children /&gt;
 1238: &lt;/xul:vbox&gt;
 1239: &lt;/content&gt;
 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;
 1248: &lt;label value="this is child 1" /&gt;
 1249: &lt;label value="this is child 2" /&gt;
 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;
 1272:    &lt;content&gt;
 1273:      &lt;xul:vbox class="insideBox"&gt;
 1274:        &lt;xul:description value="Top" /&gt;
 1275:        &lt;xul:box&gt;
 1276:          &lt;children includes="image" /&gt;
 1277:        &lt;/xul:box&gt;
 1278:        &lt;xul:description value="Bottom" /&gt;
 1279:      &lt;/xul:vbox&gt;
 1280:    &lt;/content&gt;
 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
 1286:     particular insertion point." 
 1287: 		<br/>For example:</p>
 1288: <pre>
 1289: &lt;mybinding id="myNewWidget" flex="1"&gt;
 1290:   &lt;image src="http://www.mozdev.org/sharedimages/header.gif" /&gt;
 1291:   &lt;label value="a non includes element" /&gt;
 1292: &lt;/mybinding&gt;
 1293: </pre>
 1294:     <p>The <tt>image</tt> is the only child inserted and
 1295:     the <tt>label</tt> element is ignored.</p>
 1296:     <p>If you have children that are not defined in the
 1297:     <tt>includes</tt> attribute, then the binding is discarded and
 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
 1305:     to an image element, again the binding is discarded and only the
 1306:     explicit content is used.</p>
 1307: <pre>
 1308: &lt;mybinding id="myNewWidget" flex="1"&gt;
 1309:   &lt;image src="http://www.mozdev.org/sharedimages/header.gif" /&gt;
 1310:   &lt;label value="an element" /&gt;
 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;
 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"
 1365:      extends="chrome://global/content/bindings/listbox.xml#listbox-base"&lt;/td&gt;&gt;
 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"
 1375:      extends="chrome://global/content/bindings/listbox.xml#listcell"&lt;/td&gt;&gt;
 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;
 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;
 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;
 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;
 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;
 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;
 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;
 1511:      &lt;/td&gt;&lt;constructor&gt;
 1512:        this.init( );
 1513:      &lt;/constructor&gt;
 1514:      &lt;method name="init"&gt;
 1515:        &lt;body&gt;
 1516:        &lt;!&lt;/td&gt;[CDATA[ dump("This is Widget2");]]&gt;
 1517:        &lt;/body&gt;
 1518:      &lt;/method&gt;
 1519:    &lt;/implementation&gt;
 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;
 1538: &lt;parameter name="id" /&gt;
 1539: &lt;body&gt;
 1540: &lt;!-- implementation here --&gt;
 1541: &lt;/body&gt;
 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;
 1579: &lt;handler event="mousedown" action="dumpString('hello', 'there!')" /&gt;
 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;
 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;
 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;
 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;
 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;
 1701: &lt;resources&gt;
 1702: &lt;stylesheet src="chrome://global/skin/popup.css" /&gt;
 1703: &lt;/resources&gt;
 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;
 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;
 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. 
 1771:     <?php $hide_text_control=1; $post_to_list=NO; $author='reviewers@mozdev.org'; // require(NOTES);>

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