From 1a778922af940a4fcef00a07a166e5781fa09fd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= <ged@odoo.com>
Date: Tue, 23 Apr 2019 15:26:00 +0200
Subject: [PATCH] [DOC] doc: update a lot of the documentation

---
 README.md                             | 128 ++++++-----------
 doc/comparison.md                     | 194 ++++++++++++++++++++++++++
 doc/component.md                      |  15 ++
 doc/observer.md                       |   2 +
 doc/readme.md                         |  19 ++-
 doc/{state_management.md => store.md} |   0
 doc/tutorial.md                       |   3 -
 doc/vdom.md                           |   3 +
 8 files changed, 266 insertions(+), 98 deletions(-)
 create mode 100644 doc/comparison.md
 create mode 100644 doc/observer.md
 rename doc/{state_management.md => store.md} (100%)
 delete mode 100644 doc/tutorial.md
 create mode 100644 doc/vdom.md

diff --git a/README.md b/README.md
index 4114793d..7fbfd33b 100644
--- a/README.md
+++ b/README.md
@@ -2,83 +2,30 @@
 
 ## Project Overview
 
-The Odoo Web Library (OWL) is a small (currently around 11k minified and gzipped)
-framework intended to be the basis for the Odoo Web Client, and hopefully many
-other Odoo related projects.
+The Odoo Web Library (OWL) is a small 
+UI framework intended to be the basis for the [Odoo](https://www.odoo.com/) Web Client, and hopefully many
+other Odoo related projects. OWL's two key features are:
 
-Briefly, the OWL framework contains:
+- a declarative component system, with QWeb as a template engine, asynchronous rendering, and an underlying virtual dom,
+- and a store (state management solution, loosely inspired by VueX and React/Redux).
 
-- a declarative component system, with a virtual dom based on a fork of Snabbdom
-- and a store (state management solution, loosely inspired by VueX and React/Redux)
+If you are interested, you can find a discussion on what makes OWL different
+from React and Vue [here](doc/comparison.md)
 
-The component system is designed to be:
+## Try it online!
 
-1. **declarative:** the user interface should be described in term of the state
-   of the application, not as a sequence of imperative steps.
+An online playground is available at [https://odoo.github.io/owl/](https://odoo.github.io/owl/) to let you experiment with the OWL framework.
 
-2. **composable:** each widget can seamlessly be created in a parent widget by
-   a simple directive in its template.
+# Example
 
-3. **asynchronous rendering:** the framework will transparently wait for each
-   subwidgets to be ready before applying the rendering. It uses native promises
-   under the hood.
-
-4. **uses QWeb as a template system:** the templates are described in XML
-   and follow the QWeb specification. This is a requirement for Odoo.
-
-## Try it online
-
-You can experiment with the OWL project online: [https://odoo.github.io/owl/](https://odoo.github.io/owl/)
-
-## Installing/Building
-
-Some npm scripts are available:
-
-| Command            | Description                                               |
-| ------------------ | --------------------------------------------------------- |
-| npm install        | install every dependency required for this project        |
-| npm run build      | build a bundle of _owl_ in the _/dist/_ folder            |
-| npm run build:es5  | build a bundle of _owl_ in the _/dist/_ folder (ES5 code) |
-| npm run minify     | minify the prebuilt owl.js file                           |
-| npm run test       | run all tests                                             |
-| npm run test:watch | run all tests, and keep a watcher                         |
-
-## Documentation
-
-
-The complete documentation can be found [here](doc/readme.md). The most important sections are:
-
-- [Quick Start](doc/quick_start.md)
-- [Tutorial](doc/tutorial.md)
-- [Component](doc/component.md)
-- [QWeb](doc/qweb.md)
-
-# Examples
-
-Here is a minimal Hello World example:
+Here is a short example to illustrate interactive widgets:
 
 ```javascript
-class HelloWorld extends owl.core.Component {
-  inlineTemplate = `<div>Hello <t t-esc="props.name"/></div>`;
-}
-
-const env = {
-  qweb: new owl.core.QWeb()
-};
-
-const hello = new HelloWorld(env, { name: "World" });
-hello.mount(document.body);
-```
-
-The next example show interactive widgets, and how widget
-composition works:
-
-```javascript
-class ClickCounter extends owl.core.Component {
+class ClickCounter extends owl.Component {
   inlineTemplate = `
-    <div>
-      <button t-on-click="increment">Click Me! [<t t-esc="state.value"/>]</button>
-    </div>`;
+    <button t-on-click="increment">
+      Click Me! [<t t-esc="state.value"/>]
+    </button>`;
 
   constructor(parent, props) {
     super(parent, props);
@@ -90,24 +37,37 @@ class ClickCounter extends owl.core.Component {
   }
 }
 
-class App extends owl.core.Component {
-  inlineTemplate = `
-    <div>
-        <t t-widget="ClickCounter"/>
-    </div>`;
-
-  widgets = { ClickCounter };
-}
-
-const env = {
-  qweb: new owl.core.QWeb()
-};
-
-const app = new App(env);
-app.mount(document.body);
+const qweb = new owl.QWeb();
+const counter = new ClickCounter({qweb});
+counter.mount(document.body);
 ```
 
-More interesting examples can be found on the playground application: [https://odoo.github.io/owl/](https://odoo.github.io/owl/).
+More interesting examples can be found on the [playground](https://odoo.github.io/owl/) application.
+
+## Installing/Building
+
+If you want to use a simple `<script>` tag, the last release can be downloaded here:
+
+- [owl-0.7.0.js](https://odoo.github.io/owl/releases/owl-0.7.0.js)
+- [owl-0.7.0.min.js](https://odoo.github.io/owl/releases/owl-0.7.0.min.js)
+
+Some npm scripts are available:
+
+| Command              | Description                                        |
+| -------------------- | -------------------------------------------------- |
+| `npm install`        | install every dependency required for this project |
+| `npm run build`      | build a bundle of _owl_ in the _/dist/_ folder     |
+| `npm run minify`     | minify the prebuilt owl.js file                    |
+| `npm run test`       | run all tests                                      |
+| `npm run test:watch` | run all tests, and keep a watcher                  |
+
+## Documentation
+
+The complete documentation can be found [here](doc/readme.md). The most important sections are:
+
+- [Quick Start](doc/quick_start.md)
+- [Component](doc/component.md)
+- [Store](doc/store.md)
 
 ## License
 
diff --git a/doc/comparison.md b/doc/comparison.md
new file mode 100644
index 00000000..7e5e2d02
--- /dev/null
+++ b/doc/comparison.md
@@ -0,0 +1,194 @@
+# Comparison with Vue/React
+
+OWL, React and Vue have the same main feature: they allow developers to build
+declarative user interfaces. To do that, all these frameworks uses a virtual dom. However, there are still obviously many differences.
+
+In this page, we try to highlight some of these differences. Obviously, some
+effort was done to be fair. However, if you disagree with some of the points
+discussed, feel free to open an issue/submit a PR to correct this text.
+
+- [Size](#size)
+- [Tooling/Build Step](#toolingbuild-step)
+- [Templating](#templating)
+- [Asynchronous rendering](#asynchronous-rendering)
+- [Reactiveness](#reactiveness)
+- [State Management](#state-management)
+
+### Size
+
+OWL is intended to be small and to work at a slightly lower level of abstraction
+than React and Vue. Also, jQuery is not the same kind of framework, but it is interesting to compare.
+
+| Framework                | Size (minified) | Size (minified, gzipped) |
+| ------------------------ | --------------- | ------------------------ |
+| OWL                      | 32kb            | 11kb                     |
+| Vue + VueX               |                 | 30kb                     |
+| React + ReactDOM + Redux |                 | 40kb                     |
+| jQuery                   | 86kb            | 30kb                     |
+
+### Tooling/Build step
+
+OWL is designed to be easy to use in a standalone way. For various reasons,
+Odoo does not want to rely on standard web tools (such as webpack), and OWL can
+be used by simply adding a script tag to a page.
+
+```html
+<script src="owl.min.js" />
+```
+
+In comparison, React encourages using JSX,
+which necessitate a build step, and most Vue applications uses single file
+components, which also necessitate a build step.
+
+On the flipside, external tooling may make it harder to use in some case, but it
+also brings a lot of benefits. And React/Vue have both a large ecosystem.
+
+### Templating
+
+OWL uses its own QWeb engine, which compiles templates on the
+frontend, as they are needed. This is extremely convenient for our use case, in
+particular because templates are described in XML files, and can be modified by
+XPaths. Since Odoo is at its heart a modular application, this is an important
+feature for us.
+
+```xml
+<div>
+  <button t-on-click="increment">Click Me! [<t t-esc="state.value"/>]</button>
+</div>
+```
+
+Vue is actually kind of similar. Its template language is kind of close to QWeb,
+with the `v` replaced by the `t`. However, it is also more fully featured. For
+example, Vue templates have slots, or event modifiers. A large difference is that
+most Vue applications will need to be built ahead of time, to compile the templates
+into javascript functions. Note that Vue has a separate build which includes the
+template compiler.
+
+In contrast, most React applications do not use a templating language, but write
+some JSX code, which is precompiled into plain JavaScript by a build step.
+
+```jsx
+class Clock extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.props.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+```
+
+This has the advantage of having the full power of Javascript, but is less
+structured than a template language. Note that the tooling is quite impressive:
+there is a syntax highlighter for jsx here on github!
+
+### Asynchronous rendering
+
+This is actually a big difference between OWL and React/Vue: components in OWL
+are totally asynchronous. They have two asynchronous hooks in their lifecycle:
+
+- `willStart` (before the widget starts rendering)
+- `willUpdateProps` (before new props are set)
+
+Both these methods can be implemented and return a promise. The rendering will
+then wait for these promises to be completed before patching the DOM. This is
+useful for some use cases: for example, a widget may want to fetch an external
+library (a calendar widget may need a specialized calendar rendering library),
+in its willStart hook.
+
+```javascript
+class MyCalendarWidget extends owl.Component {
+    ...
+
+    willStart() {
+        return utils.lazyLoad('static/libs/fullcalendar/fullcalendar.js');
+    }
+    ...
+}
+```
+
+This may be dangerous (to stop the rendering waiting for the network), but it is
+extremely powerful as well, as demonstrated by the Odoo Web Client.
+
+Lazy loading static libraries can obviously be done with React/Vue, but it is
+more convoluted.
+
+### Reactiveness
+
+React has a simple model: whenever the state changes, it is
+replaced with a new state (via the setState method). Then, the DOM is patched.
+This is simple, efficient, and a little bit awkward to write.
+
+Vue is a little bit different: it replace magically the properties in the state
+by getters/setters. With that, it can notify components whenever the state that
+they read was changed.
+
+Owl is closer to vue: it also tracks magically the state properties, but it does
+only increment a counter whenever it changes (and a _deep_ counter for each of
+its parents). This assumes that the state is actually a tree.
+
+### State Management
+
+Managing the state of an application is a tricky issue. Many solutions have
+been proposed these last few years. It also depends on the kind of application we
+are talking about. A small application may not need much more than a simple
+object to contain its state.
+
+However, there are some common solutions for React and Vue: redux and vuex.
+Both of them are a centralized store that own the state, and they dictate how
+the state can be mutated.
+
+**Redux**
+
+In Redux, the state is mutated by reducers. Reducers are functions
+that modify the state by returning a different object:
+
+```javascript
+  ...
+  switch (action.type) {
+    case ADD_TODO: {
+      const { id, content } = action.payload;
+      return {
+        ...state,
+        allIds: [...state.allIds, id],
+        byIds: {
+          ...state.byIds,
+          [id]: {
+            content,
+            completed: false
+          }
+        }
+      };
+    }
+```
+
+This is a little bit awkward to write, but this allows the component system to
+check if a part of the state was changed. This is exactly what is done by the
+`connect` function: it create a _connected_ component, which is subscribed to
+the state and triggers a rerender if some part of the state was modified.
+
+**VueX**
+
+VueX is based on a different principle: the state is mutated through
+some special functions (the mutations), which modify the state in place:
+
+```javascript
+    function ({state}, payload) {
+        const { id, content } = payload;
+        const message = {id, content, completed: false};
+        state.messages.push(message)
+    }
+```
+
+This is simpler, but there is a little bit more happening behind the scene:
+each key from the state is silently replaced by getters and setters, and VueX
+keeps track of who get data, and retrigger a render when it was changed.
+
+**Owl**
+
+Owl store is a little bit like a mix of redux and vuex: it has mutations and
+actions, like VueX, it keeps track of the state changes, but it does not notify
+a component when the state changes.  Instead, components need to connect to the
+store like in redux, with a function that will listen to the relevant state.
diff --git a/doc/component.md b/doc/component.md
index b19f7ba3..d337e90e 100644
--- a/doc/component.md
+++ b/doc/component.md
@@ -1,5 +1,20 @@
 # Component
 
+The component system is designed to be:
+
+1. **declarative:** the user interface should be described in term of the state
+   of the application, not as a sequence of imperative steps.
+
+2. **composable:** each widget can seamlessly be created in a parent widget by
+   a simple directive in its template.
+
+3. **asynchronous rendering:** the framework will transparently wait for each
+   subwidgets to be ready before applying the rendering. It uses native promises
+   under the hood.
+
+4. **uses QWeb as a template system:** the templates are described in XML
+   and follow the QWeb specification. This is a requirement for Odoo.
+
 Components are the reusable, composable widgets. They are designed to be low
 level, to be declarative, and with asynchronous rendering.
 
diff --git a/doc/observer.md b/doc/observer.md
new file mode 100644
index 00000000..4f9a9e12
--- /dev/null
+++ b/doc/observer.md
@@ -0,0 +1,2 @@
+# Observer
+
diff --git a/doc/readme.md b/doc/readme.md
index 5c7dcaf7..85b5498d 100644
--- a/doc/readme.md
+++ b/doc/readme.md
@@ -1,17 +1,14 @@
 # Odoo Web Library Documentation
 
-Currently, this repository contains:
 
-- an implementation/extension of the QWeb template engine that outputs a virtual
-  dom (using the snabbdom library)
-- a Component class, which uses the QWeb engine as its underlying rendering
-  mechanism. The component class is designed to be declarative, with
-  asynchronous rendering. Also, it uses snabbdom as the virtual dom library.
-- some utility functions/classes
-- a Store class and a connect function, to help manage the state of an application (like react-redux)
+## Reference
 
-- [Quick Start](quick_start.md)
-- [Tutorial](tutorial.md)
 - [Component](component.md)
 - [QWeb](qweb.md)
-- [State Management](state_management.md)
+- [Store](store.md)
+- [Observer](observer.md)
+- [Virtual DOM](vdom.md)
+
+## Miscellaneous
+- [Quick Start](quick_start.md)
+- [Comparison with React/Vue](comparison.md)
diff --git a/doc/state_management.md b/doc/store.md
similarity index 100%
rename from doc/state_management.md
rename to doc/store.md
diff --git a/doc/tutorial.md b/doc/tutorial.md
deleted file mode 100644
index 90f50790..00000000
--- a/doc/tutorial.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Tutorial
-
-todo...
diff --git a/doc/vdom.md b/doc/vdom.md
new file mode 100644
index 00000000..e19d1911
--- /dev/null
+++ b/doc/vdom.md
@@ -0,0 +1,3 @@
+# VDom
+
+todo
\ No newline at end of file