4.4 step1

Step 1 - Module Basics

For this first step, you will need to checkout the associated git branch in the training module:

git checkout step1

This step will focus on explaining the file structure of a module, and its basic components.

Module structure

When checking out the branch, you will find the library module under the modules directory of your local copy of the training repository. For now all files are empty, but that shall change shortly.

Here is the structure of a basic tryton module :

library
   ├─ tryton.cfg
   ├─ __init__.py
   ├─ library.py
   ├─ library.xml
   └─ view
        ├─ author_form.xml
        └─ author_list.xml

We are going to detail each and every one of those files, and start to build up our module.

The tryton.cfg file

Open the tryton.cfg file and write down the following:

[tryton]
depends:
    ir
    res
xml:
    library.xml

This file will be used by tryton to understand how it should install / upgrade your module.

The depends section

The depends section contains the modules on which your module depends. Here we only specify the ir and res modules. Those modules are the basic tryton modules, and are directly built into the server.

When your module extends models from other modules, or requires in any way that another module be installed for your it to behave as intended, you should add it there. There is no requirement on the module order, though for readability purposes it is recommanded to order them depending on their level in the module hierarchy (i.e. more general to more specific).

The ir module

The ir module stands for Internal Resources. It contains all the models that are needed to manage the client interface. That includes menus, views, actions, etc...

The source code of this module is available here for further reading.

The res module

The res module stands for Resources. It contains other resources that are needed for the trytond server to behave as expected. Typically, you can find in there all the models that are used for user / access-right management.

The source code of this module is available here for further reading.

The xml module

The xml section is the list of xml files that should be loaded by the server when installing or upgrading your module. Here there is only library.xml, which we will describe later on. The order is important here, because the contents of a file may depend on that of another. So if the order is wrong, installing or updating your server may fail because the server will look for an entity it does not yet installed.

Those xml files are used to create the necessary informations in the database for your module. This will usually include UI related elements (views, entry points, etc...), authorizations defaults, and configuration elements. This will be further detailed later on.

The __init__.py file

Open the __init__.py file and write down the following:

from trytond.pool import Pool

import library


def register():
    Pool.register(
        library.Author,
        module='library', type_='model')

The __init__.py file is where all standard python modules describe their contents and make them available. In the case of a tryton module, it has a very specific purpose: teach the tryton server what your module does, and how to do it. This is done by registering the python classes that describe the constitutive elements of your module. We use the word register because the server will aggregate the classes you register here in a Model which are the building blocks of tryton.

More on this later, for now let's break it down a bit.

from trytond.pool import Pool

Here we import the Pool class from trytond. This class is central to the tryton framework, because it allows for its full modularity. You will use it a lot, we will see how later.

import library

This is a standard python import of the library.py file directly in our module folder. We need it to access the classes that we must register.

def register():

The __init__.py file of a tryton module is expected to declare a register function. It will be called by the server during the server start up to register the module.

Pool.register(
    library.Author,
    module='library', type_='model')

Here is where things get done. We are basically instructing tryton to register the library.Author class in the Pool. We specify that this class is linked to the library module, and that it is a model.

Warning: the module argument value MUST be identical to the name of your module as it is understood by tryton. There are different way to specify this name, but the basic one is the name of the directory in which you are working.

The type_ parameter have the following possible values: model, wizard and report. The latter is seldom use and will not be detailed in this training, the second we will see later.

Note : The Pool.register method accepts a list of classes as parameters, so if your module defined more than one model, they can be registered in one go:

Pool.register(
    MyModel1,
    MyModel2,
    MyModel3,
    module='my_module', type_='model')