``` If an expression evaluates to a falsy value, it will not be set at all: ```xml

``` There is another way to format a string attribute: the `t-attf-` directive. With it, you get string interpolation: ```xml

``` For historical reason, there is an alternate form of string interpolation: ```xml

``` ### `t-call` directive (sub templates) QWeb templates can be used for top level rendering, but they can also be used from within another template (to avoid duplication or give names to parts of templates), using the `t-call` directive: ```xml

``` will be rendered as `

owl

`. This example shows that the sub template is rendered with the execution context of the parent. The sub template is actually inlined in the main template, but in a sub scope: variables defined in the sub template do not escape. Sometimes, one might want to pass information to the sub template. In that case, the content of the body of the `t-call` directive is available as a special magic variable `0`: ```xml This template was called with content:

content

``` will result in : ```xml

This template was called with content: content

``` ## JS/OWL Specific Extensions ### `t-on` directive In a component's template, it is useful to be able to register handlers on some elements to some specific events. This is what makes a template _alive_. There are two different use cases. 1. Register an event handler on a DOM node ```xml ``` This will be roughly translated in javascript like this: ```js button.addEventListener("click", widget.someMethod.bind(widget)); ``` The suffix (`click` in this example) is simply the name of the actual DOM event. 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 | ```xml ``` Note that modifiers can be combined (ex: `t-on-click.stop.prevent`), and that the order may matter. For instance `t-on-click.prevent.self` will prevent all clicks while `t-on-click.self.prevent` will only prevent clicks on the element itself. 2. Register an event handler on a component. This will not capture a DOM event, but rather a _business_ event: ```xml ``` ```js class MyWidget { someWhere() { const payload = ...; this.trigger('menuLoaded', payload); } } ``` Here, the parent widget will receive the payload in its `someMethod` handler, whenever the event is triggered. The `t-on` directive also allows to prebind some arguments. For example, ```xml ``` Here, `expr` is a valid Owl expression, so it could be `true` or some variable from the rendering context. ### Component: `t-widget`, `t-props` The `t-widget` and the `t-props` directives are the key to a declarative component system. They allow a template to define where and how a sub widget is created and/or updated. For example: ```xml

``` ```js class ParentWidget { widgets = { ChildWidget }; state = { val: 4 }; } ``` Whenever the template is rendered, it will automatically create the subwidget `ChildWidget` at the correct place. It needs to find the reference to the actual component class in the special `widgets` key, or the class registered in QWeb's global registry (see `register` function of QWeb). It first looks inside the local `widgets` key, then fallbacks on the global registry. In this example, the child widget will receive the object `{count: 4}` in its constructor. This will be assigned to the `props` variable, which can be accessed on the widget (and also, in the template). Whenever the state is updated, then the subwidget will also be updated automatically. The `t-widget` directive also accepts dynamic values with string interpolation (like the [`t-attf-`](#dynamic-attributes-t-att-and-t-attf-directives) directive): ```xml

``` ```js class ParentWidget { widgets = { ChildWidget1, ChildWidget2 }; state = { id: 1 }; } ``` Similarly to `t-attf-`, there is an alternate form of string interpolation: ```xml

``` ### `t-ref` directive The `t-ref` directive helps a component keep reference to some inside part of it. Like the `t-on` directive, it can work either on a DOM node, or on a component: ```xml

``` In this example, the widget will be able to access the `div` and the component inside the special `refs` variable: ```js this.refs.someDiv; this.refs.someWidget; ``` This is useful for various usecases: for example, integrating with an external library that needs to render itself inside an actual DOM node. Or for calling some method on a sub widget. Note: if used on a component, the reference will be set in the `refs` variable between `willPatch` and `patched`. The `t-ref` directive also accepts dynamic values with string interpolation (like the [`t-attf-`](#dynamic-attributes-t-att-and-t-attf-directives) and [`t-widget-`](#component-t-widget-t-props) directives). For example, if we have `id` set to 44 in the rendering context, ```xml

``` ```js this.refs.widget_44; ``` Similarly to `t-attf-` and `t-widget`, there is an alternate form of string interpolation: ```xml

``` ### `t-key` directive Even though Owl tries to be as declarative as possible, some DOM state is still locked inside the DOM: for example, the scrolling state, the current user selection, the focused element or the state of an input. This is why we use a virtual dom algorithm to keep the actual DOM node as much as possible. However, this is sometimes not enough, and we need to help Owl decide if an element is actually the same, or is different. The `t-key` directive is used to give an identity to an element. There are three main use cases: - _elements in a list_: ```xml ``` - _`t-if`/`t-else`_ - _animations_: give a different identity to a component. Ex: thread id with animations on add/remove message. ### `t-transition` directive To perform useful transition effects, whenever an element appears or disappears, it is necessary to add/remove some css style or class at some precise moment in the lifetime of a node. Since this is not easy to do by hand, Owl `t-transition` directive is there to help. Whenever a node has a `t-transition` directive, with a `name` value, the following will happen: At node insertion: - the css classes `name-enter` and `name-enter-active` will be added directly when the node is inserted into the DOM, - on the next animation frame: the css class `name-enter` will be removed and the class `name-enter-to` will be added (so they can be used to trigger css transition effects), - the css class `name-enter-active` will be removed whenever a css transition ends. At node destruction: - the css classes `name-leave` and `name-leave-active` will be added before the node is removed to the DOM, - the css class `name-leave` will be removed on the next animation frame (so it can be used to trigger css transition effects), - the css class `name-leave-active` will be removed whenever a css transition ends. Only then will the element be removed from the DOM. For example, a simple fade in/out effect can be done with this: ```xml

Hello

``` ```css .fade-enter-active, .fade-leave-active { transition: opacity 0.5s; } .fade-enter, .fade-leave-to { opacity: 0; } ``` The `t-transition` directive can be combined with `t-widget`. Notes: - more information on animations are available [here](animations.md). - the value for `t-transition` must be a single class name. Owl does not support more than one transition on a single node. ### `t-mounted` directive The `t-mounted` directive allows to register a callback to execute whenever the node is inserted into the DOM. ```xml

``` ```js class MyWidget extends owl.Component { ... focusMe() { this.refs.someInput.focus(); } } ``` ### Debugging (`t-debug` and `t-log`) The javascript QWeb implementation provides two useful debugging directives: `t-debug` adds a debugger statement during template rendering: ```xml ``` will stop execution if the browser dev tools are open. `t-log` takes an expression parameter, evaluates the expression during rendering and logs its result with console.log: ```xml ``` will print 42 to the console ### White spaces White spaces in a templates are handled in a special way: - consecutive whitespaces are always condensed to a single whitespace - if a whitespace-only text node contains a linebreak, it is ignored - the previous rules do not apply if we are in a `

` tag

### Root nodes

For many reasons, Owl QWeb templates should have a single root node. More
precisely, the result of a template rendering should have a single root node:

```xml


    foo
    bar




    foo
    bar

```

Extra root nodes will actually be ignored (even though they will be rendered
in memory).

Note: this does not apply to subtemplates (see the `t-call` directive). In that
case, they will be inlined in the main template, and can actually have many
root nodes.