diff --git a/CHANGELOG.md b/CHANGELOG.md index de95bb0a..f188a7a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -78,6 +78,7 @@ All changes are documented here in no particular order. - breaking: `renderToString` function on qweb has been removed ([details](#32-rendertostring-on-qweb-has-been-removed)) - breaking: `debounce` utility function has been removed ([details](#34-debounce-utility-function-has-been-removed)) - breaking: `t-raw` directive has been removed (replaced by `t-out`) ([details](#38-t-raw-directive-has-been-removed-replaced-by-t-out)) +- new: add support for synthetic events ([doc](doc/reference/event_handling.md#synthetic-events)) ## Details/Rationale/Migration diff --git a/doc/reference/event_handling.md b/doc/reference/event_handling.md index 2b5d490b..6059602f 100644 --- a/doc/reference/event_handling.md +++ b/doc/reference/event_handling.md @@ -4,6 +4,7 @@ - [Event Handling](#event-handling) - [Modifiers](#modifiers) +- [Synthetic Events](#synthetic-events) ## Event Handling @@ -51,12 +52,13 @@ In order to remove the DOM event details from the event handlers (like calls to `event.preventDefault`) and let them focus on data logic, _modifiers_ can be specified as additional suffixes of the `t-on` directive. -| Modifier | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------ | -| `.stop` | calls `event.stopPropagation()` before calling the method | -| `.prevent` | calls `event.preventDefault()` before calling the method | -| `.self` | calls the method only if the `event.target` is the element itself | -| `.capture` | bind the event handler in [capture](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) mode. | +| Modifier | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `.stop` | calls `event.stopPropagation()` before calling the method | +| `.prevent` | calls `event.preventDefault()` before calling the method | +| `.self` | calls the method only if the `event.target` is the element itself | +| `.capture` | bind the event handler in [capture](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) mode. | +| `.synthetic` | define a synthetic event handler (see below) | ```xml @@ -75,3 +77,26 @@ modifiers. For example, ``` This will simply stop the propagation of the event. + +## Synthetic Events + +In some cases, attaching an event handler for each element of large lists has +a non trivial cost. Owl provides a way to efficiently improve the performance: +with synthetic event, it actually adds only one handler on the document body, +and will properly call the handler, just as expected. + +The only difference with regular events is that the event is caught at the document +body, so it cannot be stopped before it actually gets there. Since it may be +surprising in some cases, it is not enabled by default. + +To enable it, one can just use the `.synthetic` suffix: + +```xml +
+ + + +
+```