Avoid Boolean trap with useCapture parameter about ftdomdelegate HOT 12 CLOSED

Tough one, we wanted to match the browser's native API for add/removeEventListener for useCapture, which is why the boolean was chosen.

For comparison the native browser APIs use these arguments:-

target.addEventListener(type, listener[, useCapture]); 
target.removeEventListener(type, listener[, useCapture]); 

Our API uses these arguments:-

target.on(type[, selector], listener[, useCapture]); 
target.off(type[, selector], listener[, useCapture]); 

In any other case I would passionately agree with you and much prefer passing options objects around.

Do you think is a reasonable justification for bending the boolean trap rule?

from ftdomdelegate.

(Oops - made a slight typo in the APIs - updated now)

from ftdomdelegate.

In that situation, a compromise would be to still accept a Boolean for compatibility reason, but also allowing an configuration object. It incurs a small overhead, but then the latter can be the one recommended in the documentation and code snippets.

from ftdomdelegate.

Something like this?

dd.on({
  type: /* string */,
  selector: /* string !optional */,
  listener: /* function */,
  useCapture: /* boolean !optional */
});
dd.on(type[, selector], listener[, useCapture]);

I also wonder whether we should support addEventListener and removeEventListener.

from ftdomdelegate.

I'd be happy with any of these options:

1. keeping API as is
2. providing aliases for addEventListener and removeEventListener for on and off.
3. providing an alternate object based API
4. both 2 and 3.

Pinging past and present contributors: @wilsonpage @wheresrhys @georgecrawford @orangemug and @mattcg for their views and I'll go along with that.

from ftdomdelegate.

Even simpler:

delegate.on('click', clickHandler, { useCapture: true }); 

from ftdomdelegate.

I thought about that but it's kinda ugly in the selector case (which is also the most common):-

delegate.on('click', clickHandler, { selector: '.my-btn', useCapture: true }); 
// or
delegate.on('click'[, selector], clickHandler, { useCapture: true }); 

from ftdomdelegate.

Also it's worth saying the useCapture option is used only in very extreme cases. I've only ever needed it once - when building an extension of FastClick called Selective FastClick* (which I think is safe to say a fairly extreme example of usage of DOM events) - the rest of the time the default value FT DOM Delegate picks is 'right' for all the applications and tools I've been involved with building.

* https://github.com/matthew-andrews/selective-fastclick/blob/master/index.js#L39

from ftdomdelegate.

For what it's worth, I think you can satisfy all these comments with:

// options (object): 
//    useCapture (boolean) - defaults to 'sensible' value for the eventType
delegate.on(eventType[, selector], clickHandler[, options]); 

If you want to further embrace the existing EventTarget API, you can add:

target.addEventListener(type, listener[, useCapture]);
//...proxies to:
delegate.on(type, listener, {useCapture: useCapture}); 

from ftdomdelegate.

OK for now let's go with @georgecrawford and @ariya's suggestion of

delegate.on(type, listener, {useCapture: useCapture});

... and save addEventListener/removeEventListener for a rainy day.

from ftdomdelegate.

Isn't the norm to have the function at the end because its a bit more readable for inline usage. So the def would be

delegate.on(eventType, selector, options, clickHandler);

So basically this

delegate.on("click", ".menu", {useCapture: true}, function() {
  // ...
});

Rather than this

delegate.on("click", ".menu", function() {
  // ...
}, {useCapture: true});

from ftdomdelegate.

useCapture is such a little used, advanced-usage-only part of the API of a library who's API is very, very small I'm really struggling to justify the extra complexity here...

ftdomdelegate tries to be as close to the browser APIs as possible - merely providing event delegation - and its the underlying browser native APIs, the ones we're mimicking that have the boolean trap (and in the case of Gecko it's a bad one at that, true, false).

target.addEventListener(type, listener[, useCapture]);
target.addEventListener(type, listener[, useCapture, wantsUntrusted ]); // Gecko/Mozilla only

https://developer.mozilla.org/en/docs/Web/API/EventTarget.addEventListener

Thank you for your thoughts, suggestions and consideration but I am increasingly thinking that this boolean trap should be fixed in the browser itself - and then after that we can fix it here by matching that.

from ftdomdelegate.