It's common to hear about Odoo modules and applications. But what exactly is the difference between them? Modules are building blocks of Odoo applications. A module can add or modify Odoo features. It is supported by a directory containing a manifest or descriptor file (named __openerp__.py) and the remaining files that implement its features. Sometimes, modules can also be referred to as "add-ons." Applications are not different from regular modules, but functionally, they provide a central feature, around which other modules add features or options. They provide the core elements for a functional area, such as accounting or HR, around which other modules add features. Because of this, they are highlighted in the Odoo Apps menu.

In the example that will follow, we will create a new module with as few dependencies as possible.

This will not be the typical case, however. The most frequent situation is where modifications or extensions are needed on an already existing module to fit some specific use cases.

The golden rule is that we shouldn't modify existing modules by changing them directly. It's considered bad practice to modify existing modules. This is especially true for the official modules provided by Odoo. Doing so does not allow a clear separation between the original module code and our modifications, and makes it difficult to apply upgrades.

Instead, we should create new modules to be applied on top of the modules we want to modify, and implement those changes. This is one of Odoo's main strengths: it provides "inheritance" mechanisms that allow custom modules to extend existing modules, either official or from the community. The inheritance is possible at all levels data models...

Our module will be a very simple application to keep to-do tasks. These tasks will have a single text field, for the description, and a checkbox to mark them as complete. We will also have a button to clean the to-do list from the old completed tasks.

These are very simple specifications, but throughout the book we will gradually add new features to it, to make it more interesting for the users.

Enough talk, let's start coding and create our new module.

Following the instructions in Chapter 1, Getting Started with Odoo Development, we should have the Odoo server at /odoo-dev/odoo/. To keep things tidy, we will create a new directory alongside it to host our custom modules:

$ mkdir ~/odoo-dev/custom-addons

An Odoo module is a directory containing an __openerp__.py descriptor file. This is still a legacy from when Odoo was named OpenERP, and in the future is expected to become __odoo__.py.

It also needs to be Python importable, so it must also have an __init__.py file.

The...

Now that we have a new module, even if minimal, we want to make it available in Odoo.

For that, we need to make sure the directory the module is in is part of the addons path. And then we need to update the Odoo module list.

Both operations have been explained in detail in the previous chapter, but we will follow here with a brief overview of what is needed.

We will position in our work directory and start the server with the appropriate addons path configuration:

$ cd ~/odoo-dev
$ odoo/odoo.py -d v8dev --addons-path="custom-addons,odoo/addons" --save

The --save option saves the options you used in a config file. This spares you from repeating them the next time you restart the server: just run ./odoo.py and the last saved options will be used.

Look closely at the server log. It should have an INFO ? openerp: addons paths: (...) line, and it should include our custom-addons directory.

Remember to also include any other addons directories you might be using. For instance...

The Local Modules option shows us the list of available modules. By default it shows only Apps modules. Since we created an application module we don't need to remove that filter to see it. Type "todo" in the search and you should see our new module, ready to be installed.

Now click on its Install button and you're done!

Developing a module is an iterative process, and you will want changes made on source files to be applied and visible in Odoo.

In most cases this is done by upgrading the module: look up the module in the Local Modules list and, since it is installed, you will see an Upgrade button available.

However, when the changes are only in Python code, the upgrade may not have an effect. Instead of a module upgrade, an application server restart is needed.

In some cases, if the module has changed both in data files and Python code, you might need both operations. This is a common source of confusion for newcomer Odoo developers.

But fortunately, there is a better way. The simplest and fastest way to make all our changes to a module effective is to stop (Ctrl + C) and restart the server process requesting our modules to be upgraded on our work database.

To start the server upgrading the todo_app module in the v8dev database, we will use:

$ ./odoo.py -d v8dev -u todo_app

The -u option...

Now that Odoo knows about our new module, let's start by adding to it a simple model.

Models describe business objects, such as an opportunity, a sales order, or a partner (customer, supplier, and so on.). A model has a list of attributes and can also define its specific business.

Models are implemented using a Python class derived from an Odoo template class. They translate directly to database objects, and Odoo automatically takes care of that when installing or upgrading the module.

Some consider it good practice to keep the Python files for models inside a models subdirectory. For simplicity we won't be following that here, so let's create a todo_model.py file in the todo_app module main directory.

Add the following content to it:

# -*- coding: utf-8 -*-
from openerp import models, fields
class TodoTask(models.Model):
    _name = 'todo.task'
    name = fields.Char('Description', required=True)
    is_done = fields.Boolean('Done?')
    active = fields.Boolean...

Now that we have a model to store our data, let's make it available on the user interface.

All we need to do is to add a menu option to open the To-do Task model so that it can be used. This is done using an XML file. Just as in the case of models, some people consider it good practice to keep the view definitions inside a views subdirectory.

We will create a new todo_view.xml data file in the module's top directory, and it will declare a menu item and the action performed by it:

<?xml version="1.0"?>
<openerp>
  <data>

    <!-- Action to open To-do Task list -->
    <act_window id="action_todo_task"
      name="To-do Task"
      res_model="todo.task"
      view_mode="tree,form" />

    <!-- Menu item to open To-do Task list -->
    <menuitem id="menu_todo_task"
      name="To-Do Tasks"
      parent="mail.mail_feeds"
      sequence="20"
      action="action_todo_task" />

  </data>
</openerp>

The user interface, including...

As we have seen, if no view is defined, Odoo will automatically generate basic views to get you going. But surely you would like to define the module views yourself, so that's what we'll do next.

Odoo supports several types of views, but the three main ones are: list (also called tree), form, and search views. We'll add an example of each to our module.

All views are stored in the database, in the ir.ui.view model. To add a view in a module, we declare a <record> element describing the view in an XML file that will be loaded into the database when the module is installed.

<record id="view_form_todo_task" model="ir.ui.view">
  <field name="name">To-do Task Form</field>
  <field name="model">todo.task</field>
  <field name="arch" type="xml">

    <form string="To-do Task">...

When viewing a model in list mode, a <tree> view is used. Tree views are capable of displaying lines organized in hierarchies, but most of the time they are used to display plain lists.

We can add the following tree view definition to todo_view.xml:

<record id="view_tree_todo_task" model="ir.ui.view">
  <field name="name">To-do Task Tree</field>
  <field name="model">todo.task</field>
  <field name="arch" type="xml">
    <tree colors="gray:is_done==True">
      <field name="name"/>
      <field name="is_done"/>
    </tree>
  </field>
</record>

We have defined a list with only two columns, name and is_done. We also added a nice touch: the lines for done tasks (is_done==True) are shown in grey.

At the top right of the list Odoo displays a search box. The default fields it searches for and available predefined filters can be defined by a <search> view.

As before, we will add this to the...