Introduction to the Odoo JavaScript framework

1. Introduction

Almost every app you create in Odoo will need some JavaScript to do what you like and the options with the JavaScript framework are almost unlimited. You can override existing features, expand features or create your own new view types for example!

This tutorial is the first in a series of tutorials that will cover many aspects of the Odoo JavaScript framework. It is interesting that as the Odoo ecosystem is getting bigger, it is still difficult to find some quality information on the Javascript part of Odoo but there are some reasons for this:

• One could say that the JS framework is not modern, it is a custom kind of low level framework (note: it is changing quickly with Owl on the way for V14!),
• The official documentation is not as good as it should be and is very limited,
• For many usecases JavaScript is not the correct answer. Many tasks can be done in a better and cheaper way in XML or Python,
• The JavaScript framework is moving really fast causing quite some changes in every Odoo version. Most JavaScript customizations will most likely require some non-trivial amount of work when migrating to a newer Odoo version.

Nevertheless the JS framework is quite often still the only solution to problems. As the JS framework is a large subject each tutorial will focus on one task. In this series of tutorials you will learn about quite some features from the JS framework:

• Introduction to the framework and static files
• Introduction to assets management, JS classes, client actions and templates
• Introduction to classes and widgets
• Introduction to RPC calls with widgets

For this tutorial we will start with an introduction to the framework and we will create a simple Hello World application in JS. The goal is to display a message in the console when the Odoo web client is loaded.

2. A short overview of the Odoo ecosystem

Broadly speaking the JS framework can be split up into a few parts:

• The web client (located in the addon "web"), which displays the Odoo backend user interface to authenticated users.
• The website (located in the addon "website"), which can be understood as the public part of Odoo: everything that can be seen in the Odoo website.
• The point of sale (located in the addon "pos"): it is a JS application which shares some code with web, but is otherwise mostly separate. It is mostly targeted at specific devices, such as a tablet, used in an actual point of sale and is built with Backbone.js.
• Some other, smaller, projects.

All of these addons are extended by many other addons. For example, the "web_gantt" module adds a Gant view to the website and the addon "website_sale" implements the Odoo e-commerce application.

Each of these parts of Odoo talk to the same server, written in Python, with a postgreSQL database. Speaking of the database, Odoo has made a very interesting architectural choice: many templates are stored in the database as an XML document. This is very powerful, since this allows any installed addon to be modified with a simple xpath expression. This is certainly the most important reason that the Odoo web client UI is so dynamic and extensible.
This series of tutorial will focus mostly on the web client, but many of the topics discussed will also apply to the website or the point of sale JS code.

3. Creating an empty module

Enough talked, lets start coding! We'll need an own module to add our files and code into. It is a good practice to separate custom addons in a different folder, so it is easier to maintain. Let us start by creating a "tutorial_add_javascript" folder with two files in our custom addons folder. Create a new "__init__.py" and "__manifest__.py" file in this new folder.
This is the minimal amount of files required by Odoo. The "__manifest__.py" should contain a description of how the module is structured, and __init__.py makes it a python module. For now we can leave the "__init__.py" file empty. Open "__manifest__.py" and add the following values:

                    {    'name': "tutorial_add_javascript",    'summary': """        Example Hello World application""",    'description': """        This is an example application to learn the basics of the JS framework.    """,    'author': "An Awesome Developer",    'version': '13.0.0.1',    'depends': ['base', 'web'],    'application': True,}                                    

Note that we set the application flag to true, to make it a real application, not just a technical addon. Another interesting fact is that we added web to its list of dependencies: this means that installing "tutorial_add_javascript" will force Odoo to install the web client as well. That's is, we now have a working addon! It does nothing, but still, it is there! If your Odoo server is properly configured/started (meaning that the "tutorial_add_javascript" parent folder is available on the addons path), then the app can now be installed. Notice that you'll need to restart your Odoo instance and update the apps list before it shows up.

4. Adding static files

So, what's next? We now have a module that does nothing so let's add our very first JavaScript file! The Odoo server has a special folder which is served to the outside world: "static". All files that are required for the web browser should live in static. Note that there is a convention in Odoo to separate the files in an hierarchy looking like this:

                    your_module_name/  static/    src/      js/        some_file.js        some_other_file.js      css/        some_file.css      xml/        other_file.xml        ...                                    

Create the folder "static" and in this folder add "src" then "js" and create a new file named "hello_world.js" in the "js" folder. Your module should now have this structure:

                    tutorial_add_javascript/  static/    src/      js/        hello_world.js                                    

Open the "hello_world.js" file and add a simple console.log in it:

                    console.log('Hello Javascript')                                    

If you now update/install the module you can open the following URL:
http://localhost:8069/tutorial_add_javascript/static/src/js/hello_world.js
If all goes well, you should see your JavaScript file in the browser! This means that it is properly served by Odoo. Of course, it is cheating. The JavaScript code is not currently being executed. To do that, we need to actually load our file with the Odoo assets.

5. Adding the JS to the assets

The next step is to tell Odoo that our "hello_world.js" file should be loaded along with all the other JavaScript files in the web client. To do this we have to add our JavaScript file to the assets. Create a new directory "views" under "your_module_name/" and in this directory create a new file named "assets.xml". Have a look at this code first, I'll explain it afterwards:

                    <?xml version="1.0" encoding="utf-8"?><odoo>    <template id="assets_backend" name="tutorial_add_javascript assets" inherit_id="web.assets_backend">        <xpath expr="." position="inside">            <script type="text/javascript" src="/tutorial_add_javascript/static/src/js/hello_world.js"></script>        </xpath>    </template></odoo>                                    

So, does this code make sense to you? This will tell Odoo that we want to inherit the XML template "assets_backend" - which contains all backend JavaScript resources - and that we want to add some file(s) to the assets. The file is of the type "text/javascript" and is in our module at the path "/tutorial_add_javascript/static/src/js/hello_world.js". This is enough for the Odoo framework to know the location of our custom JavaScript file and to add it to the assets. We'll go into more details about this in the next tutorial but for now this is enough.

The next step is to ask the Odoo server to read this XML file so that this XML gets loaded into Odoo too. You can do this by adding the XML file its location in the "__manifest__.py" file in Odoo like this:

                     'data': [      'views/assets.xml',  ],                                    

Now that we've modified the "__manifest__.py" file we need to restart the server and update our "tutorial_add_javascript" module so that Odoo rereads the file. Finally, open Odoo in your browser and open the JavaScript console (usually by pressing F12 or ctrl+shift+i) or by using the developer tools menu. You should now see the welcome message coming from your JavaScript file:

6. Conclusion

In this tutorial you've learned where Odoo locates its static files and how to add custom JavaScript files to Odoo. This tutorial helps you understand the basics of the JavaScript framework and how to load files. This is enough to be able to do some kind of customizations but it clearly doesn't interact with the Odoo web client its JavaScript code though. In the following tutorial we will explain how to create your own JavaScript functions and how to create client actions.