event.currentTarget documentation inaccurate for delegated events
|Reported by:||jmm||Owned by:||jmm|
The event.currentTarget documentation doesn't seem to be quite accurate for delegated events. It says:
Description: The current DOM element within the event bubbling phase.
But it seems that for delegated events,
currentTarget is hijacked to mean "the element that matches the selector" (the selector part of the
.on( events [, selector] [, data] , handler(eventObject) ) signature). In other words, it simulates the
currentTarget that would exist if the listener was directly bound to the element matching the selector.
I get the impression that has been the case since
delegate() was added in 1.4.2, for example from ticket #10563
event.delegateTarget, which is really the current element within the event bubbling phase, isn't it?
The situation I'm describing is illustrated by the following evaluating to
true (in FF 7 Win, Chrome 18 Win) in a delegated handler:
event.currentTarget !== event.originalEvent.currentTarget &&
event.delegateTarget === event.originalEvent.currentTarget
My interpretation of this is:
- A long time ago (1.4.2), a useful piece of data (the DOM element that matches the selector in a delegation ) was added to
jQuery.Event, which was good.
- The data was added by co-opting the existing DOM
Event.currentTargetproperty, changing its meaning. I'm wondering if that was as good of an idea.
- 1.7 added
event.delegateTargetto provide (restore) access to the data that is lost as a result of
currentTargetbeing co-opted to store other data.
- Perhaps if this were being created from scratch today
delegateTargetwould be reversed, so that
currentTargetcorresponds to the element where the listener is registered (the actual current element within the bubbling phase) and
delegateTargetcorresponds to the element matching the selector.
I speculate that because, if there's going to be an additional property (
delegateTarget) for these events to convey data above and beyond what the DOM includes, it seems to me like it would make sense to preserve the meaning of the existing property,
currentTarget, and embed the new information in the new, non-standard property.
But, I imagine it's either intentional (?), or too late to change the meaning of
currentTargetfor delegated events anyway. In any case, it would be good for the
currentTargetdocumentation and other relevant parts to accurately describe the situation.
As an aside, where the `.on()` documentation says:
jQuery passes the handler an event object it can use to analyze and change the status of the event. This object is a *normalized subset* of data provided by the browser;
With the addition of things like
delegateTarget (and in some cases other things, like
currentTarget), it's not strictly true that the event object is a subset of data provided by the browser. I guess to be really accurate it could say something like "includes a *normalized subset* of data included in the W3C DOM Event interface, as well as additional data provided by the browser and / or jQuery".