From 9556696fa8baf6fe8b8fd34e9aa0371c44c400c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= <ged@odoo.com>
Date: Wed, 15 May 2019 10:55:39 +0200
Subject: [PATCH] [REF] qweb: rename loadTemplates into addTemplates

---
 doc/qweb.md              | 47 ++++++++++++++++++++++++++++++++++++++++
 extras/playground/app.js |  2 +-
 src/qweb_core.ts         | 35 +++++++++++++++---------------
 tests/qweb.test.ts       |  6 ++---
 4 files changed, 69 insertions(+), 21 deletions(-)

diff --git a/doc/qweb.md b/doc/qweb.md
index e311b9af..90ad65e0 100644
--- a/doc/qweb.md
+++ b/doc/qweb.md
@@ -3,6 +3,7 @@
 ## Content
 
 - [Overview](#overview)
+- [QWeb Engine](#qweb-engine)
 - [QWeb Specification](#qweb-specification)
     - [Static html nodes](#static-html-nodes)
     - [`t-esc` directive](#t-esc-directive)
@@ -40,8 +41,54 @@ necessary for the component system. In addition, it has a few extra directives
 (see [OWL Specific Extensions](#owlspecificextensions))
 
 
+## QWeb Engine
+
+This section is about the javascript code that implements the `QWeb` specification.
+Owl exports a `QWeb` class in `owl.QWeb`.  To use it, it just needs to be
+instantiated:
+
+```js
+const qweb = new owl.QWeb();
+```
+
+It's API is quite simple:
+
+- **`constructor(data)`**: constructor. Takes an optional string to add initial
+  templates (see `addTemplates` for more information on format of the string).
+
+  ```js
+  const qweb = new owl.QWeb(TEMPLATES);
+  ```
+
+- **`addTemplate(name, xmlStr)`**: add a specific template.
+
+  ```js
+  qweb.addTemplate('mytemplate', '<div>hello</div>');
+  ```
+
+- **`addTemplates(xmlStr)`**: add a list of templates (identified by `t-name`
+  attribute).
+
+  ```js
+  const TEMPLATES = `
+    <templates>
+      <div t-name="App" class="main">main</div>
+      <div t-name="OtherWidget">other widget</div>
+    </templates>`;
+  qweb.addTemplates(TEMPLATES);
+  ```
+
+- **`render(name, context, extra)`**: renders a template.  This returns a `vnode`,
+  which is a virtual representation of the DOM (see [vdom doc](vdom.md)).
+
+  ```js
+  const vnode = qweb.render('App', widget);
+  ```
+
 ## QWeb Specification
 
+We define in this section the specification of how `QWeb` templates should be
+rendered.
 
 ### Static html nodes
 
diff --git a/extras/playground/app.js b/extras/playground/app.js
index c9af74bb..6ded0bb9 100644
--- a/extras/playground/app.js
+++ b/extras/playground/app.js
@@ -174,7 +174,7 @@ class App extends owl.Component {
     var error = false;
     const sanitizedXML = this.state.xml.replace(/<!--[\s\S]*?-->/g, "");
     try {
-      qweb.loadTemplates(sanitizedXML);
+      qweb.addTemplates(sanitizedXML);
     } catch (e) {
       error = e;
     }
diff --git a/src/qweb_core.ts b/src/qweb_core.ts
index e63d79a4..d33f5925 100644
--- a/src/qweb_core.ts
+++ b/src/qweb_core.ts
@@ -134,7 +134,7 @@ export class QWeb {
 
   constructor(data?: string) {
     if (data) {
-      this.loadTemplates(data);
+      this.addTemplates(data);
     }
     this.addTemplate("default", "<div></div>");
   }
@@ -167,6 +167,23 @@ export class QWeb {
     this._addTemplate(name, <Element>doc.firstChild);
   }
 
+  /**
+   * Load templates from a xml (as a string).  This will look up for the first
+   * <templates> tag, and will consider each child of this as a template, with
+   * the name given by the t-name attribute.
+   */
+  addTemplates(xmlstr: string) {
+    const doc = parseXML(xmlstr);
+    const templates = doc.getElementsByTagName("templates")[0];
+    if (!templates) {
+      return;
+    }
+    for (let elem of <any>templates.children) {
+      const name = elem.getAttribute("t-name");
+      this._addTemplate(name, elem);
+    }
+  }
+
   _addTemplate(name: string, elem: Element) {
     if (name in this.templates) {
       throw new Error(`Template ${name} already defined`);
@@ -224,22 +241,6 @@ export class QWeb {
       }
     }
   }
-  /**
-   * Load templates from a xml (as a string).  This will look up for the first
-   * <templates> tag, and will consider each child of this as a template, with
-   * the name given by the t-name attribute.
-   */
-  loadTemplates(xmlstr: string) {
-    const doc = parseXML(xmlstr);
-    const templates = doc.getElementsByTagName("templates")[0];
-    if (!templates) {
-      return;
-    }
-    for (let elem of <any>templates.children) {
-      const name = elem.getAttribute("t-name");
-      this._addTemplate(name, elem);
-    }
-  }
   /**
    * Render a template
    *
diff --git a/tests/qweb.test.ts b/tests/qweb.test.ts
index 19e7ecc3..3b3808a3 100644
--- a/tests/qweb.test.ts
+++ b/tests/qweb.test.ts
@@ -100,7 +100,7 @@ describe("error handling", () => {
 
   test("loadTemplates throw if parser error", () => {
     expect(() => {
-      qweb.loadTemplates("<templates><abc>></templates>");
+      qweb.addTemplates("<templates><abc>></templates>");
     }).toThrow("Invalid XML in template");
   });
 
@@ -1016,14 +1016,14 @@ describe("loading templates", () => {
 
         <ul t-name="main"><t t-call="items"/></ul>
       </templates>`;
-    qweb.loadTemplates(data);
+    qweb.addTemplates(data);
     const result = renderToString(qweb, "main");
     expect(result).toBe("<ul><li>ok</li><li>foo</li></ul>");
   });
 
   test("does not crash if string does not have templates", () => {
     const data = "";
-    qweb.loadTemplates(data);
+    qweb.addTemplates(data);
     expect(Object.keys(qweb.templates)).toEqual(["default"]);
   });
 });