NextERP/owl
2
0
Fork 0
mirror of https://github.com/odoo/owl.git synced 2025-10-06 19:59:41 +07:00
Code Issues Packages Projects Releases Wiki Activity

[DOC] doc: update a lot of the documentation

Browse Source
This commit is contained in:
Géry Debongnie
2019-04-23 15:26:00 +02:00
parent 79b97c6d24
commit 1a778922af
8 changed files with 266 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+44 -84
View File
@@ -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
doc/comparison.md
+194
View File
@@ -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.
doc/component.md
+15
View File
@@ -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.
doc/observer.md
+2
View File
@@ -0,0 +1,2 @@
# Observer
doc/readme.md
+8 -11
View File
@@ -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)
doc/state_management.md → doc/store.md
View File
doc/tutorial.md
-3
View File
@@ -1,3 +0,0 @@
# Tutorial
todo...
doc/vdom.md
+3
View File
@@ -0,0 +1,3 @@
# VDom
todo