diff --git a/doc/hooks.md b/doc/hooks.md index 24e5c08c..345dccc8 100644 --- a/doc/hooks.md +++ b/doc/hooks.md @@ -35,7 +35,7 @@ Owl hooks serve the same purpose, except that they work for class components there seems to be the misconception that hooks are in opposition to class. This is clearly not true, as shown by Owl hooks). -Hooks works beautifully with Owl components: they solve the problems mentioned +Hooks work beautifully with Owl components: they solve the problems mentioned above, and in particular, they are the perfect way to make your component reactive. @@ -127,7 +127,7 @@ class SomeComponent extends Component { ### One rule -There is only one rule: every hook for a component have to be called in the +There is only one rule: every hook for a component has to be called in the constructor (or in class fields): ```js @@ -152,14 +152,14 @@ class SomeComponent extends Component { } ``` -Hooks can get a reference to the currently being defined component with the -`Component.current` static property. This is why they need to be called in the -constructor. +In a hook, the `Component.current` static property is the reference to the +component instance that is currently being created. Hooks need to be called in +the constructor to ensure that this reference is properly set. ### `useState` -The `useState` hook is certainly the most important hooks for Owl components: -this is what enables component to be reactive, to react to state change. +The `useState` hook is certainly the most important hook for Owl components: +this is what allows a component to be reactive, to react to state change. The `useState` hook has to be given an object or an array, and will return an observed version of it (using a `Proxy`). @@ -183,25 +183,25 @@ class Counter extends owl.Component { ### `onMounted` -`onMounted` is not an user hook, but is a building block designed to help make useful +`onMounted` is not a user hook, but is a building block designed to help make useful abstractions. `onMounted` registers a callback, which will be called when the component is mounted (see example on top of this page). ### `onWillUnmount` -`onWillUnmount` is not an user hook, but is a building block designed to help make useful +`onWillUnmount` is not a user hook, but is a building block designed to help make useful abstractions. `onWillUnmount` registers a callback, which will be called when the component is unmounted (see example on top of this page). ### `onWillPatch` -`onWillPatch` is not an user hook, but is a building block designed to help make useful +`onWillPatch` is not a user hook, but is a building block designed to help make useful abstractions. `onWillPatch` registers a callback, which will be called just before the component patched. ### `onPatched` -`onPatched` is not an user hook, but is a building block designed to help make useful +`onPatched` is not a user hook, but is a building block designed to help make useful abstractions. `onPatched` registers a callback, which will be called just after the component patched. @@ -305,7 +305,7 @@ The `t-ref` directive also accepts dynamic values with string interpolation
``` -Here, the references needs to be set like this: +Here, the references need to be set like this: ```js this.ref1 = useRef("component_1"); @@ -321,8 +321,8 @@ The environment is sometimes useful to share some common information between all components. But sometimes, we want to _scope_ that knowledge to a subtree. For example, if we have a form view component, maybe we would like to make some -`model` object available to all sub component, but not to the whole application. -This is where the `useSubEnv` hook may be useful: it let a component add some +`model` object available to all sub components, but not to the whole application. +This is where the `useSubEnv` hook may be useful: it lets a component add some information to the environment in a way that only the component and its children can access it: @@ -366,7 +366,7 @@ But, like every good things in life, hooks should be used with moderation. They not the solution to every problem. - they may be overkill: if your component needs to perform some action specific - to him (so, the specific code does not need to be shared), there is nothing + to itself (so, the specific code does not need to be shared), there is nothing wrong with a simple class method: ```js @@ -389,7 +389,7 @@ not the solution to every problem. Note that the second solution is easier to extend in sub components. -- they may be harder to test: if a customized hook inject some external side +- they may be harder to test: if a customized hook injects some external side effect dependency, then it is harder to test without doing some non obvious manipulation. For example, assume that we want to give a reference to a router in a `useRouter` hook. We could do this: diff --git a/doc/qweb.md b/doc/qweb.md index eb4b6dd9..3e35c5bb 100644 --- a/doc/qweb.md +++ b/doc/qweb.md @@ -20,7 +20,7 @@ ## Overview -[QWeb](https://www.odoo.com/documentation/12.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. @@ -33,7 +33,7 @@ To avoid element rendering, a placeholder element `` is also available, which Some string
@@ -85,7 +85,7 @@ instantiated: const qweb = new owl.QWeb(); ``` -It's API is quite simple: +Its API is quite simple: - **`constructor(data)`**: constructor. Takes an optional string to add initial templates (see `addTemplates` for more information on format of the string). @@ -100,7 +100,8 @@ It's API is quite simple: qweb.addTemplate("mytemplate", "
hello
"); ``` - If the optional `allowDuplicate` is set to `true`, then `QWeb` will simply return whenever a template is added for a second time. Otherwise, `QWeb` will crash. + 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). @@ -128,13 +129,13 @@ It's API is quite simple: const str = qweb.renderToString("someTemplate", somecontext); ``` -- **`registerTemplate(name, template)`**: static function to register an global +- **`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", `
some template`); + QWeb.registerTemplate("mytemplate", `
some template
`); ``` - **`registerComponent(name, Component)`**: static function to register an OWL Component @@ -154,7 +155,7 @@ It's API is quite simple: In some way, a `QWeb` instance is the core of an Owl application. It is the only mandatory element of an [environment](component.md#environment). As such, it -has an extra responsability: it can act as an event bus for internal communication +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 @@ -165,7 +166,7 @@ specific extensions are documented in various other parts of the documentation. ### White Spaces -White spaces in a templates are handled in a special way: +White spaces in a template 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 @@ -207,7 +208,7 @@ component). For example, `a + b.c(d)` will be converted into: context["a"] + context["b"].c(context["d"]); ``` -It is useful to explain the various rules that applies on these expressions: +It is useful to explain the various rules that apply on these expressions: 1. it should be a simple expression which returns a value. It cannot be a statement. @@ -531,4 +532,4 @@ will stop execution if the browser dev tools are open. ``` -will print 42 to the console +will print 42 to the console.