Chapter 5. Scripting Mozilla- P2 Figure 5-2. Toggling the state of menu items in xFly The following section explains more about hooking scripts up to the interface. Needless to say, when you use a method like getElementsByAttribute that operates on all elements with a particular attribute value, you must be careful not to grab elements you didn't intend (like a button elsewhere in the application that gets disabled for other purpose). Notes [1] You can use other DOM methods, but these methods are most commonly used in the XPFE. Mozilla's support for the DOM is so thorough that you can use the W3C specifications as a list of methods and properties available to you in the chrome and in the web content the browser displays. The full W3C activity pages, including links to the specifications implemented by Mozilla, can be found at http://www.w3.org/DOM/. 5.3. Adding Scripts to the UI Once you are comfortable with how JavaScript works in the context of the user interface layer and are familiar with some of the primary DOM methods used to manipulate the various elements and attributes, you can add your own scripts to your application. Though you can use other techniques to get scripts into the UI, one of the most common methods is to use Mozilla's event model, which is described in the next few sections. 5.3.1. Handling Events from a XUL Element Events are input messages that pass information from the user interface to the application code. Capturing this information, or event handling, is how you usually tell scripts when to start and stop. When the user clicks a XUL button, for instance, the button "listens" for the click event, and may also handle that event. If the button itself does not handle the event (e.g., by supplying executable JavaScript in an event handler attribute), then the event "bubbles," or travels further up into the hierarchy of elements above the button. The event handlers in Example 5-3 use simple inline JavaScript to show that the given event (e.g., the window loading in the first example, the button getting clicked in the second, and so on) was fired and handled. As in HTML, predefined event handlers are available as attributes on a XUL element. These attributes are entry points where you can hook in your JavaScript code, as these examples show. Note that event handler attributes are technically a shortcut, for which the alternative is to register event listeners explicitly to specified elements. The value of these on[event] event handler attributes is the inline JavaScript that should be executed when that event is triggered. Example 5-5 shows some basic button activation events. Example 5-5. Basic event handler attributes <window onload="dump('this window has loaded\n');" /> <button label="onclick-test" onclick="dump('The event handler onclick has just been used\n');" /> <button label="oncommand-test" oncommand="dump('The event handler oncommand has just been used\n');" /> <menulist id="custom" onchange="doMyCustomFunction( );" /> While the window and button events in Example 5-5 carry out some inline script, there is a variation with the onchange handler attached to the menulist element. onchange contains a JavaScript function call whose definition may live in the XUL document itself or in an external file that is included by using the src attribute on a script element: <script type="application/x-javascript" src="chrome://mypackage/content/myfile.js" /> A large basic set of event handler attributes is available for use on XUL elements (and HTML elements). Appendix C has a full listing of these events along with explanations. The following subset shows the potential for script interaction when the UI uses event handlers: onabort onblur onerror onfocus onchange onclick oncontextmenu ondestroy onload onpaint onkeydown onkeypress onkeyup onunload onmousemove onmouseout onmouseover onmouseup onmousedown onrest onresize onscroll onselect onsubmit Some of these event handlers work only on particular elements, such as window, which listens for the load event, the paint event, and other special events. To see all event handler attributes on a particular element, you can execute the short script in Example 5-6 , which uses the for in loop in JavaScript to iterate over the members of an object -- in this case, a XUL element. Example 5-6. Getting event handler attributes from an element <script type="application/x-javascript"> function listElementHandlers(aObj) { if(!aObj) return null; for(var list in aObj) if(list.match(/^on/)) dump(list+'\n'); } </script> <button label="oncommand" oncommand="listElementHandlers(this);" /> The function you added in Example 5-4 is also an example of event handler code in an application's interface. 5.3.2. Events and the Mozilla Event Model The event model in Mozilla is the general framework for how events work and move around in the user interface. As you've already seen, events tend to rise up through the DOM hierarchy -- a natural process referred to as event propagation or event bubbling. The next two sections describe event propagation and its complement, event capturing. 5.3.2.1. Event propagation and event bubbling This availability of events in nodes above the element of origin is known as event propagation or event bubbling. Event bubbling means you can handle events anywhere above the event-raising element in the hierarchy. When events are handled by elements that did not initiate those events, you must determine which element below actually raised the event. For example, if an event handler in a menu element handles an event raised by one of the menu items, then the menu should be able to identify the raising element and take the appropriate action, as shown in Example 5-7 . In this example, a JavaScript function determines which menuitem was selected and responds appropriately. Example 5-7. Event propagation <script type="application/x-javascript"> function doCMD(el) { v = el.getAttribute("label") switch (v) { case "New": alert('New clicked'); break; case "Open": alert('Open clicked'); break; case "Close": alert('Close clicked'); break; } } </script> . <menu class="menu" label="File" oncommand="doCMD(event.target)"> <menupopup> <menuitem label="New" /> <menuitem label="Open" /> <menuitem label="Close" /> </menupopup> </menu> The event handler in the parent node menu finds out which child menuitem was actually clicked by using event.target and takes action accordingly. Let's walk through another possible scenario. If a user of an application selects an item from a menu list, you could get the node of that item by using event.target. Your script could then abstract that item's value or other information, if necessary. 5.3.2.1.1. Trapping events When an event is raised, it is typically handled by any node interested in it as it continues its way up the DOM hierarchy. In some cases, you may want to handle an event and then prevent it from bubbling further up, which is where the DOM Event method stopPropagation( ) comes in handy. Example 5-8 demonstrates how event bubbling can be arrested very simply. When the XUL document in Example 5-8 loads, an event listener is registered with a row in the tree. The event listener handles the event by executing the function stopEvent( ). This function calls an event object method, stopPropagation, which keeps the event from bubbling further up into the DOM. Note that the tree itself has an onclick event handler that should display a message when clicked. However, the stopEvent( ) method has stopped propagation, so after the data in the table is updated, the event phase is effectively ended. In this case, the function was used to trap the event and handle it only there. Example 5-8. stopPropagation( ) event function <?xml version="1.0"?> <!DOCTYPE window> <window id="test-win" xmlns="http://www.mozilla.org/keymaster/gatekeeper/ there.is.only.xul" orient="vertical" onload="load( );"> <script type="application/x-javascript"> function load( ) { el = document.getElementById("t"); el.addEventListener("click", stopEvent, false); } function stopEvent(e) { // this ought to keep t-daddy from getting the click. e.stopPropagation( ); } </script> <tree> <!-- tree columns definition omitted --> <treechildren flex="1" > <treeitem id="t-daddy" onclick="alert('t-daddy');" // this event is never fired container="true" parent="true"> <treerow id="t"> <treecell label="O'Reilly" id="t1" /> <treecell label="http://www.oreilly.com" id="t2" /> </treerow> </treeitem> </treechildren> </tree> </window> 5.3.2.2. Capturing events Event capturing is the complement of event bubbling. The DOM provides the addEventListener method for creating event listeners on nodes that do not otherwise supply them. When you register an event listener on an ancestor of the event target (i.e., any node above the event-raising element in the node hierarchy), you can use event capturing to handle the event in the ancestor before it is heard in the target itself or any intervening nodes. To take advantage of event capturing (or event bubbling with elements that do not already have event listeners), you must add an event listener to the element that wants to capture events occurring below it. Any XUL element may use the DOM addEventListener method to register itself to capture events. The syntax for using this method in XUL is shown here: . Chapter 5. Scripting Mozilla- P2 Figure 5- 2. Toggling the state of menu items in xFly The following. executed when that event is triggered. Example 5- 5 shows some basic button activation events. Example 5- 5. Basic event handler attributes <window onload="dump('this