.. This chapter is dedicated to detailed objects definition:
all fields
all objects
inheritancies
All the ERP's pieces of data are accessible through "objects". As an example, there is a res.partner object to access the data concerning the partners, an account.invoice object for the data concerning the invoices, etc...
Please note that there is an object for every type of resource, and not an
object per resource. We have thus a res.partner object to manage all the
partners and not a *res.partner* object per partner. If we talk in "object
oriented" terms, we could also say that there is an object per level.
The direct consequences is that all the methods of objects have a common parameter: the "ids" parameter. This specifies on which resources (for example, on which partner) the method must be applied. Precisely, this parameter contains a list of resource ids on which the method must be applied.
For example, if we have two partners with the identifiers 1 and 5, and we want to call the res_partner method "send_email", we will write something like::
res_partner.send_email(... , [1, 5], ...)
We will see the exact syntax of object method calls further in this document.
In the following section, we will see how to define a new object. Then, we will check out the different methods of doing this.
For developers:
* OpenERP "objects" are usually called classes in object oriented programming.
* A OpenERP "resource" is usually called an object in OO programming, instance of a class.
It's a bit confusing when you try to program inside OpenERP, because the language used is Python, and Python is a fully object oriented language, and has objects and instances ...
Luckily, an OpenERP "resource" can be converted magically into a nice Python object using the "browse" class method (OpenERP object method).
The ORM - Object-relational mapping - Models
--------------------------------------------
The ORM, short for Object-Relational Mapping, is a central part of OpenERP.
In OpenERP, the data model is described and manipulated through Python classes
and objects. It is the ORM job to bridge the gap -- as transparently as
possible for the developer -- between Python and the underlying relational
database (PostgreSQL), which will provide the persistence we need for our
objects.
OpenERP Object Attributes
-------------------------
Objects Introduction
++++++++++++++++++++
To define a new object, you must define a new Python class then instantiate it. This class must inherit from the osv class in the osv module.
Object definition
+++++++++++++++++
The first line of the object definition will always be of the form::
class name_of_the_object(osv.osv):
_name = 'name.of.the.object'
_columns = { ... }
...
name_of_the_object()
An object is defined by declaring some fields with predefined names in the
class. Two of them are required (_name and _columns), the rest are optional.
The predefined fields are:
Predefined fields
+++++++++++++++++
`_auto`
Determines whether a corresponding PostgreSQL table must be generated
automatically from the object. Setting _auto to False can be useful in case
of OpenERP objects generated from PostgreSQL views. See the "Reporting From
PostgreSQL Views" section for more details.
`_columns (required)`
The object fields. See the :ref:`fields <fields-link>` section for further details.
`_constraints`
The constraints on the object. See the constraints section for details.
`_sql_constraints`
The SQL Constraint on the object. See the SQL constraints section for further details.
`_defaults`
The default values for some of the object's fields. See the default value section for details.
`_inherit`
The name of the osv object which the current object inherits from. See the :ref:`object inheritance section<inherit-link>`
(first form) for further details.
`_inherits`
The list of osv objects the object inherits from. This list must be given in
a python dictionary of the form: {'name_of_the_parent_object':
'name_of_the_field', ...}. See the :ref:`object inheritance section<inherits-link>`
(second form) for further details. Default value: {}.
`_log_access`
Determines whether or not the write access to the resource must be logged.
If true, four fields will be created in the SQL table: create_uid,
create_date, write_uid, write_date. Those fields represent respectively the
id of the user who created the record, the creation date of record, the id
of the user who last modified the record, and the date of that last
modification. This data may be obtained by using the perm_read method.
`_name (required)`
Name of the object. Default value: None.
`_order`
Name of the fields used to sort the results of the search and read methods.
Default value: 'id'.
Examples::
_order = "name"
_order = "date_order desc"
`_rec_name`
Name of the field in which the name of every resource is stored. Default
value: 'name'. Note: by default, the name_get method simply returns the
content of this field.
`_sequence`
Name of the SQL sequence that manages the ids for this object. Default value: None.
`_sql`
SQL code executed upon creation of the object (only if _auto is True). It means this code gets executed after the table is created.
`_table`
Name of the SQL table. Default value: the value of the _name field above
with the dots ( . ) replaced by underscores ( _ ).
.._inherit-link:
Object Inheritance - _inherit
-----------------------------
Introduction
++++++++++++
Objects may be inherited in some custom or specific modules. It is better to
inherit an object to add/modify some fields.
It is done with::
_inherit='object.name'
Extension of an object
++++++++++++++++++++++
There are two possible ways to do this kind of inheritance. Both ways result in
a new class of data, which holds parent fields and behaviour as well as
additional fields and behaviour, but they differ in heavy programatical
consequences.
While Example 1 creates a new subclass "custom_material" that may be "seen" or
"used" by any view or tree which handles "network.material", this will not be
the case for Example 2.
This is due to the table (other.material) the new subclass is operating on,
which will never be recognized by previous "network.material" views or trees.
If we want to add a field that retrieves the function of an employee by looking its current contract, we use a functional field. The object hr_employee is inherited this way:
To add properties in forms, just put the <properties/> tag in your form. This will automatically add all properties fields that are related to this object. The system will add properties depending on your rights. (some people will be able to change a specific property, others won't).
Properties are displayed by section, depending on the group_name attribute. (It is rendered in the client like a separator tag).
**How does this work ?**
The fields.property class inherits from fields.function and overrides the read and write method. The type of this field is many2one, so in the form a property is represented like a many2one function.
But the value of a property is stored in the ir.property class/table as a complete record. The stored value is a field of type reference (not many2one) because each property may point to a different object. If you edit properties values (from the administration menu), these are represented like a field of type reference.
When you read a property, the program gives you the property attached to the instance of object you are reading. If this object has no value, the system will give you the default property.
The definition of a property is stored in the ir.model.fields class like any other fields. In the definition of the property, you can add groups that are allowed to change to property.
**Using properties or normal fields**
When you want to add a new feature, you will have to choose to implement it as a property or as normal field. Use a normal field when you inherit from an object and want to extend this object. Use a property when the new feature is not related to the object but to an external concept.
Here are a few tips to help you choose between a normal field or a property:
Normal fields extend the object, adding more features or data.
A property is a concept that is attached to an object and have special features:
* Different value for the same property depending on the company
* Rights management per field
* It's a link between resources (many2one)
**Example 1: Account Receivable**
The default "Account Receivable" for a specific partner is implemented as a property because:
* This is a concept related to the account chart and not to the partner, so it is an account property that is visible on a partner form. Rights have to be managed on this fields for accountants, these are not the same rights that are applied to partner objects. So you have specific rights just for this field of the partner form: only accountants may change the account receivable of a partner.
* This is a multi-company field: the same partner may have different account receivable values depending on the company the user belongs to. In a multi-company system, there is one account chart per company. The account receivable of a partner depends on the company it placed the sale order.
* The default account receivable is the same for all partners and is configured from the general property menu (in administration).
..note::
One interesting thing is that properties avoid "spaghetti" code. The account module depends on the partner (base) module. But you can install the partner (base) module without the accounting module. If you add a field that points to an account in the partner object, both objects will depend on each other. It's much more difficult to maintain and code (for instance, try to remove a table when both tables are pointing to each others.)
**Example 2: Product Times**
The product expiry module implements all delays related to products: removal date, product usetime, ... This module is very useful for food industries.
This module inherits from the product.product object and adds new fields to it: