diff --git a/doc/comparison.md b/doc/comparison.md index 4084e159..57beba9c 100644 --- a/doc/comparison.md +++ b/doc/comparison.md @@ -274,7 +274,7 @@ class Counter extends Component { dispatch = useDispatch(); } -owl.config.env.store = store; +Counter.env.store = store; const counter = new Counter(); ``` diff --git a/doc/learning/environment.md b/doc/learning/environment.md index 2882032a..8bfb69b1 100644 --- a/doc/learning/environment.md +++ b/doc/learning/environment.md @@ -40,7 +40,7 @@ async function myEnv() { } async function start() { - owl.config.env = await myEnv(); + App.env = await myEnv(); const app = new App(); await app.mount(document.body); } diff --git a/doc/learning/quick_start.md b/doc/learning/quick_start.md index c3dd58d8..723cd285 100644 --- a/doc/learning/quick_start.md +++ b/doc/learning/quick_start.md @@ -97,8 +97,7 @@ class ClickCounter extends owl.Component { //------------------------------------------------------------------------------ async function start() { const templates = await owl.utils.loadFile("templates.xml"); - const qweb = new owl.QWeb({ templates }); - owl.config.env.qweb = qweb; + ClickCounter.env = { qweb: new owl.QWeb({ templates }) }; const counter = new ClickCounter(); const target = document.getElementById("main"); await counter.mount(target); diff --git a/doc/readme.md b/doc/readme.md index 6958e6de..8a526e6e 100644 --- a/doc/readme.md +++ b/doc/readme.md @@ -50,15 +50,14 @@ Store Link useState RouteComponent config Router mode tags - env xml -core utils - EventBus debounce - Observer escape -hooks loadJS - onWillStart loadFile - onMounted shallowEqual - onWillUpdateProps whenReady - onWillPatch +core xml + EventBus utils + Observer debounce +hooks escape + onWillStart loadJS + onMounted loadFile + onWillUpdateProps shallowEqual + onWillPatch whenReady onPatched onWillUnmount useContext diff --git a/doc/reference/component.md b/doc/reference/component.md index ae99b39e..d21f8138 100644 --- a/doc/reference/component.md +++ b/doc/reference/component.md @@ -444,7 +444,8 @@ app.mount(document.body); ``` The root component does not have a parent nor props. It will be setup with an -[environment](environment.md) (located in `owl.config.env`). +[environment](environment.md) (either the `env` defined on its class, or a +default empty environment). ### Composition diff --git a/doc/reference/config.md b/doc/reference/config.md index 8bddf307..59872965 100644 --- a/doc/reference/config.md +++ b/doc/reference/config.md @@ -2,10 +2,9 @@ The Owl framework is designed to work in many situations. However, it is sometimes necessary to customize some behaviour. This is done by using the -global `config` object. It currently has two keys: +global `config` object. It currently has one key: -- [`mode`](#mode), -- [`env`](#env). +- [`mode`](#mode). ## Mode @@ -26,31 +25,3 @@ So, changing this setting is best done at startup. An important job done by the `dev` mode is to validate props for each component creation and update. Also, extra props will cause an error. - -## Env - -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 -all templates. - -Whenever a root component is mounted, Owl will take the environment from -`owl.config.env` and use it to setup the component (and its children). - -- if no environment was setup, an empty environment will be generated, -- if an environment exists, but does not have a QWeb key, a new QWeb instance - will then be added to the environment. - -The correct way to customize an environment is to simply modify `owl.config.env` -before the first component is created: - -```js -owl.config.env = { - _t: myTranslateFunction, - user: {...}, - services: { - ... - }, -}; -const app = new App(); -app.mount(document.body); -``` diff --git a/doc/reference/context.md b/doc/reference/context.md index abdbec0a..927db380 100644 --- a/doc/reference/context.md +++ b/doc/reference/context.md @@ -28,7 +28,7 @@ context, and add it to the environment: ```js const deviceContext = new Context({ isMobile: true }); -owl.config.env.deviceContext = deviceContext; +App.env.deviceContext = deviceContext; ``` If we want to make it completely responsive, we need to update its value whenever @@ -53,14 +53,14 @@ fact that we are in a mobile or desktop mode. ```js class SomeComponent extends Component { static template = xml` -
- - some simplified user interface - - - some more sopthisticated user interface - - `; +
+ + some simplified user interface + + + a more advanced user interface + +
`; device = useContext(this.env.deviceContext); } ``` diff --git a/doc/reference/environment.md b/doc/reference/environment.md index fa4932b6..40d19caf 100644 --- a/doc/reference/environment.md +++ b/doc/reference/environment.md @@ -1,7 +1,10 @@ # 🦉 Environment 🦉 -An environment is an object which contains a [`QWeb` instance](qweb.md). Whenever a root component is created, it is assigned an environment. This environment -is then automatically given to each sub component (and accessible in the `this.env` property). +An environment is an object which contains a [`QWeb` instance](qweb.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` +property). ``` Root @@ -11,7 +14,40 @@ is then automatically given to each sub component (and accessible in the `this.e This way, all components share the same `QWeb` instance. -Note: some additional information can be found here: +Note: some additional information about what should go into an environment +can be found in the [learning section](../learning/environment.md). -- [What should go into an environment?](../learning/environment.md) -- [Customizing an environment](config.md#env) +## 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 +all templates. + +Whenever a root component `App` is mounted, Owl will setup a valid environment by +following the next steps: + +- take the `env` object defined on `App.env` (if no `env` was explicitely setup, + this will be return the empty `env` object defined on `Component`) +- if `env.qweb` is not set, then Owl will create a `QWeb` instance. + +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 = { + _t: myTranslateFunction, + user: {...}, + services: { + ... + }, +}; +const app = new App(); +app.mount(document.body); +``` + +It is also possible to simply share an environment between all root components, +by simply doing this: + +```js +Component.env = myEnv; // will be the default env for all components +``` diff --git a/doc/reference/router.md b/doc/reference/router.md index 2b6e4020..251e1672 100644 --- a/doc/reference/router.md +++ b/doc/reference/router.md @@ -68,7 +68,7 @@ function makeEnvironment() { return env; } -owl.config.env = makeEnvironment(); +App.env = makeEnvironment(); // create root component here ``` diff --git a/src/component/component.ts b/src/component/component.ts index 50d0d1f4..62be517f 100644 --- a/src/component/component.ts +++ b/src/component/component.ts @@ -136,7 +136,7 @@ export class Component { if (!this.env.qweb) { this.env.qweb = new QWeb(); } - this.props = undefined as unknown as Props; + this.props = (undefined as unknown) as Props; this.env.qweb.on("update", this, () => { if (this.__owl__.isMounted) { this.render(true); diff --git a/src/config.ts b/src/config.ts index e667d136..209674ab 100644 --- a/src/config.ts +++ b/src/config.ts @@ -19,7 +19,7 @@ Object.defineProperty(config, "mode", { set(mode: string) { QWeb.dev = mode === "dev"; if (QWeb.dev) { - const url = `https://github.com/odoo/owl/blob/master/doc/tooling.md#development-mode`; + const url = `https://github.com/odoo/owl/blob/master/doc/reference/config.md#mode`; console.warn( `Owl is running in 'dev' mode. This is not suitable for production use. See ${url} for more information.` );