Creating configuration settings/views in Odoo

1. Introduction

Almost every app in Odoo needs some configuration options that you need to set within the module. If you want to create a configuration view in Odoo you will need to inherit the default Odoo model 'res.config.settings' which is used specifically to handle all the logic of app configurations. In this tutorial we will create a new configuration view with the most common configuration options in the view.

2. Models

2.1 Inheriting the transient model

The first thing that we need to do is to inherit the transient model 'res.config.settings'. This model already exists and is used for all configuration views in Odoo. Create a new Python file in your custom module under the /models folder named 'res_config_settings.py'. Now open the Python file and inherit the 'res.config.settings' model:

                        # -*- coding: utf-8 -*-from odoo import models, fields, apiclass ResConfigSettings(models.TransientModel):    _inherit = 'res.config.settings'                                            

After you've inherited the field you'll need to create your own fields for which you want to save configuration values. Inside this TransientModel you can use any field type just like in a normal model. Let us add some fields for configuration options. Have a look at this code:

                        # -*- coding: utf-8 -*-from odoo import models, fields, apiclass ResConfigSettings(models.TransientModel):    _inherit = 'res.config.settings'    company_id = fields.Many2one('res.company', default=lambda self: self.env.user.company_id.id)    custom_username = fields.Char(related='company_id.custom_username', string='Description', readonly=False)    use_custom_setting = fields.Boolean(string='Use custom setting',                                        config_parameter='oocademy_tutorial_configuration_settings.use_custom_setting')    number_of_days = fields.Integer(related='company_id.number_of_days',                                    string="Number of days", readonly=False)    module_project = fields.Boolean('Projects')    custom_password = fields.Char(related='company_id.custom_password', string='Password', readonly=False)    custom_description = fields.Text(related='company_id.custom_description', string='Default description',                                     readonly=False)                                            

So, what does this code tell us? Let's go over the fields one by one:

• company_id: this will create a many2one field linking to the res.company table. The value will be automatically filled thanks to the default which means that when you open the settings that Odoo will know for which company they are.
• custom_username: this will create a char field where you can enter text. It has a related set to 'company_id.custom_username' which means we'll need to create the field on the company model later on, we'll get to this in the next chapter. The readonly="False" is used to make the field editable in the view. If you do not set this option on either the field or in the view the field will not be editable in the configuration view.
• number_of_days: this will create an integer field which is stored on the res.company model.
• module_project: if a user checks on this boolean Odoo will automatically install the app project after saving the configuration. This is a built in option from Odoo and will work for any module just by saying module_name_of_the_module_to_install. It is not saved on the company as Odoo automatically installs and manages the module(s).
• custom_password: this will create a char field where you can enter text. Basically the same as 'custom_username' but to later on explain how to make passwords unreadable.
• custom_description: this will create a text field (textarea) in which the user can enter as much text as he/she likes.

2.2 Creating the fields on the res.company model

Alright we now have inherited the transient model and have the fields for our configuration view but the values still need to be saved somewhere in the database. Transient models are not meant for saving data on so we'll need to store them elsewhere, on the company. This means that you can create configurations per company and thanks to the Odoo framework Odoo will automatically map and calculate all values in the configurations views.

Create a new Python file in your custom module under the /models folder named 'res_company.py'. In this Python file we'll need to inherit the 'res.company' model and create fields for all the values that we want to save from the model 'res.config.settings'. Your code should look this:

                        # -*- coding: utf-8 -*-from odoo import models, fields, apiclass ResCompany(models.Model):    _inherit = 'res.company'    """        We have to inherit the res.company model in order to add our custom configuration fields to the model.        When you open a configuration menu in Odoo then Odoo will automatically look in the table res.company        for the values set there. By default all configurations are company wide in Odoo.        Have a look at res_config_settings.py where you can see that all fields are related to this model to get/set        those values on the company.    """    custom_username = fields.Char(string='Username')    use_custom_setting = fields.Boolean(string='Use custom setting')    number_of_days = fields.Integer(string="Number of days")    custom_password = fields.Char(string='Password')    custom_description = fields.Text(string='Default description',                                     default='Your custom description comes here.')                                            

This part of code will add all the fields we need to save from the model 'res.config.settings' into our database (and on the company). That's it, our model side is done!

3. Creating the configuration view

Now that we have the database side ready it is time to show all the fields to the end user in a view. Creating a configuration view is very similar to creating a 'normal' new view. The only difference is that you need to inherit the default configuration view to add your configuration view in. This means you'll also need to xpath into the existing view and add your elements in the view. The basic logic of your configuration view should look like this:

                                                                                    <odoo>                                    <record id="res_config_settings_view_form" model="ir.ui.view">                                        <field name="name">res.config.settings.view.form.inherit.oocademy</field>                                        <field name="model">res.config.settings</field>                                        <field name="priority" eval="50"></field>                                        <field name="inherit_id" ref="base.res_config_settings_view_form"></field>                                        <field name="arch" type="xml">                                            <xpath expr="//div[hasclass('settings')]" position="inside"></xpath>                                        </field>                                    </record>                                </odoo>                                                                        

As you can see we inherit the default view 'base.res_config_settings_view_form' which contains the basic view architecture for creating the configuration view. In this inherit we do an xpath on the element 'div' which has the class 'settings'. The next step is to create our own view within the configuration. The great part about the configuration view is that within the xpath expression you can use HTML so you have quite a lot of flexibility to style and lay-out your own configuration view! The bad part is that you'll quickly get huge views so I already apologise for my following example. Just have a look at my example lay-out for the configuration menu:

                                                                                    <odoo>                                    <record id="res_config_settings_view_form" model="ir.ui.view">                                        <field name="name">res.config.settings.view.form.inherit.oocademy</field>                                        <field name="model">res.config.settings</field>                                        <field name="priority" eval="50"></field>                                        <field name="inherit_id" ref="base.res_config_settings_view_form"></field>                                        <field name="arch" type="xml">                                            <xpath expr="//div[hasclass('settings')]" position="inside">                                                <div class="app_settings_block" data-string="oocademy_tutorial_configuration_settings" string="Custom configuration" data-key="oocademy_tutorial_configuration_settings"><script data-ad-client="ca-pub-7357241631679316" src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
                    <ins class="adsbygoogle"
     style="display:block; text-align:center;"
     data-ad-layout="in-article"
     data-ad-format="fluid"
     data-ad-client="ca-pub-7357241631679316"
     data-ad-slot="7654326254"></ins>
     <script>
     (adsbygoogle = window.adsbygoogle || []).push({});
</script>                                                    <h2>Custom fields configuration</h2>                                                    <div class="row mt16 o_settings_container">                                                        <div class="col-xs-12 col-md-6 o_setting_box" id="username">                                                            <div class="o_setting_right_pane">                                                                <label string="Username" for="custom_username"></label>                                                                <div class="text-muted">Fill in an username</div>                                                                <div class="mt16">                                                                    <field name="custom_username" required="1"></field>                                                                </div>                                                            </div>                                                        </div>                                                        <div class="col-xs-12 col-md-6 o_setting_box" id="password">                                                            <div class="o_setting_right_pane">                                                                <label string="Password" for="custom_password"></label>                                                                <div class="text-muted">Fill in the password for the user</div>                                                                <div class="mt16">                                                                    <field name="custom_password" password="True"></field>                                                                </div>                                                            </div>                                                        </div>                                                        <div class="col-12 col-lg-6 o_setting_box" title="Checking this option on allows you to use the custom settings by default on another model.">                                                            <div class="o_setting_left_pane">                                                                <field name="use_custom_setting"></field>                                                            </div>                                                            <div class="o_setting_right_pane">                                                                <label for="use_custom_setting"></label>                                                                <div class="text-muted">Use this setting by default on records</div>                                                            </div>                                                        </div>                                                    </div>                                                    <div class="row mt16 o_settings_container">                                                        <div class="col-xs-12 col-md-12 o_setting_box" id="number_of_days">                                                            <div class="o_setting_right_pane">                                                                <label string="Default amount of days" for="number_of_days"></label>                                                                <div class="mt16">                                                                    <field name="number_of_days"></field>                                                                </div>                                                            </div>                                                        </div>                                                    </div>                                                    <h2>Module configuration</h2>                                                    <div class="row mt16 o_settings_container">                                                        <div class="col-12 col-lg-6 o_setting_box" id="project">                                                            <div class="o_setting_left_pane">                                                                <field name="module_project"></field>                                                            </div>                                                            <div class="o_setting_right_pane">                                                                <label for="module_project"></label>                                                                <div class="text-muted" id="project_module">Use the projects module</div>                                                            </div>                                                        </div>                                                    </div>                                                    <h2>Default description</h2>                                                    <div class="row mt16 o_settings_container">                                                        <div class="col-xs-12 col-md-12 o_setting_box" id="custom_description">                                                            <div class="o_setting_right_pane">                                                                <label string="Custom description" for="custom_description"></label>                                                                <div class="mt16">                                                                    <field name="custom_description"></field>                                                                </div>                                                            </div>                                                        </div>                                                    </div>                                                </div>                                            </xpath>                                        </field>                                    </record>                                </odoo>                                                                        

Quite a big chunk of code right? In short this view just uses default bootstrap classes in order to build a nicely looking view in the settings. Some general pointers:

• o_settings_container, o_setting_left_pane, o_setting_right_pane and o_setting_box are classes built by Odoo and are used throughout all the configuration menus so you should try to stick to these.
• text_muted is used to make text smaller and light gray, it usually gives extra information about a setting while not distracting you too much.
• password="True" is used to mask the text you fill in. In general it is used to hide passwords so that they're not shown as plain text in the configuration view.

4. Creating a menu and action

Alright, we're nearly done! The last step is to create a menuitem and an action to open the configuration view. In this tutorial I'll create a new app on the homescreen with a configuration menuitem and an action as I do not know where you'd want to build these settings. You can just change this example.

4.1 Creating a main menuitem

First we'll need a main menu item, which will show up as an app on the Odoo home screen. Just create a new menuitem with a name and an icon:

                                                                                    <menuitem id="configuration_menu_root" name="Config tutorial" sequence="98" web_icon="base,static/description/settings.png"/>                                                                        

4.2 Creating an action

The next step is to create an action. The action will make sure that if you click on the menuitem that it will open up the configuration view. There is a little difference with a normal action here though. If you want to link an action to a configuration view you'll need to tell Odoo which configuration tab it should open from all the configurations. You can do this with the context by adding a 'module' key to it:

                                                                                    <record id="action_custom_config_settings" model="ir.actions.act_window">                                    <field name="name">Settings</field>                                    <field name="type">ir.actions.act_window</field>                                    <field name="res_model">res.config.settings</field>                                    <field name="view_id" ref="res_config_settings_view_form"></field>                                    <field name="view_mode">form</field>                                    <field name="target">inline</field>                                    <field name="context">{'module' : 'oocademy_tutorial_configuration_settings'}</field>                                </record>                                                                        

The context {'module' : 'oocademy_tutorial_configuration_settings'} will tell Odoo that it needs to open this specific tab in the configuration page as we've configured it earlier on in the view (under the app_settings_block div). So that's it! If you now save everything and install the module you'll have your own configuration menu!

5. Conclusion

Creating configuration views in Odoo is not the easiest thing to do and it requires quite some steps to create them but the possibilities are huge. You can install apps by just checking on a boolean field, you can save the configurations on the company and the configuration views are fully customizable! It is clear that this is a vital part of Odoo and that it is well thought out by Odoo.