Clarify event filter uses in hx-trigger

[brackendawson]

Description

• Clarify the example use of an event filter so that it is clear that you still use the hx-trigger attribute and that you use a CSS selector.

Corresponding issue: #2912

Testing

*Viewed the document as rendered markdown.

Checklist

• I have read the contribution guidelines
• I have targeted this PR against the correct branch (master for website changes, dev for
  source changes)
• This is either a bugfix, a documentation update, or a new feature that has been explicitly
  approved via an issue
• I ran the test suite locally (npm run test) and verified that it succeeded
  Two unit tests time out on my machine.

[Telroshan]

Hey, tbh I'm not so sure about the <CSS selector> here, I'm thinking that it's not a bad thing that an example uses any given tag, to precisely provide a "real" example.

However, this section could probably be improved to make things clearer.
For example, it could be useful to make it clear that hx-trigger="click[event.target.matches('input')]" will indeed work for any input element, but within the element declaring the hx-trigger itself only! As the click event listener will catch click events fired from the root element or any descendant, but not other elements on the page (maybe add a reference to event bubbling in here too?).

Maybe it could be useful to add this precision, as for ex a hx-trigger="click from:input" will bind to all inputs on the page, while click[event.target.matches('input')]" will only work on child inputs, in which case you would more want to do something like click[event.target.matches('input')]" from:body

Just some ideas out loud, let me know what you think!

[brackendawson]

My motivation for <CSS selector> was that on first read, for me, it wasn't clear that 'input' meant the HTML input tag, especially as it is also an event. I think that's because I'm not experienced in javascript (hence I use HTMX) and didn't recognise these well known event and element APIs.

If that example is a good approach to the stated problem then I'd agree to keeping it unchanged, other than including the attribute name in the snippet.

The precision is for sure worth mentioning, I did not know these nuances of the event scope.

Is it worth mentioning CSP here or a step too far? The console will warn the developer quickly when it doesn't work under a strict policy.

In my project I chose not to use this solution because it required unsafe-eval. I bound event listeners to my new elements that dispatch an 'input' event from a hidden with no name or value that is always present in my form. That approach is most definately not worth documenting.

[Telroshan]

wasn't clear that 'input' meant the HTML input tag, especially as it is also an event

I think we could use another example, such as click[event.target.matches('button')] or even click[event.target.matches('.some-class')] so there's no ambiguity ?
Could also use a link to Element.matches as non-experienced devs could think this is a htmx specifity when really everything in that filter expression are actually natively-supported calls by the browsers (and since Element.matches takes a CSS selector as parameter, it'd help reduce the confusion I guess)

Is it worth mentioning CSP here or a step too far? The console will warn the developer quickly when it doesn't work under a strict policy.

I think we can refer to the security section of the docs which contains the following part:

htmx.config.allowEval - can be set to false to disable all features of htmx that rely on eval:
event filters

No need to dive more than that I think as it's not the goal of the hx-trigger's doc itself, just mentioning that it relies on eval + link to the relevant configuration doc should be enough imo.

In my project I chose not to use this solution because it required unsafe-eval.

Sure, that's understandable! After all you did exacly what is suggested in the docs, i.e.:

Note that all features removed by disabling eval() can be reimplemented using your own custom javascript and the htmx event model.

[Telroshan]

Ok so very sorry about it, but I just realized I forgot to take the whole context into account while reviewing this.

As we're in the hx-trigger doc, though more specifically in the from details here, I feel like it might be too much information for this place.
Also, it feels weird to me that the docs goes from from to event filtering to then referencing combining with from once again while we're still in the from section's itself

What would you think about:

• Moving the eval reference to the "standard event filters" above that describes how filtering works ?
• Add a link to the event filtering section in the from details using a link anchor (i.e #standard-event-filters to match the id of that part and auto-scroll to it on click)
• Maybe simply illustrate the initial sentence here by 2 examples, something like

for example hx-trigger="click[event.target.matches('button')]" would intercept any dynamically swapped in button descendant as the listener is registered on the root element, and hx-trigger="click[event.target.matches('button')]" from:body would intercept any dynamically swapped in button across the whole page, as we'd be listening on the body

Rough idea, likely too verbose, we'd probably want a more concise sentence than that but you get the idea!

• Or, we could as well put more examples in the event filters section, precisely one with a event.target.matches example, then just refer to it in the from section maybe?

Let me know your thoughts!

[brackendawson]

No worries at all on the back and forth, lets do this well. I like the above, though I'm thinking for the example in "from" we only use the second, one which is most equivalent.

[Telroshan]

Thanks for your patience!