Creating a tour in Odoo

In this tutorial I will teach you how to create a tour in Odoo. You will learn how to create a tour step by step in JavaScript and how to guide your users through your custom development.
In this tutorial I will create a new tour throughout the contacts app in order to guide a new user through this module.
Updated tutorial available on Oocademy

1. Creating a new module

Let us create a new module to start. You can either manually create a module or create one with the scaffold command from Odoo. Now that you’ve created your module you should add the dependency to the module where you want to create a tour. In this tutorial I will create a tour that guides the user through the contacts app.

2. Creating the tour

The first thing to do in order to create a tour is to create a JavaScript file. In Odoo you should place all JavaScript code under /static/src/js so create these folders first. Create these new folders and then create a new JavaScript file named ‘tour.js’. You should now have this:
JavaScript folder structure
Now open up your JS file and define a new function. In this function you should require ‘web.core’ and ‘web.core.tour’ and include ‘core._t’ in order to manage translations later on. Your code should now look like this:

2.1. Registering the tour

You now have the basic JavaScript structure! It is time to register a tour and add steps to this tour. Just have a look at this code for a minute:

Does this make any sense to you? Let us walk over it line by line. The tour.register function will tell Odoo that you want to add a new tour to Odoo. ‘example_tour’ is the technical name of the tour, but be sure that it is unique! The next line shows “url” which tells Odoo on which page the tour should start (in this tutorial from the home screen). ‘tour.STEPS.MENU_MORE’ is built in in Odoo to know where/when/how the tour should be loaded.

Finally, you’ll see the options ‘trigger’, ‘content’ and ‘position’. The ‘trigger’ will tell Odoo when exactly that you would want to trigger the tour step. In this example our tour would start on the main Odoo screen and will show a little icon under the contacts app. If you would install the app with this piece of code you would get the following result:
Tour home screen

The ‘content’ will show a text dialog to the enduser and the ‘position’ tells Odoo where exactly to show this text (top, right, left or bottom).

2.2 Choosing your tour steps

A tour should contain multiple steps and a logical flow though. Take a minute to figure out the steps you would like your users to follow in your tour.
In this tutorial I will add the following steps:
– The moment the user clicks on ‘Contacts’ and when the Kanban view opens we’ll show a hint to click on the ‘Create’ button.
– After clicking on the ‘Create’ button we’ll show a hint to fill in the name of the contact.
– When the name of the contact is filled in we’ll show a hint to click on ‘Save’.

2.3 Creating all tour steps

So, how do we code all the steps? Just have a look at the full code for a minute:

If you would run this code it would do exactly the points that I’ve subscribed. The trigger tells when the next step should go off. For example with the trigger ‘.o-kanban-button-new’ it will show a blinking icon next to the ‘Create’ button. Have you noticed the ‘extra_trigger’ option and the ‘run’ option in the third step? By setting an ‘extra_trigger’ Odoo knows when the trigger should go off (in this case after the user clicked on create so he is in edit mode). The ‘run’ option will tell Odoo to automatically fill in text in the field that we’ve put a trigger on, in this example the field ‘name’. If we would run (play) the tour from the Odoo interface it would now automatically fill in the name of the new contact.
That is all! You’ve now got the JavaScript code to create a tour.

3. Including the JavaScript

Finally you should now include your JavaScript file so that it gets compiled in Odoo too. Create a new xml file named ‘assets.xml’ in a new folder ‘views’:
Assets folder structure

Open up the XML file, inherit the assets template and insert the tour.js file into the assets. Your code should look like this:

Now open up your (or if you’re in V10) and add the ‘assets.xml’ file to the data key so that it gets loaded too:

That’s it, you’ve created your very first tour! If you save this code and run the module you will get the following behaviour:

4. Translating the tour

Now what if you have Odoo users that speak different languages? Luckily you can also translate tours to any language. Activate developer mode and then go to ‘Settings’ > ‘Translations’ > ‘Export translation’. You’ll now see a dialog from which you can choose the target language and where you can select your app. Select your target language, choose the file format ‘PO File’ and choose your app. Finally click on ‘Export’:
Export translations

Next create a new folder named ‘i18n’ and add your downloaded file to this folder:
Translation folder structure
Finally, open up the PO file and translate all the terms:
Translation example
When you now update your module and switch to another language you’ll see that the tour is translated.

5. Conclusion

Because of the built-in framework from Odoo it is very easy to create a tour for users. With this tour you can guide a new user through your own custom development in a matter of minutes and with personalised text. Creating tours is really quick and just takes a few lines of code.
Do you want to try the demo code and see the source code of this tutorial? You can view it on my Github account.
Has this tutorial helped you, do you have any feedback or questions? Post away!


Tutorial sponsored by Oocademy