Element scope listeners. HOW TO

[iSuslov]

In the doc there is no word about how to listen events that bubbles. For example this does not work:

static get listeners() {
                return {"message-added": "_messageAdded"}
}

No docs. Nothing. Just addEventListener inside callback. Do we have to remove all eventListeners manually?

[jsilvermist]

Related: Polymer/polymer#4632

[ghost]

#2039

[arthurevans]

Do we need to clarify the advice in here: https://www.polymer-project.org/2.0/docs/devguide/events#imperative-listeners?

Things that could perhaps be clearer:

• If you want to add a listener on the element itself (not a shadow DOM child), you need to do it imperatively, unless Polymer/polymer#4632 lands.
• If you're adding a listener to the element or a shadow DOM child, you don't have to remove it. (i.e., you could add it once in ready. Or better yet, after first render).
• If you're adding a listener outside of the element (for example, on window), you need to remove it (for example, add in connectedCallback, remove in disconnectedCallback).

[arthurevans]

See also: https://github.com/Polymer/docs/pull/2343 which is somewhat related. The author of that PR is correct that if you're doing this.addEventListener, you don't actually need to bind the event listener (the context object (i.e., this) should be the node that you added the listener to (i.e., the same "this").

The added discussion in that PR is a bit confusing, though. It doesn't matter whether the thing you add an event handler to is a custom element or not. For example:

let hostElement = this;
let button = hostElement.shadowRoot.querySelector('button');
button.addEventListener('click', hostElement._onClick);

When the host element's _onClick method is called, this is set to button (that is, it matches the event's currentTarget, as described in the doc cited in the PR: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#The_value_of_this_within_the_handler).

So I guess what I'm saying is we should probably merge that PR but clean up the discussion a bit.

[MajorBreakfast]

It doesn't matter whether the thing you add an event handler to is a custom element or not

@arthurevans I need to chime in on this. 😊 I'm very open to making changes to the PR to make it less confusing and even clearer. Everything I'm saying in the PR feels relevant to me. The _onClick method "belongs" to the custom element class, so the this inside of it is expected to refer to an instance of that class. In case of the <button> I recommend using the approach presented in the preceding documentation section (annotated event listeners in the template); with it, the this will be "correct" for the <button> as well. So, if you'd like to improve the phrasing, just write a comment in my PR and I'll amend my changes accordingly.

[arthurevans]

Thanks @MajorBreakfast! Will do. @katejeffreys may do some follow-up work because we have other issues around events.

[MajorBreakfast]

@arthurevans Perfect. It took me quite a while to figure out all the nuances of events. Good docs/guidelines on the subject are important :) - BTW you're doing great work with the Polymer docs! I just realized that you're on the top of the contributers list.