170 lines
6.4 KiB
ReStructuredText
170 lines
6.4 KiB
ReStructuredText
|
|
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 <#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:
|
|
|
|
.. code-block::
|
|
|
|
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:
|
|
|
|
|
|
#.
|
|
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.
|
|
|
|
#.
|
|
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.
|