documentation/wowl_markdown_doc/getting_started.md

Getting Started

The addon wowl is a self-contained web project: it has a package.json file (which makes it a proper npm application), a tsconfig.json (to configure typescript), a rollup.config.js (to configure the Rollup bundler).

It has typescript supports, xml templates detection, can run tests written in typescript, it features a livereload server, and more.

Initial setup

The first and essential task is to install the dependencies defined in the project: to do that, one need to do the following:

• have npm installed (the node package manager, which comes with node),
• open a terminal and move to the addons/wowl folder (because it is the root of the web project
• type npm install

Once this is done, the commands npm run build and npm run dev are available (see next section for more detail).

WARNING: the first and most common error is to run commands in the root of the odoo project. This will not work! The configuration files are located in the addons/wowl folder, and each command should be run inside that path!

Configure your IDE

The addon wowl is written in typescript. If you're using Sublime Text, install the TypeScript package from https://www.typescriptlang.org/ to enable type checking.

WARNING: other TypeScript packages may conflict with this one, so if it isn't working well, make sure no other is installed.

Main scripts

• npm run build: build all the assets, which includes the following steps:

  • compile the typescript src files into javascript (output: static/dist/js/src)
  • bundle the js files in a single iife bundle (output: static/dist/app.js)
  • compile the typescript tests files into javascript (output: static/dist/js/tests)
  • bundle the test files into a single iife bundle (output: static/dist/app_tests.ts)

• npm run dev: main command for developing on this project.

  • build all the assets
  • watch the filesystem and rebuild assets if necessary
  • start a livereload server (port 8070, hardcoded) to make sure that each connected browser is refreshed whenever necessary

• npm run prettier: autoformat all the typescript, scss and markdown files located in static/src, static/tests and doc.

Templates

Wowl introduces the support for a new key owl_qweb in the odoo manifest (__manifest__.py). This works like qweb (but we could not use it because we want the current web/ addon to keep working), except that it also support folders. So, if a folder such as static/src/components is added to that configuration, then each xml files inside (and inside each sub folders) will be considered a static template, that will be sent to the web client through the /wowl/templates/... route.

In short, if Wowl cannot find a template, it is likely because the owl_qweb key is not set, or incorrect.

Javascript bundles

For javascript code, Wowl has its specific setup (typescript files are converted to javascript, then bundled). The bundler (rollup) will start with the main.ts files (in src/ and in tests/) and use that as a starting point, then bundle all their dependencies.

So, they are detected automatically, but a file needs to be imported somewhere to be present in the final app.js or app_test.js.

Styles

Styles are handled in an unusual way for Odoo: there is a new style key in the manifest, that works like the owl_qweb key for templates. This key describes a list of files or folders. Then, each scss file that can be found is added in a dynamic asset bundle.

The main benefit is that we don't have to manually add all these scss files each time a new component is created.

Tests

Unit tests can be written in typescript, using the QUnit framework. As mentioned above, they should be imported in the main.ts file to be included in the test suite.

To run the test suite, one needs to open the /wowl/tests route in a browser.

Livereload

The WOWL addon provides a livereload feature: once activated, a browser tab will refresh itself automatically whenever some static assets was modified.

The npm script npm run livereload (also executed by npm run dev will start a node application that listen on a specific port. The client code will open a websocket and attempt to connect to the livereload server. If it manages to do this, you will see the message [livereload] connection established in your browser console.

Note that it works also for the unit tests.

Common issues

My new code is not executed

This commonly happens when one add a new typescript file into the source code. This file is properly compiled in JS, but then is not included in the main bundle app.js.

The reason is that the way files are bundled is by starting at main.js, then following all its dependencies (and dependencies of dependencies, ...) to include them. If your new file is not imported anywhere, it will not be included in the final bundle.

System limit for file watchers

It may happen that you encounter an error while running some commands such as npm run dev, related to file watchers:

    ENOSPC: System limit for number of file watchers reached...

This is probably caused by the livereload features, that need to watch the file system. Also, note that odoo started in dev=all mode also has its own watchers.

The only solution in that case is to increase the os limit. See https://howchoo.com/node/node-increase-file-watcher-system-limit for more info.

File in browser does not match TS code

A common situation arises when one writes some typescript code, then notices that the javascript code executed on the browser is not the same. There are two probable causes for this issue:

1. the typescript code was not built because we forgot to run the command npm run build, or because we don't have a npm run dev command running. In that case, the solution is simple: just run one of these commands.

2. there is an error in the typescript code, in which case the typescript compiler simply does not output a JS file, and the previous file simply remains. Obviously, the solution is then to fix the typescript error.