W3C home > Mailing lists > Public > www-html-editor@w3.org > January to March 2008

DOM event phases and the XML Events module

From: John Boyer <boyerj@ca.ibm.com>
Date: Thu, 14 Feb 2008 12:59:03 -0800
To: public-webapi@w3.org, www-html-editor@w3.org
Message-ID: <OFBCA64F19.FF08D201-ON882573EF.00073E01-882573EF.00734469@ca.ibm.com>
Due to my work on XForms, I am fairly familiar with the XML Events 
recommendation [1].

[1] XML Events. http://www.w3.org/TR/2003/REC-xml-events-20031014/

It is odd that a citation of DOM 2 Events [2]  appears in the normative 
references considering that none of the normative sections of [1] make a 
direct reference to it, only the informative sections.

[2] DOM 2 events. 
http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/

As a result, in the normative part of XML Events [2], I am led to believe 
that the following has a reasonable meaning:

<someElement id="X"/>

<ev:listener event="some-event" target="X" observer="X" phase="capture" 
...> ... </listener>
 
This listener element listens for the occurrence of some-event at the 
element identified by X in the capture phase of the event propagation. 
Further, the event is also targeted at X.

The normative description of the phase attribute takes the trouble to note 
that a non-bubbling event cannot have an observer other than the target, 
but it makes no note to the effect that the observer for an event in the 
capture phase must be an ancestor of the target.

So, one goes to the handy (informative) introduction to XML events, which 
does reference DOM 2 events, and then explains in both words and picture 
that the capture phase of an event includes the entire path from the root 
element to the target element of the event: "... when an event occurs it 
is dispatched by passing it down the document tree in a phase called 
capture to the element where the event occurred (called its target), "

*** Alas the the second paragraph of Section 1.2.2 of DOM 2 Events [2] 
does not support the above claim.  It states clearly that if you have a 
listener for an event at the target in the capture phase, the handler will 
not occur.  Therefore, I would ask that an erratum be published for XML 
events [1] to correct both the wording and the diagram in Section 1, and 
add a note to the normative description of the phase attribute.  Then, 
please update the spec as soon as possible, and use the update as a means 
to restore the current XML Events recommendation to the short name 
http://www.w3.org/TR/xml-events/ (right now, links to this short name have 
incorrectly been directed to the working draft for XML Events 2).

*** Please also correct the intro section and normative text of the phase 
attribute in XML Events 2, since the same problems are there too.

The next problem is that XML Events [1] seems to amalgamate the event at 
the target and the bubbling of the event into a single phase called 
"default".  This seems to match DOM 2 Events, but it is broken because 
events that don't bubble still occur on the target.  It is also 
inconvenient because it forces me to put an ID on an element if I want to 
listen for an event that is targeted at that element while ignoring the 
same event if it bubbles up from a descendant of that element.

In XForms, I want to be able to do something like this, only without using 
an ID:

<trigger id="X">
    <label>Submit</label>
    <action ev:event="DOMActivate" ev:target="X">
         <send if="no errors" submission="doSubmission"/>
         <message if="some error condition">
                 There is an error.  Are you sure?
                  <submit 
submission="doSubmission"><label>Yes</label></submit>
                  <trigger><label>No</label></trigger>
         </message>
   </action>
</trigger>

With this markup, the trigger and submit elements could be presented as 
buttons.  When the button corresponding to the outer trigger is pressed, 
the trigger receives a DOMActivate event, which runs the handler code in 
the action element.  If there is "some error condition" then a message 
action runs that asks the user if they are sure.  If they press the button 
for either the Yes submit or the No trigger, that element receives a 
DOMActivate.  Since DOMActivate bubbles, the outermost trigger also sees 
the event.  However, the action handler also contains ev:target="X", which 
means that the outer trigger's action handler will only run when it 
observes a DOMActivate that is targeted at the element with ID of X. 

This is how we avoid a loop of the outer action handler when that action 
handler contains elements that are targets for the same kind of event that 
the handler handles.

I would like to be able to do this without the use of an ID, and I believe 
it can be done by separating the bubble phase from the target phase.  In 
other words, I believe the following markup would work:

<trigger>
    <label>Submit</label>
    <action ev:event="DOMActivate" ev:phase="target">
         <send if="no errors" submission="doSubmission"/>
         <message if="some error condition">
                 There is an error.  Are you sure?
                  <submit 
submission="doSubmission"><label>Yes</label></submit>
                  <trigger><label>No</label></trigger>
         </message>
   </action>
</trigger>

If you look at the working draft of DOM 3 events [3], it appears that the 
phases have been more rigorously defined.  The capture phase excludes the 
target, but the bubble phase excludes the target as well, and  the target 
is given a phase of its own.

[3] DOM 3 events. http://www.w3.org/TR/DOM-Level-3-Events/

But there are the following problems:

*** In [3], the text separates the three phases, but the interface for 
EventTarget in section 1.6 does not properly support the distinction.  XML 
events is a markup that maps to what the interface functions can actually 
do, not just what the spec says, so this needs to be fixed.  Specifically, 
the methods all have a boolean parameter called useCapture.  This allows 
you to say whether or not the event listener is on the capture phase, but 
a boolean is insufficient now that there are three phases.  As you can see 
from above, I would like to be able to invoke addEventListener() and use 
neither capture nor bubble.

*** The XML Events 2 spec is still based on DOM 2 events.  It needs to 
upgrade to DOM 3 events so that we can get access to this extra phase.

Finally, I believe that DOM 3 events is missing a feature.  In the XForms 
spec, I wanted to be able to describe the behavior of repeat index 
updating in terms of handlers for the events xforms-insert and 
xforms-delete.  But if the form author writes their own handlers for those 
events, it seems reasonable that the repeat index should already have been 
updated before the form author's handlers run.  So, I wanted to be able to 
have a listener for "the event at the target in the capture phase" since 
the form author's handlers would be likely to listen for "the event at the 
target in the bubble phase" (i.e. the default phase).  I also wanted the 
form author to be able to handle the xforms-insert or xforms-delete 
*before* repeat index updating by listening for the event on the parent of 
the target in the capture phase. 

But it seems there is no way to handle an event at the target in the 
capture phase, so the XForms repeat index updaters need to listen for the 
xforms-insert and xforms-delete on the parent of the target in the capture 
phase.  In turn, this means that if a form author wants to do something 
with those events before repeat index updating, then they must listen for 
the events in the capture phase on the grandparent of the target.  The 
problem is that the grandparent of the target is not going to be an 
element in the XForms namespace, so it is very unclean to tell a form 
author that they have to set up handlers for XForms constructs, but the 
only way to do it is to listen on elements that are not in XForms.

*** Net-net, I need a way to push my event handler on the target to the 
front of the queue of stuff that happens at the target.  It is almost as 
if we need not just "AT_TARGET" phase, but rather "ENTERING_TARGET" and 
"EXITING_TARGET".  Could you please consider adding a feature like this?

Thanks,
John M. Boyer, Ph.D.
Senior Technical Staff Member
Lotus Forms Architect and Researcher
Chair, W3C Forms Working Group
Workplace, Portal and Collaboration Software
IBM Victoria Software Lab
E-Mail: boyerj@ca.ibm.com 

Blog: http://www.ibm.com/developerworks/blogs/page/JohnBoyer
Blog RSS feed: 
http://www.ibm.com/developerworks/blogs/rss/JohnBoyer?flavor=rssdw
Received on Thursday, 14 February 2008 20:59:23 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 27 March 2012 18:17:57 GMT