[IMP] owl: add a new mount method

doc/learning/how_to_test.md

@@ -85,8 +85,7 @@ afterEach(() => {
 describe("SomeComponent", () => {
   test("component behaves as expected", async () => {
     const props = {...}; // depends on the component
-    const comp = new SomeComponent(null, props);
-    await comp.mount(fixture);
+    const comp = await mount(SomeComponent, { target: fixture, props });
 
     // do some assertions
     expect(...).toBe(...);

doc/learning/quick_start.md

@@ -54,7 +54,7 @@ Now, `index.html` should contain the following:
 And `app.js` should look like this:
 
 ```js
-const { Component } = owl;
+const { Component, mount } = owl;
 const { xml } = owl.tags;
 const { whenReady } = owl.utils;
 
@@ -65,8 +65,7 @@ class App extends Component {
 
 // Setup code
 function setup() {
-  const app = new App();
-  app.mount(document.body);
+  mount(App, target: { document.body })
 }
 
 whenReady(setup);
@@ -124,7 +123,7 @@ Here is the content of `app.js` and `main.js`:
 
 ```js
 // app.js ----------------------------------------------------------------------
-const { Component } = owl;
+const { Component, mount } = owl;
 const { xml } = owl.tags;
 
 export class App extends Component {
@@ -135,8 +134,7 @@ export class App extends Component {
 import { App } from "./app.js";
 
 function setup() {
-  const app = new App();
-  app.mount(document.body);
+  mount(App, { target: document.body });
 }
 
 owl.utils.whenReady(setup);
@@ -240,12 +238,11 @@ export class App extends Component {
 }
 
 // src/main.js -----------------------------------------------------------------
-import { utils } from "@odoo/owl";
+import { utils, mount } from "@odoo/owl";
 import { App } from "./components/App";
 
 function setup() {
-  const app = new App();
-  app.mount(document.body);
+  mount(App, { target: document.body });
 }
 
 utils.whenReady(setup);
@@ -253,6 +250,7 @@ utils.whenReady(setup);
 // tests/components/App.test.js ------------------------------------------------
 import { App } from "../../src/components/App";
 import { makeTestFixture, nextTick, click } from "../helpers";
+import { mount } from "@odoo/owl";
 
 let fixture;
 
@@ -266,8 +264,7 @@ afterEach(() => {
 
 describe("App", () => {
   test("Works as expected...", async () => {
-    const app = new App();
-    await app.mount(fixture);
+    await mount(App, { target: fixture });
     expect(fixture.innerHTML).toBe("<div>Hello Owl</div>");
 
     click(fixture, "div");

doc/learning/tutorial_todoapp.md

@@ -83,7 +83,7 @@ a single root component. Let us start by defining an `App` component. Replace th
 content of the function in `app.js` by the following code:
 
 ```js
-const { Component } = owl;
+const { Component, mount } = owl;
 const { xml } = owl.tags;
 const { whenReady } = owl.utils;
 
@@ -94,8 +94,7 @@ class App extends Component {
 
 // Setup code
 function setup() {
-  const app = new App();
-  app.mount(document.body);
+  mount(App, { target: document.body });
 }
 
 whenReady(setup);
@@ -279,8 +278,7 @@ class App extends Component {
 // -------------------------------------------------------------------------
 function setup() {
     owl.config.mode = "dev";
-    const app = new App();
-    app.mount(document.body);
+    mount(App, { target: document.body });
 }
 
 whenReady(setup);
@@ -639,8 +637,7 @@ function setup() {
   owl.config.mode = "dev";
   const store = new Store({ actions, state: initialState });
   App.env.store = store;
-  const app = new App();
-  app.mount(document.body);
+  mount(App, { target: document.body });
 }
 
 whenReady(setup);
@@ -666,9 +663,8 @@ function makeStore() {
 
 function setup() {
   owl.config.mode = "dev";
-  App.env.store = makeStore();
-  const app = new App();
-  app.mount(document.body);
+  const env = {store = makeStore()};
+  mount(App, { target: document.body, env });
 }
 ```
 
@@ -943,9 +939,8 @@ For reference, here is the final code:
 
   function setup() {
     owl.config.mode = "dev";
-    App.env.store = makeStore();
-    const app = new App();
-    app.mount(document.body);
+    const env = {store = makeStore()};
+    mount(App, { target: document.body, env });
   }
 
   whenReady(setup);

doc/readme.md

@@ -27,6 +27,7 @@ provided by Owl.
 - [Event Handling](reference/event_handling.md)
 - [Error Handling](reference/error_handling.md)
 - [Hooks](reference/hooks.md)
+- [Mounting a component](reference/mounting.md)
 - [Miscellaneous Components](reference/misc.md)
 - [Observer](reference/observer.md)
 - [Props](reference/props.md)

doc/reference/component.md

@@ -270,6 +270,10 @@ We explain here all the public methods of the `Component` class.
   // app is now visible
   ```
 
+  Note that the normal way of mounting an application is by using the `mount`
+  method on a component class, not by creating the instance by hand. See the
+  documentation on [mounting applications](mounting.md).
+
 * **`unmount()`**: in case a component needs to be detached/removed from the DOM, this
   method can be used. Most applications should not call `unmount`, this is more
   useful to the underlying component system.

doc/reference/content.md

@@ -10,10 +10,11 @@ exported as `owl.core.EventBus`.
 Component                               misc
 Context                                     AsyncRoot
 QWeb                                        Portal
-Store                                   router
-useState                                    Link
-config                                      RouteComponent
-    mode                                    Router
+mount                                   router
+Store                                       Link
+useState                                    RouteComponent
+config                                      Router
+    mode
 core                                    tags
     EventBus                                css
     Observer                                xml

doc/reference/environment.md

@@ -49,15 +49,14 @@ The correct way to customize an environment is to simply set it up on the root
 component class, before the first component is created:
 
 ```js
-App.env = {
+const env = {
     _t: myTranslateFunction,
     user: {...},
     services: {
         ...
     },
 };
-const app = new App();
-app.mount(document.body);
+mount(App, { target: document.body, env });
 ```
 
 It is also possible to simply share an environment between all root components,
@@ -121,9 +120,8 @@ async function myEnv() {
 }
 
 async function start() {
-  App.env = await myEnv();
-  const app = new App();
-  await app.mount(document.body);
+  const env = await myEnv();
+  mount(App, { target: document.body, env });
 }
 ```
 

doc/reference/misc.md

@@ -43,7 +43,7 @@ workflow to help the user put in some data, which it could use later on.
 JavaScript:
 
 ```js
-const { Component } = owl;
+const { Component, mount } = owl;
 const { Portal } = owl.misc;
 
 class TeleportedComponent extends Component {}
@@ -51,8 +51,7 @@ class App extends Component {
   static components = { Portal, TeleportedComponent };
 }
 
-const app = new App();
-app.mount(document.body);
+mount(App, { target: document.body });
 ```
 
 XML:

doc/reference/mounting.md

@@ -0,0 +1,60 @@
+# 🦉 Mounting an application 🦉
+
+## Content
+
+- [Overview](#overview)
+- [API](#api)
+
+## Overview
+
+Mounting an Owl application is done by using the `mount` method (available in
+`owl.mount` if you are using the iife build, or it can be directly imported
+from `owl` if you are using a module system):
+
+```js
+const mount = { owl }; // if owl is available as an object
+
+const env = { ... };
+const app = await mount(MyComponent, { target: document.body, env });
+```
+
+Another example:
+
+```js
+const config = {
+  env: ...,
+  props: ...,
+  target: document.body,
+  position: "self",
+};
+const app = await mount(App, config);
+```
+
+A common way to initialize an application is to first setup an environment,
+then to call the `mount` method.
+
+## API
+
+Mount takes two parameters:
+
+- `C`, which should be a component class (NOT instance),
+- `params`, which is an object with the following keys:
+  - `target (HTMLElement | DocumentFragment)`: the target of the mount operation
+  - `env (optional, Env)` an environment
+  - `position (optional, "first-child" | "last-child" | "self")` the position
+    where it should be mounted (see below for more informations)
+  - `props (optional, any)`: some initial values that are given as props. Useful
+    when the root component is configurable, or when testing sub components
+
+Here are the various positions supported by Owl:
+
+- `first-child`: with this option, the component will be prepended inside the target,
+- `last-child` (default value): with this option, the component will be
+  appended in the target element,
+- `self`: the target will be used as the root element for the component. This
+  means that the target has to be an HTMLElement (and not a document fragment).
+  In this situation, it is possible that the component cannot be unmounted. For
+  example, if its target is `document.body`.
+
+The `mount` method returns a promise that resolves to the instance of the created
+component.

doc/reference/utils.md

@@ -21,8 +21,8 @@ argument, it executes it as soon as the DOM ready (or directly).
 ```js
 Promise.all([loadFile("templates.xml"), owl.utils.whenReady()]).then(function ([templates]) {
   const qweb = new owl.QWeb({ templates });
-  const app = new App({ qweb });
-  app.mount(document.body);
+  const env = { qweb };
+  await mount(App, { env, target: document.body });
 });
 ```
 
@@ -31,8 +31,8 @@ or alternatively:
 ```js
 owl.utils.whenReady(function () {
   const qweb = new owl.QWeb();
-  const app = new App({ qweb });
-  app.mount(document.body);
+  const env = { qweb };
+  await mount(App, { env, target: document.body });
 });
 ```