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.
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:
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:
|
1 2 3 4 5 6 7 8 |
odoo.define('example.tour', function(require) { "use strict"; var core = require('web.core'); var tour = require('web_tour.tour'); var _t = core._t; }); |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
odoo.define('example.tour', function(require) { "use strict"; var core = require('web.core'); var tour = require('web_tour.tour'); var _t = core._t; tour.register('example_tour', { url: "/web", }, [tour.STEPS.MENU_MORE, { trigger: '.o_app[data-menu-xmlid="contacts.menu_contacts"]', content: _t('Want to <b>create customers</b>?<br/><i>Click on Contacts to start.</i>'), position: 'bottom', } }]); }); |
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:
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
tour.register('example_tour', { url: "/web", }, [tour.STEPS.MENU_MORE, { trigger: '.o_app[data-menu-xmlid="contacts.menu_contacts"]', content: _t('Want to <b>create customers</b>?<br/><i>Click on Contacts to start.</i>'), position: 'bottom', }, { trigger: '.o-kanban-button-new', content: _t('Let\'s create your first contact.'), position: 'bottom', width: 200, }, { // The trigger will tell that you would like to input a value in the field 'Name' trigger: 'input[placeholder="Name"]', extra_trigger: '.o_form_editable', // This is the 'hint' / tooltip that is shown to the enduser content: _t('Fill in the name of the contact.'), // When you run the test (from the developer tools) it will automatically fill in 'James Cook' automatically) run: 'text James Cook', position: 'right', }, { trigger: '.o_form_button_save', content: _t('Save this contact and the modifications you\'ve made to it.'), position: 'bottom', }]); |
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’:
Open up the XML file, inherit the assets template and insert the tour.js file into the assets. Your code should look like this:
|
1 2 3 4 5 6 7 8 9 |
<?xml version="1.0"?> <odoo> <template id="assets_backend" name="tour_demo assets" inherit_id="web.assets_backend"> <xpath expr="." position="inside"> <!-- Include the new tour in the JavaScript assets --> <script type="text/javascript" src="/tour_demo/static/src/js/tour.js"></script> </xpath> </template> </odoo> |
Now open up your manifest.py (or openerp.py if you’re in V10) and add the ‘assets.xml’ file to the data key so that it gets loaded too:
|
1 2 3 |
'data': [ 'views/assets.xml', ] |
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’:
Next create a new folder named ‘i18n’ and add your downloaded file to this folder:
Finally, open up the PO file and translate all the terms:
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!
