wip

content/developer/reference/javascript/getting_started.rst

@@ -0,0 +1,169 @@
+
+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.