diff --git a/README.md b/README.md index 6cbfb598..680655c1 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

🦉 OWL: the Odoo Web Library 🦉

+

🦉 OWL Framework 🦉

_Class based components with hooks, reactive state and concurrent mode_ @@ -11,11 +11,11 @@ simple and consistent way. Owl's main features are: - a declarative component system, - a reactivity system based on hooks, -- a store implementation (for state management), -- a small frontend router +- concurrent mode by default, +- a store and a frontend router Owl components are defined with ES6 classes, they use QWeb templates, an -underlying virtual dom, integrates beautifully with hooks, and the rendering is +underlying virtual DOM, integrates beautifully with hooks, and the rendering is asynchronous. **Try it online!** An online playground is available at @@ -29,12 +29,12 @@ Owl is currently stable. Possible future changes are explained in the ## Why Owl? Why did Odoo decide to make Yet Another Framework? This is really a question -that deserves [a long answer](doc/why_owl.md). But in short, we believe that +that deserves [a long answer](doc/miscellaneous/why_owl.md). But in short, we believe that while the current state of the art frameworks are excellent, they are not optimized for our use case, and there is still room for something else. If you are interested in a comparison with React or Vue, you will -find some more additional information [here](doc/comparison.md). +find some more additional information [here](doc/miscellaneous/comparison.md). ## Example @@ -92,7 +92,8 @@ requirements are common and code needs to be maintained by large teams. Owl is not designed to be fast nor small (even though it is quite good on those two topics). It is a no nonsense framework to build applications. There is only -one way to define components (with classes). +one way to define components (with classes). There is no black magic. It just +works. ## Documentation @@ -101,19 +102,18 @@ A complete documentation for Owl can be found here: - [Main documentation page](doc/readme.md). -The most important sections are: +Some of the most important pages are: - [Tutorial: TodoList application](doc/learning/tutorial_todoapp.md) +- [How to start an Owl project](doc/learning/quick_start.md) - [QWeb templating language](doc/reference/qweb_templating_language.md) - [Component](doc/reference/component.md) - [Hooks](doc/reference/hooks.md) -Found an issue in the documentation? A broken link? Some outdated information? -Submit a PR! -## Installing/Building +## Installing Owl -Owl can be installed with the following command: +Owl is available on `npm` and can be installed with the following command: ``` npm install @odoo/owl @@ -124,146 +124,6 @@ If you want to use a simple ` + Hello Owl + + - -
- - + ``` -In `app.css`: +And `app.js` should look like this: -```css -button { - color: darkred; - font-size: 30px; - width: 220px; +```js +const { Component } = owl; +const { xml } = owl.tags; +const { whenReady } = owl.utils; + +// Owl Components +class App extends Component { + static template = xml`
Hello Owl
`; +} + +// Setup code +function setup() { + const app = new App(); + app.mount(document.body); +} + +whenReady(setup); +``` + +Now, simply loading this html file in a browser should display a welcome message. +This setup is not fancy, but it is extremely simple. There are no tooling at +all required. It can be slightly optimized by using the minified build of Owl. + + +## With a static server + +The previous setup has a big disadvantage: the application code is located in a +single file. Obviously, we could split it in several files and add multiple +` + + + + +``` + +Not that the `main.js` script tag has the `type="module"` attribute. This means +that the browser will parse the script as a module, and load all its dependencies. + +Here is the content of `app.js` and `main.js`: + +```js +// app.js ---------------------------------------------------------------------- +const { Component } = owl; +const { xml } = owl.tags; + +export class App extends Component { + static template = xml`
Hello Owl
`; +} + + +// main.js --------------------------------------------------------------------- +import { App } from "./app.js"; + +function setup() { + const app = new App(); + app.mount(document.body); +} + +owl.utils.whenReady(setup); +``` + +The `main.js` file import the `app.js` file. Note that the import statement has +a `.js` suffix, which is important. Most text editor can understand this syntax +and will provide autocompletion. + +Now, to execute this code, we need to serve the `src` folder statically. A low +tech way to do that is to use for example the python `SimpleHTTPServer` feature: + +``` +$ cd src +$ python -m SimpleHTTPServer 8022 # now content is available at localhost:8022 +``` + +Another more "javascripty" way to do it is to create a `npm` application. To do +that, we can add the following `package.json` file at the root of the project: + +```json +{ + "name": "hello_owl", + "version": "0.1.0", + "description": "Starting Owl app", + "main": "src/index.html", + "scripts": { + "serve": "serve src" + }, + "author": "John", + "license": "ISC", + "devDependencies": { + "serve": "^11.3.0" + } } ``` -Also, let's not forget to add a release of OWL (`owl-X.Y.Z.js`) +We can now install the `serve` tool with the command `npm install`, and then, +start a static server with the simple `npm run serve` command. -### XML -In `templates.xml`: +## Standard Javascript project -```xml - - - +The previous setup works, and is certainly good for some usecases, including +quick prototyping. However, it lacks some useful features, such as livereload, +a test suite, or bundling the code in a single file. + +Each of these features, and many others, can be done in many different ways. +Since it is really not trivial to configure such a project, we provide here an +example that can be used as a starting point. + + +Our standard Owl project has the following file structure: + +``` +hello_owl/ + public/ + index.html + src/ + components/ + App.js + main.js + tests/ + components/ + App.test.js + helpers.js + .gitignore + package.json + webpack.config.js ``` -### JS +This project as a `public` folder, meant to contain all static assets, such as +images and styles. The `src` folder has the javascript source code, and finally, +`tests` contains the test suite. -To build an application (or a sub-part of an application), we need two things: +Here is the content of `index.html`: -- an environment: it is the global context in which we are working. It needs to - contain a QWeb instance (preloaded with templates), and anything else that we - need. In practice, it could be used to contain some user session information, some - configuration keys (for example, isMobile = true/false if we are in mobile mode). +```html + + + + Hello Owl + + + +``` -- a description of the user interface: there should be a root component, which can - have sub components +Note that there are no `