2018-02-16 23:00:40 +07:00
|
|
|
:banner: banners/odoo-sh.jpg
|
|
|
|
|
|
|
|
==================================
|
|
|
|
Your first module
|
|
|
|
==================================
|
|
|
|
|
|
|
|
Overview
|
|
|
|
========
|
|
|
|
|
|
|
|
This chapter helps you to create your first Odoo module and deploy it in your Odoo.sh project.
|
|
|
|
|
2018-03-28 22:32:25 +07:00
|
|
|
This tutorial requires :ref:`you created a project on Odoo.sh <odoosh-gettingstarted-create>`, and you know your Github repository's URL.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
Basic use of Git and Github is explained.
|
|
|
|
|
|
|
|
The below assumptions are made:
|
|
|
|
|
|
|
|
* *~/src* is the directory where are located the Git repositories related to your Odoo projects,
|
|
|
|
* *odoo* is the Github user,
|
|
|
|
* *odoo-addons* is the Github repository,
|
|
|
|
* *feature-1* is the name of a development branch,
|
|
|
|
* *master* is the name of the production branch,
|
|
|
|
* *my_module* is the name of the module.
|
|
|
|
|
|
|
|
Replace these by the values of your choice.
|
|
|
|
|
|
|
|
Create the development branch
|
|
|
|
=============================
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
From Odoo.sh
|
|
|
|
-------------
|
|
|
|
|
|
|
|
In the branches view:
|
|
|
|
|
|
|
|
* hit the :code:`+` button next to the development stage,
|
|
|
|
* choose the branch *master* in the *Fork* selection,
|
|
|
|
* type *feature-1* in the *To* input.
|
|
|
|
|
|
|
|
|pic1| |pic2|
|
|
|
|
|
|
|
|
.. |pic1| image:: ./media/firstmodule-development-+.png
|
|
|
|
:width: 45%
|
|
|
|
|
|
|
|
.. |pic2| image:: ./media/firstmodule-development-fork.png
|
|
|
|
:width: 45%
|
|
|
|
|
|
|
|
|
|
|
|
Once the build created, you can access the editor and browse to the folder *~/src/user* to access
|
|
|
|
to the code of your development branch.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-development-editor.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-development-editor-interface.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
From your computer
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
|
|
Clone your Github repository on your computer:
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ mkdir ~/src
|
|
|
|
$ cd ~/src
|
|
|
|
$ git clone https://github.com/odoo/odoo-addons.git
|
|
|
|
$ cd ~/src/odoo-addons
|
|
|
|
|
|
|
|
Create a new branch:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git checkout -b feature-1 master
|
|
|
|
|
|
|
|
|
|
|
|
Create the module structure
|
|
|
|
===========================
|
|
|
|
|
|
|
|
Scaffolding the module
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
While not necessary, scaffolding avoids the tedium of setting the basic Odoo module structure.
|
2018-12-27 18:22:08 +07:00
|
|
|
You can scaffold a new module using the executable *odoo-bin*.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
From the Odoo.sh editor, in a terminal:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ odoo-bin scaffold my_module ~/src/user/
|
2018-02-16 23:00:40 +07:00
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Or, from your computer, if you have an `installation of Odoo <https://www.odoo.com/documentation/11.0/setup/install.html#source-install>`_:
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ ./odoo-bin scaffold my_module ~/src/odoo-addons/
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
If you do not want to bother installing Odoo on your computer,
|
|
|
|
you can also :download:`download this module structure template <media/my_module.zip>` in which you replace every occurrences of
|
|
|
|
*my_module* to the name of your choice.
|
|
|
|
|
|
|
|
The below structure will be generated:
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
my_module
|
|
|
|
├── __init__.py
|
|
|
|
├── __manifest__.py
|
|
|
|
├── controllers
|
|
|
|
│ ├── __init__.py
|
|
|
|
│ └── controllers.py
|
|
|
|
├── demo
|
|
|
|
│ └── demo.xml
|
|
|
|
├── models
|
|
|
|
│ ├── __init__.py
|
|
|
|
│ └── models.py
|
|
|
|
├── security
|
|
|
|
│ └── ir.model.access.csv
|
|
|
|
└── views
|
|
|
|
├── templates.xml
|
|
|
|
└── views.xml
|
|
|
|
|
|
|
|
.. Warning::
|
|
|
|
|
|
|
|
Do not use special characters other than the underscore ( _ ) for your module name, not even an hyphen ( - ).
|
|
|
|
This name is used for the Python classes of your module,
|
|
|
|
and having classes name with special characters other than the underscore is not valid in Python.
|
|
|
|
|
|
|
|
Uncomment the content of the files:
|
|
|
|
|
|
|
|
* *models/models.py*,
|
|
|
|
an example of model with its fields,
|
|
|
|
* *views/views.xml*,
|
|
|
|
a tree and a form view, with the menus opening them,
|
|
|
|
* *demo/demo.xml*,
|
|
|
|
demo records for the above example model,
|
|
|
|
* *controllers/controllers.py*,
|
|
|
|
an example of controller implementing some routes,
|
|
|
|
* *views/templates.xml*,
|
|
|
|
two example qweb views used by the above controller routes,
|
|
|
|
* *__manifest__.py*,
|
|
|
|
the manifest of your module, including for instance its title, description and data files to load.
|
|
|
|
You just need to uncomment the access control list data file:
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
# 'security/ir.model.access.csv',
|
|
|
|
|
|
|
|
Manually
|
|
|
|
--------
|
|
|
|
|
|
|
|
If you want to create your module structure manually,
|
|
|
|
you can follow `Build an Odoo module <https://www.odoo.com/documentation/11.0/howtos/backend.html>`_ to understand
|
|
|
|
the structure of a module and the content of each file.
|
|
|
|
|
|
|
|
Push the development branch
|
|
|
|
===========================
|
|
|
|
|
2018-03-28 22:32:25 +07:00
|
|
|
Stage the changes to be committed
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git add my_module
|
|
|
|
|
|
|
|
Commit your changes
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git commit -m "My first module"
|
|
|
|
|
|
|
|
Push your changes to your remote repository
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
From an Odoo.sh editor terminal:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git push https HEAD:feature-1
|
|
|
|
|
|
|
|
The above command is explained in the section
|
|
|
|
:ref:`Commit & Push your changes
|
|
|
|
<odoosh-gettingstarted-online-editor>` of the
|
|
|
|
:ref:`Online Editor <odoosh-gettingstarted-online-editor>`
|
|
|
|
chapter.
|
|
|
|
It includes the explanation regarding the fact you will be prompted to type your username and password,
|
|
|
|
and what to do if you use the two-factor authentication.
|
|
|
|
|
|
|
|
Or, from your computer terminal:
|
|
|
|
|
2018-02-16 23:00:40 +07:00
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git push -u origin feature-1
|
|
|
|
|
|
|
|
You need to specify *-u origin feature-1* for the first push only.
|
2018-12-27 18:22:08 +07:00
|
|
|
From that point, to push your future changes from your computer, you can simply use
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git push
|
|
|
|
|
|
|
|
Test your module
|
|
|
|
================
|
|
|
|
|
|
|
|
Your branch should appear in your development branches in your project.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-branch.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
In the branches view of your project,
|
|
|
|
you can click on your branch name in the left navigation panel to access its history.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-branch-history.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
You can see here the changes you just pushed, including the comment you set.
|
|
|
|
Once the database ready, you can access it by clicking the *Connect* button.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-database.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
If your Odoo.sh project is configured to install your module automatically,
|
|
|
|
you will directly see it amongst the database apps. Otherwise, it will be available in the apps to install.
|
|
|
|
|
|
|
|
You can then play around with your module, create new records and test your features and buttons.
|
|
|
|
|
|
|
|
|
|
|
|
Test with the production data
|
|
|
|
=============================
|
|
|
|
|
|
|
|
You need to have a production database for this step. You can create it if you do not have it yet.
|
|
|
|
|
|
|
|
Once you tested your module in a development build with the demo data and believe it is ready,
|
|
|
|
you can test it with the production data using a staging branch.
|
|
|
|
|
|
|
|
You can either:
|
|
|
|
|
|
|
|
* Make your development branch a staging branch, by drag and dropping it onto the *staging* section title.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-devtostaging.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
* Merge it in an existing staging branch, by drag and dropping it onto the given staging branch.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-devinstaging.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
You can also use the :code:`git merge` command to merge your branches.
|
|
|
|
|
|
|
|
This will create a new staging build, which will duplicate the production database and make it run using a server
|
|
|
|
updated with your latest changes of your branch.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-mergedinstaging.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
Once the database ready, you can access it using the *Connect* button.
|
|
|
|
|
|
|
|
.. _odoosh-gettingstarted-firstmodule-productiondata-install:
|
|
|
|
|
|
|
|
Install your module
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
Your module will not be installed automatically, you have to install it from the apps menu.
|
|
|
|
Indeed, the purpose of the staging build is to test the behavior of your changes as it would be on your production,
|
|
|
|
and on your production you would not like your module to be installed automatically, but on demand.
|
|
|
|
|
|
|
|
Your module may not appear directly in your apps to install either, you need to update your apps list first:
|
|
|
|
|
|
|
|
* activate the developer mode from the Settings,
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-developermode.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
* in the apps menu, click the *Update Apps List* button,
|
|
|
|
* in the dialog that appears, click the *Update* button.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-updateappslist.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
Your module will then appear in the list of available apps.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-mymoduleinapps.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
Deploy in production
|
|
|
|
====================
|
|
|
|
|
|
|
|
Once you tested your module in a staging branch with your production data,
|
|
|
|
and believe it is ready for production, you can merge your branch in the production branch.
|
|
|
|
|
|
|
|
Drag and drop your staging branch on the production branch.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-mergeinproduction.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
You can also use the :code:`git merge` command to merge your branches.
|
|
|
|
|
|
|
|
This will merge the latest changes of your staging branch in the production branch,
|
|
|
|
and update your production server with these latest changes.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-mergedinproduction.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
Once the database ready, you can access it using the *Connect* button.
|
|
|
|
|
|
|
|
Install your module
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
Your module will not be installed automatically,
|
|
|
|
you have to install it manually as explained in the
|
|
|
|
:ref:`above section about installing your module in staging databases
|
|
|
|
<odoosh-gettingstarted-firstmodule-productiondata-install>`.
|
|
|
|
|
|
|
|
Add a change
|
|
|
|
============
|
|
|
|
|
|
|
|
This section explains how to add a change in your module by adding a new field in a model and deploy it.
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
From the Odoo.sh editor,
|
|
|
|
* browse to your module folder *~/src/user/my_module*,
|
|
|
|
* then, open the file *models/models.py*.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Or, from your computer,
|
|
|
|
* use the file browser of your choice to browse to your module folder *~/src/odoo-addons/my_module*,
|
|
|
|
* then, open the file *models/models.py* using the editor of your choice,
|
|
|
|
such as *Atom*, *Sublime Text*, *PyCharm*, *vim*, ...
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
Then, after the description field
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
description = fields.Text()
|
|
|
|
|
|
|
|
Add a datetime field
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
start_datetime = fields.Datetime('Start time', default=lambda self: fields.Datetime.now())
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Then, open the file *views/views.xml*.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
After
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
<field name="value2"/>
|
|
|
|
|
|
|
|
Add
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
<field name="start_datetime"/>
|
|
|
|
|
|
|
|
These changes alter the database structure by adding a column in a table,
|
|
|
|
and modify a view stored in database.
|
|
|
|
|
|
|
|
In order to be applied in existing databases, such as your production database,
|
|
|
|
these changes requires the module to be updated.
|
|
|
|
|
|
|
|
If you would like the update to be performed automatically by the Odoo.sh platform when you push your changes,
|
|
|
|
increase your module version in its manifest.
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Open the module manifest *__manifest__.py*.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
Replace
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
'version': '0.1',
|
|
|
|
|
|
|
|
with
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
'version': '0.2',
|
|
|
|
|
|
|
|
The platform will detect the change of version and trigger the update of the module upon the new revision deployment.
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Browse to your Git folder.
|
|
|
|
|
|
|
|
Then, from an Odoo.sh terminal:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ cd ~/src/user/
|
|
|
|
|
|
|
|
Or, from your computer terminal:
|
2018-04-03 19:37:08 +07:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ cd ~/src/odoo-addons/
|
2018-12-27 18:22:08 +07:00
|
|
|
|
|
|
|
Then, stage your changes to be committed
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
2018-04-03 19:37:08 +07:00
|
|
|
$ git add my_module
|
|
|
|
|
2018-02-16 23:00:40 +07:00
|
|
|
Commit your changes
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git commit -m "[ADD] my_module: add the start_datetime field to the model my_module.my_module"
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Push your changes:
|
|
|
|
|
|
|
|
From an Odoo.sh terminal:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git push https HEAD:feature-1
|
|
|
|
|
|
|
|
Or, from your computer terminal:
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git push
|
|
|
|
|
|
|
|
The platform will then create a new build for the branch *feature-1*.
|
|
|
|
|
|
|
|
.. image:: ./media/firstmodule-test-addachange-build.png
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
Once you tested your changes, you can merge your changes in the production branch, for instance by drag-and-dropping the
|
|
|
|
branch on the production branch in the Odoo.sh interface. As you increased the module version in the manifest,
|
|
|
|
the platform will update the module automatically and your new field will be directly available.
|
|
|
|
Otherwise you can manually update the module within the apps list.
|
|
|
|
|
|
|
|
Use an external Python library
|
|
|
|
==============================
|
|
|
|
|
|
|
|
If you would like to use an external Python library which is not installed by default,
|
|
|
|
you can define a *requirements.txt* file listing the external libraries your modules depends on.
|
|
|
|
|
|
|
|
The platform will use this file to automatically install the Python libraries your project needs.
|
|
|
|
|
|
|
|
The feature is explained in this section by using the `Unidecode library <https://pypi.python.org/pypi/Unidecode>`_ in
|
|
|
|
your module.
|
|
|
|
|
|
|
|
Create a file *requirements.txt* in the root folder of your repository
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
From the Odoo.sh editor, create and open the file ~/src/user/requirements.txt.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Or, from your computer, create and open the file ~/src/odoo-addons/requirements.txt.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
Add
|
|
|
|
|
|
|
|
.. code-block:: text
|
|
|
|
|
2018-03-30 16:28:00 +07:00
|
|
|
unidecode
|
2018-02-16 23:00:40 +07:00
|
|
|
|
2018-03-28 22:32:25 +07:00
|
|
|
Then use the library in your module, for instance to remove any special characters in the name field of your
|
2018-02-16 23:00:40 +07:00
|
|
|
model.
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Open the file *models/models.py*.
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
Before
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
from odoo import models, fields, api
|
|
|
|
|
|
|
|
Add
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
from unidecode import unidecode
|
|
|
|
|
|
|
|
After
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
start_datetime = fields.Datetime('Start time', default=lambda self: fields.Datetime.now())
|
|
|
|
|
|
|
|
Add
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
@api.model
|
|
|
|
def create(self, values):
|
|
|
|
if 'name' in values:
|
|
|
|
values['name'] = unidecode(values['name'])
|
|
|
|
return super(my_module, self).create(values)
|
|
|
|
|
|
|
|
@api.multi
|
|
|
|
def write(self, values):
|
|
|
|
if 'name' in values:
|
|
|
|
values['name'] = unidecode(values['name'])
|
|
|
|
return super(my_module, self).write(values)
|
|
|
|
|
|
|
|
Adding a Python dependency requires a module version increase for the platform to install it.
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Edit the module manifest *__manifest__.py*
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
Replace
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
'version': '0.2',
|
|
|
|
|
|
|
|
with
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
'version': '0.3',
|
|
|
|
|
2018-12-27 18:22:08 +07:00
|
|
|
Stage and commit your changes:
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
2018-03-28 22:32:25 +07:00
|
|
|
$ git add requirements.txt
|
2018-02-16 23:00:40 +07:00
|
|
|
$ git add my_module
|
|
|
|
$ git commit -m "[IMP] my_module: automatically remove special chars in my_module.my_module name field"
|
2018-12-27 18:22:08 +07:00
|
|
|
|
|
|
|
Then, push your changes:
|
|
|
|
|
|
|
|
In an Odoo.sh terminal:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ git push https HEAD:feature-1
|
|
|
|
|
|
|
|
In your computer terminal:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
2018-02-16 23:00:40 +07:00
|
|
|
$ git push
|