mirror of
https://github.com/odoo/owl.git
synced 2025-10-06 19:59:41 +07:00
[DOC] miscellaneous improvements
including: - add a link to the tutorial in the main readme page - remove learning page on 'env', move content on reference page - add dynamic sub components section in component page - add reference page on props - split qweb page into engine/language pages - move t-key information into qweb language page
This commit is contained in:
Géry Debongnie
@@ -92,7 +92,8 @@ A complete documentation for Owl can be found here:
|
||||
|
||||
The most important sections are:
|
||||
|
||||
- [Quick Start](doc/learning/quick_start.md)
|
||||
- [Tutorial: TodoList application](doc/learning/tutorial_todoapp.md)
|
||||
- [QWeb templating language](doc/reference/qweb_templating_language.md)
|
||||
- [Component](doc/reference/component.md)
|
||||
- [Hooks](doc/reference/hooks.md)
|
||||
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
# 🦉 Environment 🦉
|
||||
|
||||
An environment is an object which contains a [`QWeb` instance](../reference/qweb.md).
|
||||
Whenever a root component is created, it is assigned an environment (see the
|
||||
reference section on [environment](../reference/environment.md). This environment
|
||||
is then automatically given to each sub components (and accessible in the `this.env` property).
|
||||
|
||||
The environment is mostly static. Each application is free to add anything to
|
||||
the environment, which is very useful, since this can be accessed by each sub
|
||||
component.
|
||||
|
||||
Some good use cases for the environment is:
|
||||
|
||||
- some configuration keys,
|
||||
- session information,
|
||||
- generic services (such as doing rpcs, or accessing local storage).
|
||||
|
||||
Doing it this way means that components are easily testable: we can simply
|
||||
create a test environment with mock services.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
async function myEnv() {
|
||||
const templates = await loadTemplates();
|
||||
const qweb = new QWeb({ templates });
|
||||
const session = getSession();
|
||||
|
||||
return {
|
||||
_t: myTranslateFunction,
|
||||
session: session,
|
||||
qweb: qweb,
|
||||
services: {
|
||||
localStorage: localStorage,
|
||||
rpc: rpc
|
||||
},
|
||||
debug: false,
|
||||
inMobileMode: true
|
||||
};
|
||||
}
|
||||
|
||||
async function start() {
|
||||
App.env = await myEnv();
|
||||
const app = new App();
|
||||
await app.mount(document.body);
|
||||
}
|
||||
```
|
||||
@@ -181,14 +181,14 @@ class App extends Component {
|
||||
}
|
||||
```
|
||||
|
||||
The template contains a [`t-foreach`](../reference/qweb.md#loops) loop to iterate
|
||||
The template contains a [`t-foreach`](../reference/qweb_templating_language.md#loops) loop to iterate
|
||||
through the tasks. It can find the `tasks` list from the component, since the
|
||||
component is the rendering context. Note that we use the `id` of each task as a
|
||||
`t-key`, which is very common. There are two css classes: `task-list` and `task`,
|
||||
that we will use in the next section.
|
||||
|
||||
Finally, notice the use of the `t-att-checked` attribute:
|
||||
prefixing an attribute by [`t-att`](../reference/qweb.md#dynamic-attributes) makes
|
||||
prefixing an attribute by [`t-att`](../reference/qweb_templating_language.md#dynamic-attributes) makes
|
||||
it dynamic. Owl will evaluate the expression and set it as the value of the
|
||||
attribute.
|
||||
|
||||
|
||||
+4
-3
@@ -9,9 +9,11 @@
|
||||
- [Environment](reference/environment.md)
|
||||
- [Event Bus](reference/event_bus.md)
|
||||
- [Hooks](reference/hooks.md)
|
||||
- [Misc](reference/misc.md)
|
||||
- [Miscellaneous Components](reference/misc.md)
|
||||
- [Observer](reference/observer.md)
|
||||
- [QWeb](reference/qweb.md)
|
||||
- [Props](reference/props.md)
|
||||
- [QWeb Templating Language](reference/qweb_templating_language.md)
|
||||
- [QWeb Engine](reference/qweb_engine.md)
|
||||
- [Router](reference/router.md)
|
||||
- [Store](reference/store.md)
|
||||
- [Tags](reference/tags.md)
|
||||
@@ -21,7 +23,6 @@
|
||||
|
||||
- [Quick Start: create an (almost) empty Owl application](learning/quick_start.md)
|
||||
- [Tutorial: create a TodoList application](learning/tutorial_todoapp.md)
|
||||
- [Environment: what it is and what it should contain](learning/environment.md)
|
||||
|
||||
## Miscellaneous
|
||||
|
||||
|
||||
+49
-127
@@ -14,11 +14,11 @@
|
||||
- [Composition](#composition)
|
||||
- [Event Handling](#event-handling)
|
||||
- [Form Input Bindings](#form-input-bindings)
|
||||
- [`t-key` Directive](#t-key-directive)
|
||||
- [Semantics](#semantics)
|
||||
- [Props Validation](#props-validation)
|
||||
- [References](#references)
|
||||
- [Slots](#slots)
|
||||
- [Dynamic sub components](#dynamic-sub-components)
|
||||
- [Asynchronous Rendering](#asynchronous-rendering)
|
||||
- [Error Handling](#error-handling)
|
||||
- [Functional Components](#functional-components)
|
||||
@@ -42,7 +42,7 @@ OWL components are the building blocks for user interface. They are designed to
|
||||
and follow the QWeb specification. This is a requirement for Odoo.
|
||||
|
||||
OWL components are defined as a subclass of Component. The rendering is
|
||||
exclusively done by a [QWeb](qweb.md) template (which needs to be preloaded in QWeb).
|
||||
exclusively done by a [QWeb](qweb_templating_language.md) template (which needs to be preloaded in QWeb).
|
||||
Rendering a component generates a virtual dom representation
|
||||
of the component, which is then patched to the DOM, in order to apply the changes in an efficient way.
|
||||
|
||||
@@ -81,7 +81,7 @@ a state object is defined, by using the `useState` hook. It is not mandatory to
|
||||
|
||||
An Owl component is a small class which represents a component or some UI element.
|
||||
It exists in the context of an [environment](environment.md) (`env`), which is propagated from a
|
||||
parent to its children. The environment needs to have a [QWeb](qweb.md) instance, which
|
||||
parent to its children. The environment needs to have a [QWeb](qweb_templating_language.md) instance, which
|
||||
will be used to render the component template.
|
||||
|
||||
Be aware that the name of the component may be significant: if a component does
|
||||
@@ -166,7 +166,7 @@ to be called in the constructor.
|
||||
- **`el`** (HTMLElement | null): reference to the DOM root node of the element. It is `null` when the
|
||||
component is not mounted.
|
||||
|
||||
- **`env`** (Object): the component environment, which contains a QWeb instance.
|
||||
- **`env`** (Object): the component [environment](environment.md), which contains a QWeb instance.
|
||||
|
||||
- **`props`** (Object): this is an object containing all the properties given by
|
||||
the parent to a child component. For example, in the following situation,
|
||||
@@ -502,66 +502,8 @@ the static `components` key, then fallbacks on the global registry.
|
||||
_Props_: In this example, the child component will receive the object `{count: 4}` in its
|
||||
constructor. This will be assigned to the `props` variable, which can be accessed
|
||||
on the component (and also, in the template). Whenever the state is updated, then
|
||||
the sub component will also be updated automatically.
|
||||
|
||||
Note that there are restrictions on valid prop names: `class`, `style` and any
|
||||
string which starts with `t-` are not allowed.
|
||||
|
||||
It is not common, but sometimes we need a dynamic component name and/or dynamic props. In this case,
|
||||
the `t-component` directive can also be used to accept dynamic values with string interpolation (like the [`t-attf-`](qweb.md#dynamic-attributes) directive):
|
||||
|
||||
```xml
|
||||
<div t-name="ParentComponent">
|
||||
<t t-component="ChildComponent{{id}}" />
|
||||
</div>
|
||||
```
|
||||
|
||||
```js
|
||||
class ParentComponent {
|
||||
static components = { ChildComponent1, ChildComponent2 };
|
||||
state = { id: 1 };
|
||||
}
|
||||
```
|
||||
|
||||
And the `t-props` directive can be used to specify totally dynamic props:
|
||||
|
||||
```xml
|
||||
<div t-name="ParentComponent">
|
||||
<Child t-props="some.obj"/>
|
||||
</div>
|
||||
```
|
||||
|
||||
```js
|
||||
class ParentComponent {
|
||||
static components = { Child };
|
||||
some = { obj: { a: 1, b: 2 } };
|
||||
}
|
||||
```
|
||||
|
||||
There is an even more dynamic way to use `t-component`: its value can be an
|
||||
expression evaluating to an actual component class. In that case, this is the
|
||||
class that will be used to create the component:
|
||||
|
||||
```js
|
||||
class A extends Component<any, any, any> {
|
||||
static template = xml`<span>child a</span>`;
|
||||
}
|
||||
class B extends Component<any, any, any> {
|
||||
static template = xml`<span>child b</span>`;
|
||||
}
|
||||
class App extends Component<any, any, any> {
|
||||
static template = xml`<t t-component="myComponent" t-key="state.child"/>`;
|
||||
|
||||
state = { child: "a" };
|
||||
|
||||
get myComponent() {
|
||||
return this.state.child === "a" ? A : B;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the component `App` selects dynamically the concrete sub
|
||||
component class.
|
||||
the sub component will also be updated automatically. See the [props section](props.md)
|
||||
for more information.
|
||||
|
||||
**CSS and style:** Owl allows the parent to declare
|
||||
additional css classes or style for the sub component: css declared in `class`, `style`, `t-att-class` or `t-att-style` will be added to the
|
||||
@@ -787,69 +729,6 @@ update a number whenever the change is done.
|
||||
|
||||
Note: the online playground has an example to show how it works.
|
||||
|
||||
### `t-key` Directive
|
||||
|
||||
Even though Owl tries to be as declarative as possible, the DOM does not fully
|
||||
expose its state declaratively in the DOM tree. For example, the scrolling state,
|
||||
the current user selection, the focused element or the state of an input are not
|
||||
set as attribute in the DOM tree. This is why we use a virtual dom
|
||||
algorithm to keep the actual DOM node as much as possible.
|
||||
|
||||
However, in some situations, this is not enough, and we need to help Owl decide
|
||||
if an element is actually the same, or is a different element with the same
|
||||
properties.
|
||||
|
||||
Consider the following situation: we have a list of two items `[{text: "a"}, {text: "b"}]`
|
||||
and we render them in this template:
|
||||
|
||||
```xml
|
||||
<p t-foreach="items" t-as="item"><t t-esc="item.text"/></p>
|
||||
```
|
||||
|
||||
The result will be two `<p>` tags with text `a` and `b`. Now, if we swap them,
|
||||
and rerender the template, Owl needs to know what the intent is:
|
||||
|
||||
- should Owl actually swap the DOM nodes,
|
||||
- or should it keep the DOM nodes, but with an updated text content?
|
||||
|
||||
This might look trivial, but it actually matters. These two possibilities lead
|
||||
to different results in some cases. For example, if the user selected the text
|
||||
of the first `p`, swapping them will keep the selection while updating the
|
||||
text content will not.
|
||||
|
||||
There are many other cases where this is important: `input` tags with their
|
||||
value, css classes and animations, scroll position...
|
||||
|
||||
So, the `t-key` directive is used to give an identity to an element. It allows
|
||||
Owl to understand if different elements of a list are actually different or not.
|
||||
|
||||
The above example could be modified by adding an ID: `[{id: 1, text: "a"}, {id: 2, text: "b"}]`.
|
||||
Then, the template could look like this:
|
||||
|
||||
```xml
|
||||
<p t-foreach="items" t-as="item" t-key="item.id"><t t-esc="item.text"/></p>
|
||||
```
|
||||
|
||||
The `t-key` directive is useful for lists (`t-foreach`). A key should be
|
||||
a unique number or string (objects will not work: they will be cast to the
|
||||
`"[object Object]"` string, which is obviously not unique).
|
||||
|
||||
Also, the key can be set on a `t` tag or on its children. The following variations
|
||||
are all equivalent:
|
||||
|
||||
```xml
|
||||
<p t-foreach="items" t-as="item" t-key="item.id">
|
||||
<t t-esc="item.text"/>
|
||||
</p>
|
||||
|
||||
<t t-foreach="items" t-as="item" t-key="item.id">
|
||||
<p t-esc="item.text"/>
|
||||
</t>
|
||||
|
||||
<t t-foreach="items" t-as="item">
|
||||
<p t-key="item.id" t-esc="item.text"/>
|
||||
</t>
|
||||
```
|
||||
|
||||
### Semantics
|
||||
|
||||
@@ -1145,6 +1024,49 @@ be considered the `default` slot. For example:
|
||||
</div>
|
||||
```
|
||||
|
||||
### Dynamic sub components
|
||||
|
||||
It is not common, but sometimes we need a dynamic component name. In this case,
|
||||
the `t-component` directive can also be used to accept dynamic values with string interpolation (like the [`t-attf-`](qweb_templating_language.md#dynamic-attributes) directive):
|
||||
|
||||
```xml
|
||||
<div t-name="ParentComponent">
|
||||
<t t-component="ChildComponent{{id}}" />
|
||||
</div>
|
||||
```
|
||||
|
||||
```js
|
||||
class ParentComponent {
|
||||
static components = { ChildComponent1, ChildComponent2 };
|
||||
state = { id: 1 };
|
||||
}
|
||||
```
|
||||
|
||||
There is an even more dynamic way to use `t-component`: its value can be an
|
||||
expression evaluating to an actual component class. In that case, this is the
|
||||
class that will be used to create the component:
|
||||
|
||||
```js
|
||||
class A extends Component<any, any, any> {
|
||||
static template = xml`<span>child a</span>`;
|
||||
}
|
||||
class B extends Component<any, any, any> {
|
||||
static template = xml`<span>child b</span>`;
|
||||
}
|
||||
class App extends Component<any, any, any> {
|
||||
static template = xml`<t t-component="myComponent" t-key="state.child"/>`;
|
||||
|
||||
state = { child: "a" };
|
||||
|
||||
get myComponent() {
|
||||
return this.state.child === "a" ? A : B;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the component `App` selects dynamically the concrete sub
|
||||
component class.
|
||||
|
||||
### Asynchronous Rendering
|
||||
|
||||
Working with asynchronous code always adds a lot of complexity to a system. Whenever
|
||||
|
||||
@@ -1,6 +1,14 @@
|
||||
# 🦉 Environment 🦉
|
||||
|
||||
An environment is an object which contains a [`QWeb` instance](qweb.md). Whenever
|
||||
## Content
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Setting an Environment](#setting-an-environment)
|
||||
- [Content of an Environment](#content-of-an-environment)
|
||||
|
||||
## Overview
|
||||
|
||||
An environment is an object which contains a [`QWeb` instance](qweb_engine.md). Whenever
|
||||
a root component is created, it is assigned an environment (see
|
||||
[below](#setting-an-environment) for more info on this). This environment is
|
||||
then automatically given to each sub component (and accessible in the `this.env`
|
||||
@@ -12,15 +20,20 @@ property).
|
||||
A B
|
||||
```
|
||||
|
||||
This way, all components share the same `QWeb` instance.
|
||||
This way, all components share the same `QWeb` instance. Owl internally requires
|
||||
that the environment has a `qweb` key which maps to a
|
||||
[`QWeb`](qweb_engine.md) instance. This is the QWeb instance that will be used to
|
||||
render each templates in this specific component tree. Note that if no `QWeb`
|
||||
instance is provided, Owl will simply generate it on the fly.
|
||||
|
||||
Note: some additional information about what should go into an environment
|
||||
can be found in the [learning section](../learning/environment.md).
|
||||
The environment is mostly static. Each application is free to add anything to
|
||||
the environment, which is very useful, since this can be accessed by each sub
|
||||
component.
|
||||
|
||||
## Setting an environment
|
||||
|
||||
An Owl application needs an [environment](environment.md) to be executed. The
|
||||
environment has an important key: the [QWeb](qweb.md) instance, which will render
|
||||
environment has an important key: the [QWeb](qweb_engine.md) instance, which will render
|
||||
all templates.
|
||||
|
||||
Whenever a root component `App` is mounted, Owl will setup a valid environment by
|
||||
@@ -51,3 +64,42 @@ by simply doing this:
|
||||
```js
|
||||
Component.env = myEnv; // will be the default env for all components
|
||||
```
|
||||
|
||||
## Content of an Environment
|
||||
|
||||
Some good use cases for additional keys in the environment are:
|
||||
|
||||
- some configuration keys,
|
||||
- session information,
|
||||
- generic services (such as doing rpcs, or accessing local storage).
|
||||
|
||||
Doing it this way means that components are easily testable: we can simply
|
||||
create a test environment with mock services.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
async function myEnv() {
|
||||
const templates = await loadTemplates();
|
||||
const qweb = new QWeb({ templates });
|
||||
const session = getSession();
|
||||
|
||||
return {
|
||||
_t: myTranslateFunction,
|
||||
session: session,
|
||||
qweb: qweb,
|
||||
services: {
|
||||
localStorage: localStorage,
|
||||
rpc: rpc
|
||||
},
|
||||
debug: false,
|
||||
inMobileMode: true
|
||||
};
|
||||
}
|
||||
|
||||
async function start() {
|
||||
App.env = await myEnv();
|
||||
const app = new App();
|
||||
await app.mount(document.body);
|
||||
}
|
||||
```
|
||||
|
||||
@@ -301,11 +301,11 @@ key, and components references are accessed with `comp`.
|
||||
Notes:
|
||||
|
||||
- if used on a component, the reference will be set in the `refs`
|
||||
variable between `willPatch` and `patched`,
|
||||
variable between `willPatch` and `patched`,
|
||||
- on a component, accessing `ref.el` will get the root node of the component.
|
||||
|
||||
The `t-ref` directive also accepts dynamic values with string interpolation
|
||||
(like the [`t-attf-`](qweb.md#dynamic-attributes) and
|
||||
(like the [`t-attf-`](qweb_templating_language.md#dynamic-attributes) and
|
||||
`t-component` directives). For example,
|
||||
|
||||
```xml
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
# 🦉 Props 🦉
|
||||
|
||||
## Content
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Definition](#definition)
|
||||
- [Good Practices](#good-practices)
|
||||
- [Dynamic Props](#dynamic-props)
|
||||
|
||||
## Overview
|
||||
|
||||
In Owl, `props` (short for _properties_) is an object which contains every piece
|
||||
of data given to a component by its parent.
|
||||
|
||||
```js
|
||||
class Child extends Component {
|
||||
static template = xml`<div><t t-esc="props.a"/><t t-esc="props.b"/></div>`;
|
||||
}
|
||||
|
||||
class Parent extends Component {
|
||||
static template = xml`<div><ComponentA a="state.a" b="'string'"/></div>`;
|
||||
static components = { Child };
|
||||
state = useState({ a: "fromparent" });
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the `Child` component receives two props from its parent: `a`
|
||||
and `b`. They are collected into a `props` object by Owl, with each value being
|
||||
evaluated in the context of the parent. So, `props.a` is equal to `'fromparent'` and
|
||||
`props.b` is equal to `'string'`.
|
||||
|
||||
Note that `props` is an object that only makes sense from the perspective of the
|
||||
child component.
|
||||
|
||||
## Definition
|
||||
|
||||
The `props` object is made of every attributes defined on the template, with the
|
||||
following exceptions:
|
||||
|
||||
- every attribute starting with `t-` are not props (they are QWeb directives),
|
||||
- `style` and `class` attributes are excluded as well (they are applied by Owl on
|
||||
the root element of the component).
|
||||
|
||||
In the following example:
|
||||
|
||||
```xml
|
||||
<div>
|
||||
<ComponentA a="state.a" b="'string'"/>
|
||||
<ComponentB t-if="state.flag" model="model"/>
|
||||
<ComponentC style="color:red;" class="left-pane" />
|
||||
</div>
|
||||
```
|
||||
|
||||
the `props` object contains the following keys:
|
||||
|
||||
- for `ComponentA`: `a` and `b`,
|
||||
- for `ComponentB`: `model`,
|
||||
- for `ComponentC`: empty object
|
||||
|
||||
## Good Practices
|
||||
|
||||
A `props` object is a collection of values that come from the parent. As such,
|
||||
they are owned by the parent, and should never be modified by the child:
|
||||
|
||||
```js
|
||||
class MyComponent extends Component {
|
||||
constructor(parent, props) {
|
||||
super(parent, props);
|
||||
props.a.b = 43; // Never do that!!!
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Props should be considered readonly, from the perspective of the child component.
|
||||
If there is a need to modify them, then the request to update them should be
|
||||
sent to the parent (for example, with an event).
|
||||
|
||||
Any value can go in a props. Strings, objects, classes, or even callbacks could
|
||||
be given to a child component (but then, in the case of callbacks, communicating
|
||||
with events seems more appropriate).
|
||||
|
||||
## Dynamic Props
|
||||
|
||||
The `t-props` directive can be used to specify totally dynamic props:
|
||||
|
||||
```xml
|
||||
<div t-name="ParentComponent">
|
||||
<Child t-props="some.obj"/>
|
||||
</div>
|
||||
```
|
||||
|
||||
```js
|
||||
class ParentComponent {
|
||||
static components = { Child };
|
||||
some = { obj: { a: 1, b: 2 } };
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,151 @@
|
||||
# 🦉 QWeb Engine 🦉
|
||||
|
||||
## Content
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Reference](#reference)
|
||||
|
||||
## Overview
|
||||
|
||||
[QWeb](https://www.odoo.com/documentation/13.0/reference/qweb.html) is the primary
|
||||
templating engine used by Odoo. The QWeb class in the OWL project is an
|
||||
implementation of that specification with a few interesting points:
|
||||
|
||||
- it compiles templates into functions that output a virtual DOM instead of a
|
||||
string. This is necessary for the component system.
|
||||
- it has a few extra directives: `t-component`, `t-on`, ...
|
||||
|
||||
We present in this section the engine, not the templating language.
|
||||
|
||||
## Reference
|
||||
|
||||
This section is about the javascript code that implements the `QWeb` specification.
|
||||
Owl exports a `QWeb` class in `owl.QWeb`. To use it, it just needs to be
|
||||
instantiated:
|
||||
|
||||
```js
|
||||
const qweb = new owl.QWeb();
|
||||
```
|
||||
|
||||
Its API is quite simple:
|
||||
|
||||
- **`constructor(config)`**: constructor. Takes an optional configuration object
|
||||
with an optional `templates` string to add initial
|
||||
templates (see `addTemplates` for more information on format of the string)
|
||||
and an optional `translateFn` translate function (see the section on
|
||||
[translations](#translations)).
|
||||
|
||||
```js
|
||||
const qweb = new owl.QWeb({ templates: TEMPLATES, translateFn: _t });
|
||||
```
|
||||
|
||||
- **`addTemplate(name, xmlStr, allowDuplicate)`**: add a specific template.
|
||||
|
||||
```js
|
||||
qweb.addTemplate("mytemplate", "<div>hello</div>");
|
||||
```
|
||||
|
||||
If the optional `allowDuplicate` is set to `true`, then `QWeb` will simply
|
||||
ignore templates added for a second time. Otherwise, `QWeb` will crash.
|
||||
|
||||
- **`addTemplates(xmlStr)`**: add a list of templates (identified by `t-name`
|
||||
attribute).
|
||||
|
||||
```js
|
||||
const TEMPLATES = `
|
||||
<templates>
|
||||
<div t-name="App" class="main">main</div>
|
||||
<div t-name="OtherComponent">other component</div>
|
||||
</templates>`;
|
||||
qweb.addTemplates(TEMPLATES);
|
||||
```
|
||||
|
||||
- **`render(name, context, extra)`**: renders a template. This returns a `vnode`,
|
||||
which is a virtual representation of the DOM (see [vdom doc](../architecture/vdom.md)).
|
||||
|
||||
```js
|
||||
const vnode = qweb.render("App", component);
|
||||
```
|
||||
|
||||
- **`renderToString(name, context)`**: renders a template, but returns an html
|
||||
string.
|
||||
|
||||
```js
|
||||
const str = qweb.renderToString("someTemplate", somecontext);
|
||||
```
|
||||
|
||||
- **`registerTemplate(name, template)`**: static function to register a global
|
||||
QWeb template. This is useful for commonly used components accross the
|
||||
application, and for making a template available to an application without
|
||||
having a reference to the actual QWeb instance.
|
||||
|
||||
```js
|
||||
QWeb.registerTemplate("mytemplate", `<div>some template</div>`);
|
||||
```
|
||||
|
||||
- **`registerComponent(name, Component)`**: static function to register an OWL Component
|
||||
to QWeb's global registry. Globally registered Components can be used in
|
||||
templates (see the `t-component` directive). This is useful for commonly used
|
||||
components accross the application.
|
||||
|
||||
```js
|
||||
class Dialog extends owl.Component { ... }
|
||||
QWeb.registerComponent("Dialog", Dialog);
|
||||
|
||||
...
|
||||
|
||||
class ParentComponent extends owl.Component { ... }
|
||||
qweb.addTemplate("ParentComponent", "<div><Dialog/></div>");
|
||||
```
|
||||
|
||||
In some way, a `QWeb` instance is the core of an Owl application. It is the only
|
||||
mandatory element of an [environment](environment.md). As such, it
|
||||
has an extra responsibility: it can act as an event bus for internal communication
|
||||
between Owl classes. This is the reason why `QWeb` actually extends [EventBus](event_bus.md).
|
||||
|
||||
### Translations
|
||||
|
||||
If properly setup, Owl QWeb engine can translate all rendered templates. To do
|
||||
so, it needs a translate function, which takes a string and returns a string.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
const translations = {
|
||||
hello: "bonjour",
|
||||
yes: "oui",
|
||||
no: "non"
|
||||
};
|
||||
const translateFn = str => translations[str] || str;
|
||||
|
||||
const qweb = new QWeb({ translateFn });
|
||||
```
|
||||
|
||||
Once setup, all rendered templates will be translated using `translateFn`:
|
||||
|
||||
- each text node will be replaced with its translation,
|
||||
- each of the following attribute values will be translated as well: `title`,
|
||||
`placeholder`, `label` and `alt`,
|
||||
- translating text nodes can be disabled with the special attribute `t-translation`,
|
||||
if its value is `off`.
|
||||
|
||||
So, with the above `translateFn`, the following templates:
|
||||
|
||||
```xml
|
||||
<div>hello</div>
|
||||
<div t-translation="off">hello</div>
|
||||
<div>Are you sure?</div>
|
||||
<input placeholder="hello" other="yes"/>
|
||||
```
|
||||
|
||||
will be rendered as:
|
||||
|
||||
```xml
|
||||
<div>bonjour</div>
|
||||
<div>hello</div>
|
||||
<div>Are you sure?</div>
|
||||
<input placeholder="bonjour" other="yes"/>
|
||||
```
|
||||
|
||||
Note that the translation is done during the compilation of the template, not
|
||||
when it is rendered.
|
||||
@@ -1,10 +1,9 @@
|
||||
# 🦉 QWeb 🦉
|
||||
# 🦉 QWeb Templating Language🦉
|
||||
|
||||
## Content
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Directives](#directives)
|
||||
- [QWeb Engine](#qweb-engine)
|
||||
- [Reference](#reference)
|
||||
- [White Spaces](#white-spaces)
|
||||
- [Root Nodes](#root-nodes)
|
||||
@@ -21,14 +20,11 @@
|
||||
|
||||
## Overview
|
||||
|
||||
[QWeb](https://www.odoo.com/documentation/13.0/reference/qweb.html) is the primary templating engine used by Odoo. It is based on the XML format, and used
|
||||
[QWeb](https://www.odoo.com/documentation/13.0/reference/qweb.html) is the primary
|
||||
templating engine used by Odoo. It is based on the XML format, and used
|
||||
mostly to generate HTML. In OWL, QWeb templates are compiled into functions that
|
||||
generate a virtual dom representation of the HTML.
|
||||
|
||||
Template directives are specified as XML attributes prefixed with `t-`, for instance `t-if` for conditionals, with elements and other attributes being rendered directly.
|
||||
|
||||
To avoid element rendering, a placeholder element `<t>` is also available, which executes its directive but doesn’t generate any output in and of itself.
|
||||
|
||||
```xml
|
||||
<div>
|
||||
<span t-if="somecondition">Some string</span>
|
||||
@@ -40,19 +36,22 @@ To avoid element rendering, a placeholder element `<t>` is also available, which
|
||||
</div>
|
||||
```
|
||||
|
||||
The QWeb class in the OWL project is an implementation of that specification
|
||||
with a few interesting points:
|
||||
Template directives are specified as XML attributes prefixed with `t-`, for
|
||||
instance `t-if` for conditionals, with elements and other attributes being
|
||||
rendered directly.
|
||||
|
||||
- it compiles templates into functions that output a virtual DOM instead of a
|
||||
string. This is necessary for the component system.
|
||||
- it has a few extra directives: `t-component`, `t-on`, ...
|
||||
To avoid element rendering, a placeholder element `<t>` is also available, which
|
||||
executes its directive but doesn’t generate any output in and of itself.
|
||||
|
||||
We present in this section the templating language, including its Owl specific
|
||||
extensions.
|
||||
|
||||
## Directives
|
||||
|
||||
We present here a list of all standard QWeb directives:
|
||||
For reference, here is a list of all standard QWeb directives:
|
||||
|
||||
| Name | Description |
|
||||
| ------------------------------ | ------------------------------------------------------------ |
|
||||
| ------------------------------ | -------------------------------------------------------------- |
|
||||
| `t-esc` | [Outputting safely a value](#outputting-data) |
|
||||
| `t-raw` | [Outputting value, without escaping](#outputting-data) |
|
||||
| `t-set`, `t-value` | [Setting variables](#setting-variables) |
|
||||
@@ -62,7 +61,7 @@ We present here a list of all standard QWeb directives:
|
||||
| `t-call` | [Rendering sub templates](#rendering-sub-templates) |
|
||||
| `t-debug`, `t-log` | [Debugging](#debugging) |
|
||||
| `t-translation` | [Disabling the translation of a node](#translations) |
|
||||
| `t-name` | [Defining a template (not really a directive)](#qweb-engine) |
|
||||
| `t-name` | [Defining a template (not really a directive)](qweb_engine.md) |
|
||||
|
||||
The component system in Owl requires additional directives, to express various
|
||||
needs. Here is a list of all Owl specific directives:
|
||||
@@ -71,104 +70,14 @@ needs. Here is a list of all Owl specific directives:
|
||||
| ------------------------ | ----------------------------------------------------------------------------------- |
|
||||
| `t-component`, `t-props` | [Defining a sub component](component.md#composition) |
|
||||
| `t-ref` | [Setting a reference to a dom node or a sub component](component.md#references) |
|
||||
| `t-key` | [Defining a key (to help virtual dom reconciliation)](component.md#t-key-directive) |
|
||||
| `t-key` | [Defining a key (to help virtual dom reconciliation)](#loops) |
|
||||
| `t-on-*` | [Event handling](component.md#event-handling) |
|
||||
| `t-transition` | [Defining an animation](animations.md#css-transitions) |
|
||||
| `t-slot` | [Rendering a slot](component.md#slots) |
|
||||
| `t-model` | [Form input bindings](component.md#form-input-bindings) |
|
||||
|
||||
## QWeb Engine
|
||||
|
||||
This section is about the javascript code that implements the `QWeb` specification.
|
||||
Owl exports a `QWeb` class in `owl.QWeb`. To use it, it just needs to be
|
||||
instantiated:
|
||||
|
||||
```js
|
||||
const qweb = new owl.QWeb();
|
||||
```
|
||||
|
||||
Its API is quite simple:
|
||||
|
||||
- **`constructor(config)`**: constructor. Takes an optional configuration object
|
||||
with an optional `templates` string to add initial
|
||||
templates (see `addTemplates` for more information on format of the string)
|
||||
and an optional `translateFn` translate function (see the section on
|
||||
[translations](#translations)).
|
||||
|
||||
```js
|
||||
const qweb = new owl.QWeb({ templates: TEMPLATES, translateFn: _t });
|
||||
```
|
||||
|
||||
- **`addTemplate(name, xmlStr, allowDuplicate)`**: add a specific template.
|
||||
|
||||
```js
|
||||
qweb.addTemplate("mytemplate", "<div>hello</div>");
|
||||
```
|
||||
|
||||
If the optional `allowDuplicate` is set to `true`, then `QWeb` will simply
|
||||
ignore templates added for a second time. Otherwise, `QWeb` will crash.
|
||||
|
||||
- **`addTemplates(xmlStr)`**: add a list of templates (identified by `t-name`
|
||||
attribute).
|
||||
|
||||
```js
|
||||
const TEMPLATES = `
|
||||
<templates>
|
||||
<div t-name="App" class="main">main</div>
|
||||
<div t-name="OtherComponent">other component</div>
|
||||
</templates>`;
|
||||
qweb.addTemplates(TEMPLATES);
|
||||
```
|
||||
|
||||
- **`render(name, context, extra)`**: renders a template. This returns a `vnode`,
|
||||
which is a virtual representation of the DOM (see [vdom doc](../architecture/vdom.md)).
|
||||
|
||||
```js
|
||||
const vnode = qweb.render("App", component);
|
||||
```
|
||||
|
||||
- **`renderToString(name, context)`**: renders a template, but returns an html
|
||||
string.
|
||||
|
||||
```js
|
||||
const str = qweb.renderToString("someTemplate", somecontext);
|
||||
```
|
||||
|
||||
- **`registerTemplate(name, template)`**: static function to register a global
|
||||
QWeb template. This is useful for commonly used components accross the
|
||||
application, and for making a template available to an application without
|
||||
having a reference to the actual QWeb instance.
|
||||
|
||||
```js
|
||||
QWeb.registerTemplate("mytemplate", `<div>some template</div>`);
|
||||
```
|
||||
|
||||
- **`registerComponent(name, Component)`**: static function to register an OWL Component
|
||||
to QWeb's global registry. Globally registered Components can be used in
|
||||
templates (see the `t-component` directive). This is useful for commonly used
|
||||
components accross the application.
|
||||
|
||||
```js
|
||||
class Dialog extends owl.Component { ... }
|
||||
QWeb.registerComponent("Dialog", Dialog);
|
||||
|
||||
...
|
||||
|
||||
class ParentComponent extends owl.Component { ... }
|
||||
qweb.addTemplate("ParentComponent", "<div><Dialog/></div>");
|
||||
```
|
||||
|
||||
In some way, a `QWeb` instance is the core of an Owl application. It is the only
|
||||
mandatory element of an [environment](environment.md). As such, it
|
||||
has an extra responsibility: it can act as an event bus for internal communication
|
||||
between Owl classes. This is the reason why `QWeb` actually extends [EventBus](event_bus.md).
|
||||
|
||||
## Reference
|
||||
|
||||
We define in this section the specification of how `QWeb` templates should be
|
||||
rendered. Note that we only document here the standard QWeb specification. Owl
|
||||
specific extensions are documented in various other parts of the documentation.
|
||||
|
||||
### White Spaces
|
||||
|
||||
White spaces in a template are handled in a special way:
|
||||
@@ -479,16 +388,67 @@ into the global context.
|
||||
<!-- new_variable undefined -->
|
||||
```
|
||||
|
||||
Owl QWeb is used as the template engine for components. Components are frequently
|
||||
updated, and reuse as much of the previous DOM as possible. Loops offer a specific
|
||||
problem for this usecase: how does the template engine know if two rows have
|
||||
been swapped, or if the content of these rows was changed? To help Owl with that,
|
||||
there is an additional directive: [`t-key`](component.md#t-key-directive).
|
||||
|
||||
Even though Owl tries to be as declarative as possible, the DOM does not fully
|
||||
expose its state declaratively in the DOM tree. For example, the scrolling state,
|
||||
the current user selection, the focused element or the state of an input are not
|
||||
set as attribute in the DOM tree. This is why we use a virtual dom
|
||||
algorithm to keep the actual DOM node as much as possible.
|
||||
|
||||
However, in some situations, this is not enough, and we need to help Owl decide
|
||||
if an element is actually the same, or is a different element with the same
|
||||
properties.
|
||||
|
||||
Consider the following situation: we have a list of two items `[{text: "a"}, {text: "b"}]`
|
||||
and we render them in this template:
|
||||
|
||||
```xml
|
||||
<p t-foreach="state.things" t-as="thing" t-key="thing.id">
|
||||
<t t-esc="thing.content"/>
|
||||
<p t-foreach="items" t-as="item"><t t-esc="item.text"/></p>
|
||||
```
|
||||
|
||||
The result will be two `<p>` tags with text `a` and `b`. Now, if we swap them,
|
||||
and rerender the template, Owl needs to know what the intent is:
|
||||
|
||||
- should Owl actually swap the DOM nodes,
|
||||
- or should it keep the DOM nodes, but with an updated text content?
|
||||
|
||||
This might look trivial, but it actually matters. These two possibilities lead
|
||||
to different results in some cases. For example, if the user selected the text
|
||||
of the first `p`, swapping them will keep the selection while updating the
|
||||
text content will not.
|
||||
|
||||
There are many other cases where this is important: `input` tags with their
|
||||
value, css classes and animations, scroll position...
|
||||
|
||||
So, the `t-key` directive is used to give an identity to an element. It allows
|
||||
Owl to understand if different elements of a list are actually different or not.
|
||||
|
||||
The above example could be modified by adding an ID: `[{id: 1, text: "a"}, {id: 2, text: "b"}]`.
|
||||
Then, the template could look like this:
|
||||
|
||||
```xml
|
||||
<p t-foreach="items" t-as="item" t-key="item.id"><t t-esc="item.text"/></p>
|
||||
```
|
||||
|
||||
The `t-key` directive is useful for lists (`t-foreach`). A key should be
|
||||
a unique number or string (objects will not work: they will be cast to the
|
||||
`"[object Object]"` string, which is obviously not unique).
|
||||
|
||||
Also, the key can be set on a `t` tag or on its children. The following variations
|
||||
are all equivalent:
|
||||
|
||||
```xml
|
||||
<p t-foreach="items" t-as="item" t-key="item.id">
|
||||
<t t-esc="item.text"/>
|
||||
</p>
|
||||
|
||||
<t t-foreach="items" t-as="item" t-key="item.id">
|
||||
<p t-esc="item.text"/>
|
||||
</t>
|
||||
|
||||
<t t-foreach="items" t-as="item">
|
||||
<p t-key="item.id" t-esc="item.text"/>
|
||||
</t>
|
||||
```
|
||||
|
||||
If there is no `t-key` directive, Owl will use the index as a default key.
|
||||
@@ -543,23 +503,9 @@ will result in :
|
||||
|
||||
### Translations
|
||||
|
||||
If properly setup, Owl QWeb engine can translate all rendered templates. To do
|
||||
so, it needs a translate function, which takes a string and returns a string.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
const translations = {
|
||||
hello: "bonjour",
|
||||
yes: "oui",
|
||||
no: "non"
|
||||
};
|
||||
const translateFn = str => translations[str] || str;
|
||||
|
||||
const qweb = new QWeb({ translateFn });
|
||||
```
|
||||
|
||||
Once setup, all rendered templates will be translated using `translateFn`:
|
||||
By default, QWeb specify that templates should be translated. If this behaviour
|
||||
is not wanted, there is a `t-translation` directive which can turn off
|
||||
translations (if it is set to the `off` value), with the following rules:
|
||||
|
||||
- each text node will be replaced with its translation,
|
||||
- each of the following attribute values will be translated as well: `title`,
|
||||
@@ -567,26 +513,8 @@ Once setup, all rendered templates will be translated using `translateFn`:
|
||||
- translating text nodes can be disabled with the special attribute `t-translation`,
|
||||
if its value is `off`.
|
||||
|
||||
So, with the above `translateFn`, the following templates:
|
||||
|
||||
```xml
|
||||
<div>hello</div>
|
||||
<div t-translation="off">hello</div>
|
||||
<div>Are you sure?</div>
|
||||
<input placeholder="hello" other="yes"/>
|
||||
```
|
||||
|
||||
will be rendered as:
|
||||
|
||||
```xml
|
||||
<div>bonjour</div>
|
||||
<div>hello</div>
|
||||
<div>Are you sure?</div>
|
||||
<input placeholder="bonjour" other="yes"/>
|
||||
```
|
||||
|
||||
Note that the translation is done during the compilation of the template, not
|
||||
when it is rendered.
|
||||
See [here](qweb_engine.md#translations) for more information on how to setup a
|
||||
translate function in Owl QWeb.
|
||||
|
||||
### Debugging
|
||||
|
||||
+1
-1
@@ -44,7 +44,7 @@ it easier to scale application to larger size.
|
||||
|
||||
To do so, Owl currently has a small helper that makes it easy to define a
|
||||
template inside a javascript (or typescript) file: the [`xml`](reference/tags.md#xml-tag)
|
||||
helper. With this, a template is automatically registered to [QWeb](reference/qweb.md).
|
||||
helper. With this, a template is automatically registered to [QWeb](reference/qweb_engine.md).
|
||||
|
||||
This means that the template and the javascript code can be defined in the same
|
||||
file. It is not currently possible to add css to the same file, but Owl may
|
||||
|
||||
@@ -282,9 +282,7 @@ export class Component<T extends Env, Props extends {}> {
|
||||
return Promise.resolve();
|
||||
}
|
||||
if (!(target instanceof HTMLElement)) {
|
||||
let message = `Component '${
|
||||
this.constructor.name
|
||||
}' cannot be mounted: the target is not a valid DOM node.`;
|
||||
let message = `Component '${this.constructor.name}' cannot be mounted: the target is not a valid DOM node.`;
|
||||
message += `\nMaybe the DOM is not ready yet? (in that case, you can use owl.utils.whenReady)`;
|
||||
throw new Error(message);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user