fireOnce events immediately execute new subscription callbacks after they have been fired. Separately, returning false from an event subscriber (unfortunately) has been overloaded to be equivalent to e.preventDefault(); e.stopImmediatePropagation(). The latter call stops the processing of further subscribers. However, it doesn't stop further subscriptions from being made for a subsequent fire().

var handle = foo.on("notAFireOnce", function (e) {

    e.stopImmediatePropagation();

});

foo.on("notAFireOnce", function (e) {

    Y.log("this is not called the first time, but is after handle.detach() is called");

});


foo.fire("notAFireOnce"); // no log

foo.on("notAFireOnce", function (e) {

    Y.log("subsequent subscriptions are A OK");

});

foo.fire("notAFireOnce"); // no log because the first sub calls stopImmediatePropagation

handle.detach();

foo.fire("notAFireOnce"); // calls both Y.log subscribers

The same is true for fireOnce events, but each call to on() or after() after the event is fired ignores previous subscriptions (they've already been notified) and is effectively a call to on()+fire().

So it sounds like what you're asking for is that if a fireOnce event is stopped with stopImmediatePropagation or return false, that post-fire() subscriptions don't execute.

Is this a fair summation?

That sounds like it would be most consistent.

Fortunately it turns out that isn't as much of a problem as I had feared, since the preventDefault/stopPropagation behavior only occurs from an actual "false" return value, but no other falsey values including "undefined'. However it seems to me that the 'false' return value behavior (independent of the fireOnce issue) is worthy of a paragraph in the main Event documentation page, or at least the API docs. You can even label it as a "feature" ;)

I've created #2530477 to track the code related modification. I'll leave this ticket to track the documentation change. Docs I can probably do for 3.4.0, but not the code change.

I've added verbiage in the Event user guide and EventTarget's on() method API docs for 3.4.0.

More EventTarget methods should have their docs updated to make sense in the context of Node, but it's a start.

Add API doc content for on + return falsennPartial solution, as the other methods neednto have language friendly for reading on thenNode API docs (inherited methods).nnFixes #2530448
View Commit: 389a9f8339d5c537895c22b7a6b55d96d9aa6639