[REF] utils: rename loadTemplates into loadFile

closes #351

doc/quick_start.md

@@ -87,7 +87,7 @@ class ClickCounter extends owl.Component {
 // Application initialization
 //------------------------------------------------------------------------------
 async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
+  const templates = await owl.utils.loadFile("templates.xml");
   const env = {
     qweb: new owl.QWeb(templates)
   };

doc/readme.md

@@ -39,7 +39,8 @@ owl
         debounce
         escape
         loadJS
-        loadTemplates
+        loadFile
+        shallowEqual
         whenReady
 ```
 

doc/utils.md

@@ -7,7 +7,7 @@ functions are all available in the `owl.utils` namespace.
 
 - [`whenReady`](#whenready): executing code when DOM is ready
 - [`loadJS`](#loadjs): loading script files
-- [`loadTemplates`](#loadtemplates): loading xml files
+- [`loadFile`](#loadfile): loading a file (useful for templates)
 - [`escape`](#escape): sanitizing strings
 - [`debounce`](#debounce): limiting rate of function calls
 - [`shallowEqual`](#shallowequal): shallow object comparison
@@ -20,7 +20,7 @@ not ready yet, resolved directly otherwise). If called with a callback as
 argument, it executes it as soon as the DOM ready (or directly).
 
 ```js
-Promise.all([loadTemplates(), owl.utils.whenReady()]).then(function([templates]) {
+Promise.all([loadFile('templates.xml'), owl.utils.whenReady()]).then(function([templates]) {
   const qweb = new owl.QWeb(templates);
   const app = new App({ qweb });
   app.mount(document.body);
@@ -39,11 +39,12 @@ owl.utils.whenReady(function() {
 
 ## `loadJS`
 
-`loadJS` takes a url (string) for a javascript resource, and loads it. It returns
+`loadJS` takes a url (string) for a javascript resource, and loads it (by adding
-a promise, so the caller can properly reacts when it is ready. Also, it is smart:
+a script tag in the document head). It returns a promise, so the caller can
-it maintains a list of urls previously loaded (or currently being loaded), and
+properly reacts when it is ready. Also, it is smart: it maintains a list of urls
-prevent doing twice the work.
+previously loaded (or currently being loaded), and prevent doing twice the work.
 
+For example, it is useful for lazy loading external libraries:
 ```js
 class MyComponent extends owl.Component {
   willStart() {
@@ -52,20 +53,23 @@ class MyComponent extends owl.Component {
 }
 ```
 
-## `loadTemplates`
+## `loadFile`
 
-`loadTemplates` is a helper function to fetch a template file.  It simply
+`loadFile` is a helper function to fetch a file.  It simply
-performs a `GET` request and return the resulting string in a promise. For
+performs a `GET` request and returns the resulting string in a promise. The
-example:
+initial usecase for this function is to load a template file. For example:
 
 ```js
 async function makeEnv() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
+  const templates = await owl.utils.loadFile("templates.xml");
   const qweb = new owl.QWeb(templates);
   return { qweb };
 }
 ```
 
+Note that unlike `loadJS`, this function returns the content of the file as a
+string. It does not add a `script` tag or any other side effect.
+
 ## `escape`
 
 Sometimes, we need to display dynamic data (for example user-generated data) in

src/qweb/extensions.ts

@@ -219,7 +219,9 @@ QWeb.addDirective({
       `slot${slotKey}.call(this, context.__owl__.parent, Object.assign({}, extra, {parentNode: ${parentNode}, vars: extra.vars, parent: owner}));`
     );
     if (!ctx.parentNode) {
-        ctx.addLine(`Promise.all(extra.promises).then(() => utils.defineProxy(result, ${parentNode}[0]))`);
+      ctx.addLine(
+        `Promise.all(extra.promises).then(() => utils.defineProxy(result, ${parentNode}[0]))`
+      );
     }
     ctx.closeIf();
     return true;

src/utils.ts

@@ -5,7 +5,7 @@
  *
  * - whenReady
  * - loadJS
- * - loadTemplates
+ * - loadFile
  * - escape
  * - debounce
  */
@@ -43,7 +43,7 @@ export function loadJS(url: string): Promise<void> {
   return promise;
 }
 
-export async function loadTemplates(url: string): Promise<string> {
+export async function loadFile(url: string): Promise<string> {
   const result = await fetch(url);
   if (!result.ok) {
     throw new Error("Error while fetching xml templates");

tests/qweb/qweb.test.ts

@@ -79,7 +79,7 @@ describe("error handling", () => {
     expect(() => qweb.addTemplate("test", "<div/>")).toThrow("already defined");
   });
 
-  test("loadTemplates throw if parser error", () => {
+  test("addTemplates throw if parser error", () => {
     expect(() => {
       qweb.addTemplates("<templates><abc>></templates>");
     }).toThrow("Invalid XML in template");

tools/benchmarks/owl-master/app.js

@@ -144,7 +144,7 @@ class App extends owl.Component {
 // Application initialization
 //------------------------------------------------------------------------------
 async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
+  const templates = await owl.utils.loadFile("templates.xml");
   const env = {
     qweb: new owl.QWeb(templates)
   };

tools/playground/app.js

@@ -127,7 +127,7 @@ async function makeApp(js, css, xml) {
   const JS = `
 async function loadTemplates() {
   try {
-    return owl.utils.loadTemplates('app.xml');
+    return owl.utils.loadFile('app.xml');
   } catch(e) {
     console.error(\`This app requires a static server.  If you have python installed, try 'python app.py'\`);
   }
@@ -430,7 +430,7 @@ App.components = { TabbedEditor };
 async function start() {
   document.title = `${document.title} (v${owl.__info__.version})`;
   const [templates] = await Promise.all([
-    owl.utils.loadTemplates("templates.xml"),
+    owl.utils.loadFile("templates.xml"),
     owl.utils.whenReady()
   ]);
   const qweb = new owl.QWeb(templates);