Chapter Extending the UI with XBL- P4 7.4.4 Extra Binding Content and Insertion Points All examples in the chapter have so far dealt with standard binding content rendering within a bound document The processes outlined in this section can, in one sense, be seen as abnormal because they allow ordering of the content to change based on insertion points defined in the binding This process is done with the XBL element 7.4.4.1 Working with children of the bound element Zero or more children can be contained in anonymous content These children are marked up with the XBL-specific tag They can be either the content of the element using the binding or anonymous content generated by the base binding If the tag contains its own elements, then it will be used as the default content If the element the binding is attached to contains children, the default content will be ignored The location of the tags determines the content's insertion point Insertion points play an important role in the generation of content within a template because they affect how the content is displayed and accessed by the DOM This stripped-down binding has only a vertical box as its own content and looks to the children of the bound element for more content by using the element Here is the XUL content that uses the binding: When the binding is attached and the content is drawn, the insertion point for the two labels is inside the container vertical box inside the binding This scenario could be used when a binding is used multiple times Each time, it needs to be rendered differently with extra content that can be provided this way 7.4.4.2 Selective inclusion Sometimes multiple siblings are located within a box in the XUL, but you want to use only some of them in the binding, such as when a user logs into a system and content is displayed depending on its level of membership In these cases, you can be selective about which children should be included in the binding Example 7-5 shows how to use the includes attribute on the element Example 7-5 Selective inclusion of child content in a binding The children element in Example 7-5 essentially tells, "Of all the content contained in the bound element, insert only the image element at this particular insertion point." Here is the XUL code that goes with this example: The image is the only child taken from the XUL content and the label is ignored If you have children that are not defined in the includes attribute, then the binding is discarded and not used If the bound element uses another element in addition to an image element, the binding is discarded and only the explicit content is used If the image element isn't used at all, the binding is discarded This example renders the image and the label and discards the binding The anonymous content does not appear because the binding is discarded and only the explicit content is used 7.5 Inheritance In XBL, inheritance is the process in which one object included in another object is allowed to use properties from that parent object These properties can be many things, depending on the implementation, ranging from methods to attribute property values Inheritance is a concept familiar in programming languages, most notably object-oriented ones It's not something alien to markup, however, and it is deployed effectively in XBL This section examines three forms of XBL inheritance: binding, attribute, and implementation As you will see, inheritance promotes self-contained (modular) and flexible bindings that permit shared content across and within XBL documents 7.5.1 Binding Inheritance Binding inheritance occurs when one binding is linked to another binding or XUL element and uses some or all properties of it, whether they are content or behavior A binding can inherit from another binding that exists in the same or different file In one way, this useful feature makes a binding like a class, with content and methods that can be used elsewhere Bindings become modules, which prevents code duplication, makes maintenance easier, and gets slotted in and out of documents Linkage or inheritance is enabled by the extends attribute on the element This attribute contains the URL of the binding that you inherit from This URL is made up of the location and name of the file that contains the binding (the # symbol), and the id of the specific binding being used In this way, it is similar to the access method used in CSS attachment Although it is in the XBL 1.0 specification, Mozilla hasn't fully implemented type="inherits" on the children tag yet, so the best way to work with binding inheritance is to use the extends attribute Example 7-6 shows a few bindings used in the implementation of the listbox cell in the Mozilla tree It illustrates how extends is used to inherit from another binding Example 7-6 Binding inheritance In Example 7-6, listcell-iconic inherits listcell In turn, listcell inherits list-box-base, which holds resources The listcell binding is a cell with text only and the listcell-iconic binding has text and an image Thus, the user has a choice of using a list cell binding with an icon or no icon Yet both of these bindings have access to the stylesheet resource declared in the base binding If listcelliconic is used, the duplicate xul:label is ignored in the inherited binding and the stylesheet inherited from the base binding via the inherited binding is used We've used this technique to illustrate how resources in multiple bindings are shared With binding extensions that use the extends attribute, you can also extend a XUL element as a model, using extensions as a proxy to mimic that XUL element The element may not be included directly in the anonymous content, but its characteristics are still present on the bound element If you use the XUL namespace xul: in the same way you use it for XUL content in a binding, you can inherit the XUL element properties as illustrated in Example 7-7 Example 7-7 Inheriting XUL widget characteristics using extends In Example 7-7, the binding has all of the attributes and behavior of a XUL box Because you extend a box element, the base widget is now a vertical box The anonymous content is laid out according to the box model, and all attributes that are recognized on the bound element are applied to the box 7.5.2 Attribute Inheritance Also known as "attribute forwarding," attribute inheritance is a way for anonymous content to link to the attributes from the bound element When the bound element attribute is changed, this modification filters down to the binding attribute list The code in Example 7-8 shows anonymous content where multiple attributes are picked up by the xbl:inherits attribute, with each one separated by a comma Example 7-8 XBL attribute inheritance The element that inherits the attributes can be anywhere in the chain of anonymous content In this case, it is on the top-level box It assumes the value given to these attributes in the bound element Here is the XUL that uses the binding content from Example 7-8: The xul:box element inherits the attribute values vertical, 1, and middle, respectively, from the bound element (mywidget) The box in the anonymous content contains three children: two text (description) elements and an image contained in another box The default orientation for a box is horizontal, but these child elements are now positioned vertically You may notice that the inherits attribute is preceded with the xbl: prefix, unlike other attributes in the XBL element set Why is this unique? It guarantees that the effect is on the binding and not directly on the element that uses it This ensures that the element can have an inherits attribute of its own if needed This scenerio is unlikely and you might wonder why this rule does not apply to other attributes used on XBL elements To achieve correct binding, the XBL namespace must be declared on an element at a higher level than the element using it, most commonly the container, as explained earlier Here is what the code will look like: 7.5.3 Implementation Inheritance The third type of inheritance, inheritance of behavior, is also achieved by using the extends attribute and is useful when you want to use methods or properties in another binding Example 7-9 shows how one binding inherits implementation from another in the same file Example 7-9 Inheritance of behavior between bindings this.init( ); The Widget1 binding in Example 7-9 pulls in Widget2 using extends Widget2 has implemented a constructor that dumps some text to output When Widget1 is bound and it does not find any implementation to initiate, it looks to the inherited binding and, in this case, dumps "This is Widget2" to output In a bindings inheritance tree, more than one implementation could have a method with the same name In this case, the most derived binding the one nested deepest in the inheritance chain is the one used It is even possible for some common DOM functions used on the bound element outside of the anonymous content to find imitators when implementing the attached bindings If you glance through the source code for the Mozilla chrome, you may notice that many of the standard XUL widgets used were extended by using XBL The button is a good example On its own, the button can display text with the value attribute and an image with the src attribute Usually, this is sufficient, and you can color the button and change the text font with CSS But you may want to take advantage of inherent behaviors in other elements or inherit from other bindings Mozilla buttons are a mix of , , and elements, and they take on the characteristics of each 7.6 Event Handling Event handlers are attributes that listen for events They intercept events raised by certain user actions, such as button clicks When intercepted, control is given to the application to carry out some functionality Mouse and keyboard actions are included in these events XBL uses all events that are available on an element in XUL and calls them by their name, minus the on prefix Thus, for example, the onmouseclick event handler becomes mouseclick in XBL Refer to Appendix C for a full list of these events, which also describes the difference between XUL and XBL event handling The element contains a single event Sets of individual elements need to be included in a element The event that sets off the action is contained in the event attribute This code uses the action attribute to point to script that is executed when the event is triggered The alternative way to set up the actions is to put the executable script between the handler tags, like you can with the XUL element If you use this "embedded" syntax, wrap your script in a CDATA section so it gets interpreted and executed properly: You cannot use both inline and external scripts in an XBL event handler If this instance does occur, the action attribute is used Like code decisions in other contexts, which one you use depends on whether you want to reuse the code In our experience, using inline scripts is best in most circumstances unless useful code libraries can be accessed in external scripts 7.6.1 The Time and Venue Event handlers in XBL allow for fine-tuning, using built-in attributes that control when, where, and how they are executed Events are not limited to bindings They can be registered with other UI elements that pre-empt behavior when, for example, a create or load event occurs This registration occurs when using the attachto attribute The handler is designed to update the list in the binding when the application is loaded up and the window shows Other possible values for attachto are document and element //FIXME did we loose content here? The attachto feature is disabled for Mozilla 1.0, but it is included here for completeness and to highlight XBL's full capabilities Another nice feature of event handlers in XBL is the existence of extra modifiers on mouse and key events using the modifiers and the key or keycode attributes The value is a list of one or more modifier keys separated by a comma The most common combination is the use of the alt, control, or shift modifiers The key codes have special identifiers like VK_INSERT and VK_UP Finally, when talking about event handlers, the phase attribute allows you to control the point in the event's lifecycle when the code is to be executed The possible values are bubbling (the default), targeting, and capturing Here is an example of a handler implementation that fills a tooltip when the popup element displaying it is shown: This event handler first checks that the current popup is in fact a tooltip via the document's tooltipNode property and then extracts the text from it This text is assigned to the binding's label, which will propagate via inheritance to the text display content widget used in the binding, which could be a label or description element 7.7 Resources for Bindings This chapter stresses that bindings used in XUL documents are designed to be modular, self-contained widgets that have a certain appearance and carry out a specific set of functionality This final section extends the notion of XBL as an organization of content, behavior, and event handling by describing extra resources (such as stylesheets and pictures) that are available in the XBL framework for use in your bindings If you are creating templates, for example, you should consider using these approaches to application development 7.7.1 Stylesheets in XBL You can include stylesheets in an XBL document by using the XBL-specific element The example below shows the color-picker stylesheet as it would be included in a -containing element, allowing styles contained therein to be used by the bindings that referenced it The element is intended for the styling of bound elements and anonymous content It can be used on anonymous content generated by the binding and in explicit children in documents that use the bindings Typically, you would include this element in a binding and inherit it to style other bindings when there are many bindings that have a similar appearance Then you can access the stylesheet in your binding by using the extends attribute: Beyond this static usage of stylesheets, two attributes, applyauthorstyles and styleexplicitcontent, can affect the appearance of a binding element if a stylesheet is applied to it Although they are part of the XBL 1.0 specification, these attributes were not implemented at the time of writing They are attributes of the element applyauthorstyles A Boolean value that determines the use of stylesheets from the document that contains the bound element The default is false styleexplicitcontent A Boolean value that indicates whether the stylesheets loaded in the XBL document can be applied to a bound element's explicit children and not just the bound element itself The default is false Stylesheets take effect from the inside scope and move outwards This means that styles on a binding can be overridden easily by styles attached to elements contained in anonymous content The XBL element works much like a XUL element and pulls in the image by using the src attribute If an element calls this binding, the pictures would lay out side-by-side horizontally in the bound document ... from the XUL content and the label is ignored If you have children that are not defined in the includes attribute, then the binding is discarded and not used If the bound element uses another... example renders the image and the label and discards the binding The anonymous content does not appear because the binding is discarded and only the explicit content is used 7.5 Inheritance In... by the extends attribute on the element This attribute contains the URL of the binding that you inherit from This URL is made up of the location and name of the file that contains the