File:  [mozdev] / books / www / chapters / ch07.html
Revision 1.8: download - view: text, annotated - select for diffs - revision graph
Wed Dec 11 18:57:10 2002 UTC (17 years, 5 months ago) by petejc
Branches: MAIN
CVS tags: HEAD
cleaned up html code w/ html tidy

--pete

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

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