Creating the module's basic skeleton

Following the instructions in Chapter 2, Installing and Organizing the Development Environment, we should have the Odoo server code at ~/odoo-dev/odoo/. The best practices say that our code should be kept in its own directory, and never mixed up with Odoo's original code. So, to host our custom modules we will use a new directory alongside Odoo: ~/odoo-dev/custom-addons.

Odoo includes a scaffold command to automatically create a new module directory, with a basic structure already in place. You can learn more about it with the following command:

$ ~/odoo-dev/odoo/odoo-bin scaffold --help

You might want to keep this in mind when you start working on your next module, but we won't be using it right now since we prefer to manually alter the structure for our module.

An Odoo addon module is a directory containing a __manifest__.py descriptor file. It also needs to be Python importable, so it must also have a __init__.py file.

The module's directory name is its technical name. We will use todo_app for it. The technical name must be a valid Python identifier: it should begin with a letter and can only contain letters, numbers, and the underscore character.

If using the command line, we can initialize our module directory, with an empty __init__.py file in it, with these commands:

$ mkdir -p ~/odoo-dev/custom-addons/todo_app
$ touch ~/odoo-dev/custom-addons/todo_app/__init__.py

Next, we need to add the manifest file. It should contain only a Python dictionary, with about a dozen possible attributes. Of them, only the name attribute is required, but the description and author attributes are also highly advised.

Now, create the __manifest__.py file, alongside the __init__.py file, with the following content:

{ 
    'name': 'To-Do Application', 
    'description': 'Manage personal to-do tasks.', 
    'author': 'Daniel Reis', 
    'depends': ['base'], 
    'application': True, 
} 

The depends attribute can have a list of other modules that are required. Odoo will have them automatically installed when this module is installed. It's not a mandatory attribute, but it's advised to always have it. If no particular dependencies are needed, we should depend on the core base module.

You should be careful to ensure all dependencies are explicitly set here; otherwise, the module may fail to install in a clean database (due to missing dependencies) or have loading errors if by chance the other required modules are loaded afterward.

For our application, we don't need any specific dependencies, so we depend on the base module only.

To be concise, we chose to use only some essential descriptor keys:

• name is a string with the addon module title.
• description is a long text with the description of the features, usually in RST format.
• author is the author name. It is a string, but can contain a comma-separated list of names.
• depends is a list of the addon modules it depends on. They will be automatically installed before this module is.
• application is a Boolean flag, declaring whether the addon module should be featured as an app in the Apps list.

Since Odoo 8.0, instead of the description key, we can use a README.rst or README.md file in the module's top directory. If both exist, then the manifest description is used.

In a real-world scenario, we recommend that you also use the additional keys, since they are relevant for the Odoo apps store:

• summary is a string displayed as a subtitle for the module.
• version, by default, is 1.0. It should follow versioning rules (see  http://semver.org/ for details). It is a good practice to use the Odoo version before our module version, for example: 11.0.1.0.
• license identifier, by default considered to be LGPL-3.
• website is a URL to find more information about the module. This can help people find more documentation or the issue tracker to file bugs and suggestions.
• category is a string with the functional category of the module, which defaults to Uncategorized. The list of existing categories can be found in the security Groups form (at Settings | User | Groups), in the Application field drop-down list.

These other descriptor keys are also available:

• installable is by default True but can be set to False to disable a module.
• auto_install, if set to True, will be automatically installed as soon as all its dependencies are already installed. It is used for "glue" modules, connecting two features together as soon as both are installed in the same instance.