This document contains an overview of all changes between Owl 1.x and Owl 2.x, with some pointers on how to update the code.
Note that some of these changes can be magically implemented (for example, by
patching the setup method of Component to auto register all the lifecycle
methods as hooks). This will be done for the transition period, but will be
removed after.
All changes are documented here in no particular order.
Components
- components can now have empty content or multiple root nodes (htmlelement or text) (details)
- breaking: component.el is removed (details)
- new
useEffecthook (doc) - new
onWillDestroy,onWillRenderandonRenderedhooks (doc) - breaking: lifecycle methods are removed (details)
- breaking: can no longer be mounted on detached DOM (details)
- breaking: standalone
mountmethod API is simpler (details) - breaking: components can no longer be instantiated and mounted by hand (details)
- breaking: components can no longer be unmounted/remounted (details)
- breaking: template name is no longer inferred from the class name (details)
- breaking: components no longer have a
shouldUpdatemethod (details) - breaking: components can no longer be mounted with position=self (details)
- breaking:
rendermethod does not return a promise anymore (details) - breaking:
catchErrormethod is replaced byonErrorhook (details) - breaking: Support for inline css (
csstag and staticstyle) has been removed (details) - new: prop validation system can now describe that additional props are allowed (with
*) (doc) - breaking: prop validation system does not allow default prop on a mandatory (not optional) prop (doc)
- breaking: rendering a component does not necessarily render child components (details)
Templates
- breaking:
t-foreachshould always have a correspondingt-key(details) - breaking:
t-refdoes not work on components (details) - breaking:
t-rawdirective has been removed (replaced byt-out) (details) - new: add support for synthetic events (doc)
- breaking: style/class on components are now regular props (details)
- new: components can use the
.bindsuffix to bind function props (doc) - breaking:
t-ondoes not accept expressions, only functions (details) - new: an error is thrown if an handler defined in a
t-on-directive is not a function (failed silently previously in some cases) - breaking:
t-componentno longer accepts strings (details) - new: the
thisvariable in template expressions is now bound to the component
Reactivity
- finer grained reactivity: owl 2 tracks change per key/component
- finer grained reactivity: sub components can reobserve state (doc)
- new:
reactivefunction: create reactive state (without being linked to a component) (doc) - new:
markRawfunction: mark an object or array so that it is ignored by the reactivity system (doc) - new:
toRawfunction: given a reactive objet, return the raw (non reactive) underlying object (doc)
Slots
- breaking:
t-setdoes not define a slot any more (details) - slots capabilities have been improved (doc)
- params can be give to slot content (to pass information from slot owner to slot user)
- slots are given as a
prop(and can be manipulated/propagated to sub components ) - slots can define scopes (to pass information from slot user to slot owner)
Portal
- Portal are now defined with
t-portal(details) - portals can now have arbitrary content (no longer restricted to one single child)
- breaking: does no longer transfer dom events (details)
- breaking: does render as an empty text node instead of
<portal/>(details)
Miscellaneous
- improved performance
- much simpler code
- new App class to encapsulate a root Owl component (with the config for that application) (doc)
- new
useEffecthook (doc) - breaking:
Contextis removed (details) - breaking:
envis now totally empty (details) - breaking:
envis now frozen (details) - new hook:
useChildSubEnv(only applies to child components) (details) - breaking: most exports are exported at top level (details)
- breaking: properties are no longer set as attributes (details)
- breaking:
EventBusapi changed: it is now anEventTarget(details) - breaking:
Storeis removed (details) - breaking:
Routeris removed (details) - breaking: transition system is removed (details)
- breaking: no more global components or templates (details)
- breaking:
AsyncRootutility component is removed (details) - breaking:
renderToStringfunction on qweb has been removed (details) - breaking:
debounceutility function has been removed (details) - breaking:
browserobject has been removed (details)
All changes are listed in no particular order.
There was two ways to define hooks: the component methods (willStart, mounted, ...) and the hooks (onWillStart, onMounted, ...). In Owl 2, the component methods have been removed.
Rationale: it makes the implementation simpler and slightly faster. Hooks are more composable than component methods. It enforces a single entry point to check all the useful lifecycle calls (instead of it being scattered in the component definition). It feels more "modern".
Migration: lifecycle methods should be defined in the setup:
class MyComponent extends Component {
mounted() {
// do something
}
}should become:
class MyComponent extends Component {
setup() {
onMounted(() => {
// do something
});
}
}Documentation: Component Lifecycle
Nor document fragment.
Rationale: it is actually very difficult to do it: this implies that a component can be mounted more than once, that we need to check every time different status, that some elements is in the dom, and was a cause for bugs. Also, we don't use it in practice. Removing this means that we have a much simpler mental model of what happens.
Migration: well, not really easy. The code needs to be refactored in a different way.
The t-set directive cannot define a slot anymore. Only the t-set-slot directive
can do it.
Rationale: it was left for compatibility reason, but was deprecated anyway.
Migration: t-set should be changed to t-set-slot (when defining a slot)
Example:
<SideBar><t t-set="content">content</t></SideBar>should become:
<SideBar><t t-set-slot="content">content</t></SideBar>Before, the mount method was used like this:
await mount(Root, { target: document.body });It is now simpler and takes the root component and a target argument:
await mount(Root, document.body);Rationale: the mount method is only useful anyway for small toy examples,
because real applications will need to configure the templates, the translations,
and other stuff. All complex usecases need to go through the new App class,
that encapsulates the root of an owl application.
Documentation: Mounting a component
In Owl 1, it was possible to instantiate a component by hand:
const root = new Root();
await root.mount(document.body);Now, it is no longer possible. All component instantiations should be done by the owl framework itself.
Rationale: the mount method does not make sense for all non root components.
Also, the fact that it was possible for a component to be sometimes root,
sometimes a child made for a weird constructor signature. This changes makes it
simpler.
Migration: all code doing that should use either the mount method (if the use
case is simple enough, or the App class):
const app = new App(Root);
app.configure({ templates: ..., ...});
await app.mount(document.body);Rationale: this is a very difficult feature to implement (it adds a lot of possible state transitions), compared to its benefit.
Migration: all code using it should find a way to export and reimport the state
Before, it was possible to define a component without specifying its template:
class Blabla extends Component {
// no static template here!
}with the Blabla template. It also worked with subclasses. But then, this means
that the code had to look up all the super classes names to find the correct
template.
Rationale: in practice, it is not really useful, since all templates are usually
namespaced: web.SomeComponent anyway. All the trouble to do that was just not
worth it.
Migration: simply explicitely defines the template key everytime:
class Blabla extends Component {}
Blabla.template = "Blabla";Rationale: shouldUpdate is a dangerous method to use, that may cause a lot of
issues. Vue does not have such a mechanism (see vuejs/vue#4255),
because the reactivity system in Vue is smart enough to only rerender the minimal
subset of components that is subscribed to a piece of state. Now, Owl 2 features
a much more powerful reactivity system, so the same rationale applies: in a way,
it's like each Owl 2 component has a shouldUpdate method that precisely tracks
every value used by the component.
Migration code: remove the shouldUpdate methods, and it should work as well
as before.
This comes from the fact that Owl 2 supports fragments (arbitrary content).
Migration: if one need a reference to the root htmlelement of a template, it is
suggested to simply add a ref on it, and access the reference as needed.
Documentation: Refs
Before, it was possible to do this in a template:
<Child style="..." class="..."/>(or with t-att-style and t-att-class). This does no longer work, as they are
now considered normal props.
Rationale: with the move to fragments, the semantics of where the style/class
attribute should be set is unclear. Also, it is actually very hard to implement
properly, in particular with higher order components. And another issue is that
it (slightly) breaks the encapsulation of behaviour from the Child component
perspective.
Migration: each component that wishes to be customized should explicitely add
the class and style attributes in its template. Also, the parent component
should be aware that since we are talking about props, it should be a javascript expression:
In parent:
<Child class="'o_my_god'"/>and in child:
<div t-att-class="props.class">
...
</div>Rationale: this is due to the implementation of owl 2 virtual dom. The hack
necessary to support position=self does not work. This position also is not
compatible with the fact that a component can have a root <div> then later,
change it to something else, or even a text node.
Migration: no real way to do the same. Owl application needs to be appended or
prepended in something, maybe a div. Remember that you the root component
can have multiple roots
Documentation:
In Owl 1, a Portal component would listen to events emitted on its portalled child, and redispatch them on itself. It no longer works.
Rationale: Portal now supports an arbitrary content (so, more than one child,
and potentially no html element), so it is already unclear what it should listen
to. Also, redispatching events was an hack. And this changes allows the portal
to render itself as a text node, which is nice. This is also in line with the
fact that modern Owl moves toward using callback instead of t-on for communication.
Migration: use callback if possible to communicate. Otherwise, use a sub env.
That is pretty nice. No real migration needed.
Context was an abstraction in Owl that was used to define some reactive state and to let some components subscribe to it, then only them would be rerendered if the context was updated. This has been removed.
Rationale: first, the Context api and code was kind of awkward, which is a sign that the abstraction is not well thought. But the good news is that it is actually completely replaced by the new reactivity system, which is even more powerful, since it can tracks changes key by key.
Migration: replace all uses of Context with the new reactivity system.
// somewhere, maybe in a service, or in the global env
const context = observe({some: "state"})
// in a component that would previously get a reference to the context:
setup() {
this.context = useState(context);
// now the component is subscribed to the context and will react to any
// change for any key read by the component, and only those changes
}In Owl 1, the env object had to contain a QWeb instance. This was the way
components would get a reference to their template function. It no longer works
that way: the env object is now totally empty (from the perspective of Owl).
It is now a user space concept, useful for the application.
Rationale: first, there is no longer a QWeb class. Also, this changes simplifies the way components works internally.
Migration: there is no proper way to get an equivalent. The closest is to get
a reference to the root App using this.__owl__.app. If you need to do this,
let us know. If this is a legitimate usecase, we may add a useApp hook.
Documentation: Environment
In owl 1, we could write this:
<t t-component="Coucou"/>This meant that Owl would look for the component class like this: components["Coucou"],
so, essentially equivalent to <Coucou/>. In Owl 2, the t-component directive
is assumed to be an expression evaluating to a component class:
class Parent extends Component {
static template = xml`<t t-component="Child"/>`;
Child = Child;
}Rationale: it simply seems more consistent with the way directive works. Also, the implementation is slightly simpler.
Migration: simply using constructor.components.Coucou instead of Coucou will
do the trick.
Documentation: Component
Most exports are flattened: for ex, onMounted is in owl, not in owl.hooks.
Rationale: this makes it easier to work with, instead of importing stuff from
owl, then owl.hooks and owl.tags for example.
Migration: all import code simply need to be slightly adapted.
Formerly, html properties <input type="checkbox" t-att-checked="blah"/> were
set as property and as attribute, so, they would be visible in the DOM:
<input type="checkbox" checked="blah"/>. Now, they are treated as property only:
<input type="checkbox"/>.
Rationale: this is actually simple to do, is faster, and makes more sense to me.
It was possible in Owl 1 to write a t-foreach without a t-key. In that case,
the index was used as key. Since it was clearly a possible bug, Owl 1 had a
warning in some cases, when it could detect that there was definitely not a t-key.
However, this was imperfect, and in some cases no warning was displayed. In Owl 2,
the tag with a t-foreach has to have a corresponding t-key.
Rationale: this makes it easier to avoid bugs.
Migration: simply move the t-key to the tag with the t-foreach. If this is
a situation where there is really not a need for a t-key, you can still add
it with the _index suffix:
<div t-foreach="items" t-as="item" t-key="item_index">
...
</div>In Owl 1, the EventBus class was done manually, with a custom API. In Owl 2,
it simply extends EventTarget (the native Dom class), so its implementation
is basically only 5 lines long. This means that it has now the usual DOM interface:
bus.addEventListener('event-name', callback);Rationale: it makes it easier to have just one interface to remember, it makes the code simpler
Migration: most bus methods need to be adapted. So, bus.on("event-type", owner, (info) => {...}) has to be
rewritten like this: bus.addEventListener("event-type", (({detail: info}) => {...}).bind(owner)).
Do not forget to similarly replace bus.off(...) by bus.removeEventListener(...)
Documentation: EventBus
The Store system had been abandoned in owl 2.
Rationale: first, it was complicated to maintain. Second, it was not really used in Odoo. Finally, the new reactivity system seems to be a pretty good basis to write a store, and it should not take much work. Also, this can be done in user space (so, not necessarily at the framework level). Another point is that the store API was invented before the hooks, then was still a little awkward.
Migration:
- rewrite the code not to use a store
- probably use the reactivity system instead and build a store class and a few hooks on top of it.
Rationale: Router was not used that much, and it felt like it did not fit in Owl 2. Its API needs to be reworked, and we are not confident that it is a good experience to use it. Also, it can be done in userspace (it does not need specific integration at the framework level)
Migration: reimport all missing piece from the code in Owl 1.
Rationale: this was a high ratio cost/value, with a lot of potential for bugs. We feel like there should be a way to reimplement in userspace the simple cases.
Maybe something like: add a t-ref in the template, and define a hook useFadeOut
that takes the ref, and add a fadeout class at initial render, then in mounted,
wait for a micro tick and remove it.
Migration: try to reimplement it manually.
It was possible in Owl 1 to register globally a component or a template. This is no longer the case in Owl 2.
Rationale: first, this was a tradeoff: ease of use was gained, but at the cost
of a higher complexity. Users had to know that there was a magic mechanism. Also,
it was not used much in practice, and the cost of having to import manually components
is low. Finally, this can be mostly done in user space (for example, by subclassing
Component).
Migration: import manually all required global components, or find a way to organize the code to do it.
Rationale: it was difficult to understand, never used, and not really useful. It seems better to control the asynchrony of an application by simply controlling how/when the state is updated, and how each component is loading/updating itself.
Migration: remove the AsyncRoot component, then possibly, reorganize the code
to fetch data in a higher order component, and using a t-if/t-else to display
either a fallback when the data is not ready, or the actual component with data
as props. If there is no escape, and AsyncRoot is needed, please reach out to
us so we can study this usecase.
In Owl, a call to useSubEnv would define a new environment for the children
AND the component. It is very useful, but in some cases, one only need to update
the children component environment. This can now be done with a new hook:
useChildSubEnv
In Owl 2, the env object is frozen. It can no longer be modified (structurally)
arbitrarily.
Rationale: it seems like the env object purpose is to have a global channel of
communication between components. It is however scary if anyone can add something
to it. The usual use case is to add something to the environment for some child
components. This use case still works with useSubEnv.
Migration: use useSubEnv instead of writing directly to the env. Also, note
that the environment given to the App can initially contain anything.
Documentation: Environment
Before, t-ref could be used to get a reference to a child component. It no
longer works.
Rationale: the possibility of having a ref to a child component breaks the encapsulation provided by Owl components: a child component now has a private and a public interface. Another issue is that it may be unclear when the ref should be set: is the component active on setup, or on mounted? Also, it is kind of awkward to implement.
Migration: the env and props should provide a communication channel wide enough:
the sub component can expose its public API by calling a callback at the proper
timing, or by triggering an event.
In Owl 1, it was possible to define simple expressions inline, in a template:
<button t-on-click="state.value = state.value + 1">blabla</button>
<button t-on-click="someFunction(someVar)">blabla</button>This does not work anymore. Now, the t-on directive assumes that what it get is
a function.
Rationale: the fact that owl 1 had to support expressions meant that it was not possible to properly inject the event in general. With this restriction, Owl 2 can support more general use cases. Also, the examples above can simply be wrapped in a lambda function.
Migration: use lambda functions. For example, the two examples above can be adapted like this:
<button t-on-click="() => state.value = state.value + 1">blabla</button>
<button t-on-click="() => this.someFunction(someVar)">blabla</button>Documentation: Event Handling
Before Owl 2, components had to limit themselves to one single htmlelement as root. Now, the content is arbitrary: it can be empty, or multiple html elements. So, the following template works for components:
<div>1</div>
<div>2</div>
helloDocumentation: Fragments
Rationale: the renderToString function was a qweb method, which made sense because
the qweb instance knew all templates. But now, the closest analogy is the App
class, but it is not as convenient, since the app instance is no longer visible
to components (while before, qweb was in the environment).
Also, this can easily be done in userspace, by mounting a component in a div. For example:
export async function renderToString(template, context) {
class C extends Component {
static template = template;
setup () {
Object.assign(this, context);
}
}
const div = document.createElement('div');
document.body.appendChild(div);
const app = new App(C);
await app.mount(div);
const result = div.innerHTML;
app.destroy();
div.remove();
return result;
}The function above works for most cases, but is asynchronous. An alternative function could look like this:
const { App, blockDom } = owl;
const app = new App(Component); // act as a template repository
function renderToString(template, context = {}) {
app.addTemplate(template, template, { allowDuplicate: true });
const templateFn = app.getTemplate(template);
const bdom = templateFn(context, {});
const div = document.createElement('div')
blockDom.mount(bdom, div);
return div.innerHTML;
}This is a synchronous function, so it will not work with components, but it should be useful for most simple templates.
Also note that these two examples do not translate their templates. To do that,
they need to be modified to pass the proper translate function to the App
configuration.
Before Owl 2, one could use the Portal component by importing it and using it.
Now, it is no longer available. Instead, we can simply use the t-portal directive:
<div>
some content
<span t-portal="'body'">
portalled content
</span>
<div>Rationale: it makes it slightly simpler to use (just need the directive, instead of having to import and use a sub component), it makes the implementation slightly simpler as well. Also, it prevents subclassing the Portal component, which could be dangerous, since it is really doing weird stuff under the hood, and could easily be broken inadvertendly.
Rationale: it did not really help that much, is available as utility function elsewhere, so, we decided to have a smaller footprint by focusing Owl on what it does best.
Rationale: using the render method directly and waiting for it to complete
was slightly un-declarative. Also, it can be done using the lifecycle hooks
any way.
Migration: if necessary, one can use the lifecycle hooks to execute code after the next mounted/patched operation.
The catchError method was used to provide a way to components to handle errors
occurring during the component lifecycle. This has been replaced by a onError
hook, with a similar API.
Rationale: catchError felt a little big awkward, when most of the way we
interact with componentss is via hooks. Using hooks felt more natural and
consistent.
Migration: mostly replace all catchError methods by onError hooks in the
setup method.
Documentation: Error Handling
Rationale: Owl tries to focus on what it does best, and supporting inline css was not a priority. It used to support some simplified scss language, but it was feared that it would cause more trouble than it was worth. Also, it seems like it can be done in userspace.
Migration: it seems possible to implement an equivalent solution using hooks. A simple implementation could look like this:
let cache = {};
function useStyle(css) {
if (!css in cache) {
const sheet = document.createElement("style");
sheet.innerHTML = css;
cache[css] = sheet;
document.head.appendChild(sheet);
}
}To match the Odoo qweb server implementation, Owl does no longer implement t-raw.
It is replaced by the t-out directive, which is safer: it requires the data
to be marked explicitely as markup if it is to be inserted without escaping.
Otherwise, it will be escaped (just like t-esc).
Migration: replace all t-raw uses by t-out, and uses the markup function
to mark all the js values.
Documentation: Outputting data
Rationale: the browser object caused more trouble than it was worth. Also, it
seems like this should be done in user space, not at the framework level.
Migration: code should just be adapted to either use another browser object, or to use native browser function (and then, just mock them directly).
Before, if one had the following component tree:
graph TD;
A-->B;
A-->C;
when A would render, it would also render B and C. Now, in Owl 2, it will
(shallow) compare the before and after props, and B or C will only be rerendered
if their props have changed.
Now, the question is what happens if the props have changed, but in a deeper way?
In that case, Owl will know, because each props are now reactive. So, if some
inner value read by B was changed, then only B will be updated.
Rationale: This was just not possible in Owl 1, but it now possible. This is due to the rewriteof the underlying rendering engine and the reactivity system. The goal is to have a big performance boost in large screen with many components: now Owl only rerender what is strictly useful.