[DOC] doc: rewrite component/quick start documentation

2025-10-06 19:59:41 +07:00 · 2019-04-24 11:54:26 +02:00
parent 379cd2a90f
commit d509373228
7 changed files with 299 additions and 101 deletions
@@ -1,11 +1,67 @@
-# Quick Start
+# 🦉 Quick Start 🦉
+
+## Static server
+
+Let us assume that we have a static server running somewhere. We could then
+simply add an html page with a few extra files.
+
+### HTML and CSS
+
+In a file `index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>My OWL App</title>
+    <link href="app.css" rel="stylesheet" />
+    <script src="owl-X.Y.Z.js"></script>
+  </head>
+  <body>
+    <div id="main"></div>
+    <script src="app.js" type="module"></script>
+  </body>
+</html>
+```
+
+In `app.css`:
+
+```css
+button {
+  color: darkred;
+  font-size: 30px;
+  width: 220px;
+}
+```
+
+Also, let's not forget to add a release of OWL (`owl-X.Y.Z.js`)
+
+### XML
+
+In `templates.xml`:
+
+```xml
+<templates>
+   <button t-name="clickcounter" t-on-click="increment">
+      Click Me! [<t t-esc="state.value"/>]
+    </button>
+</templates>
+```
+
+### JS

 To build an application (or a sub-part of an application), we need two things:

- an environment
- a root widget
+- 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 context some user session information, some
+  configuration keys (for example, isMobile = true/false if we are in mobile mode).

-Here are a few steps that may be useful to get started:
+- a description of the user interface: there should be a root widget, which can
+  have sub widgets
+
+Here are a few steps that we may take to get started:

 - get the templates
 - create a qweb engine, with the templates
@@ -13,49 +69,33 @@ Here are a few steps that may be useful to get started:
 - create an instance of the root widget
 - mount the root widget to a DOM element

-## Simple example
-
-In a oversimplified example, here is what it could look like:
+Let us now add the javascript to make it work, in `app.js`:

 ```javascript
-const templates = await loadTemplates();
+class ClickCounter extends owl.Component {
+  constructor() {
+    super(...arguments);
+    this.template = "clickcounter";
+    this.state = { value: 0 };
+  }

-const qweb = new QWeb();
-qweb.loadTemplates(templates);
+  increment() {
+    this.state.value++;
+  }
+}

-const env = {
-  qweb: qweb
-};
+//------------------------------------------------------------------------------
+// Application initialization
+//------------------------------------------------------------------------------
+async function start() {
+  const templates = await owl.utils.loadTemplates("templates.xml");
+  const env = {
+    qweb: new owl.QWeb(templates)
+  };
+  const counter = new ClickCounter(env);
+  const target = document.getElementById("main");
+  await counter.mount(target);
+}

-const root = new RootWidget(env, { initialState: 17 });
-
-const target = document.getElementById("app");
-root.mount(target);
-```
-
-## Managing state
-
-The environment is propagated to each subchildren. So, it is convenient to use
-to give a reference to some global object. This is potentially very useful
-in a redux-like architecture:
-
-```javascript
-...
-
-const store = new Store();
-
-const env = {
-    qweb: qweb,
-    store: store,
-};
-
-const state = store.getState()
-const root = new RootWidget(env, state);
-
-store.on('state_change', nextState => {
-    root.updateProps(nextState);
-});
-
-const target = document.getElementById('app');
-root.mount(target);
+start();
 ```