odoo
/
odoo
2
0
Fork 0
Code Pull Requests Releases Activity

doc review part1 

bzr revid: al@openerp.com-20121113010059-efzzjaak19n1fn7s
This commit is contained in:
Antony Lesuisse 2012-11-13 02:00:59 +01:00
parent 1086c96272
commit b6bdd7c699
4 changed files with 319 additions and 684 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

295
doc/01_getting_started.rst
View File

@ -155,6 +155,21 @@ You can specify alternate configuration files with ::
-c CONFIG, --config=CONFIG specify alternate config file
Configure addons locations
--------------------------
By default, the only directory of addons known by the server is server/bin/addons.
It is possible to add new addons by
- copying them in server/bin/addons, or creating a symbolic link to each
of them in this directory, or
- specifying another directory containing addons to the server. The later
can be accomplished either by running the server with the ``--addons-path=``
option, or by configuring this option in the openerp_serverrc file,
automatically generated under Linux in your home directory by the
server when executed with the ``--save`` option. You can provide several
addons to the ``addons_path`` = option, separating them using commas.
Start-up script
===============
@ -173,283 +188,3 @@ Yet another alternative is to use a WSGI-compatible HTTP server and let it call
into one of the WSGI entry points of the server.
Appendix
========
Command line options example
++++++++++++++++++++++++++++
Usage: openerp-server [options]
**Options**::
--version show program's version number and exit
-h, --help show this help message and exit
**Common options**::
-c CONFIG, --config=CONFIG
specify alternate config file
-s, --save save configuration to ~/.openerp_serverrc
-i INIT, --init=INIT
install one or more modules (comma-separated list, use
"all" for all modules), requires -d
-u UPDATE, --update=UPDATE
update one or more modules (comma-separated list, use
"all" for all modules). Requires -d.
--without-demo=WITHOUT_DEMO
disable loading demo data for modules to be installed
(comma-separated, use "all" for all modules). Requires
-d and -i. Default is none
-P IMPORT_PARTIAL, --import-partial=IMPORT_PARTIAL
Use this for big data importation, if it crashes you
will be able to continue at the current state. Provide
a filename to store intermediate importation states.
--pidfile=PIDFILE file where the server pid will be stored
--addons-path=ADDONS_PATH
specify additional addons paths (separated by commas).
--load=SERVER_WIDE_MODULES
Comma-separated list of server-wide modules
default=web
**XML-RPC Configuration**::
--xmlrpc-interface=XMLRPC_INTERFACE
Specify the TCP IP address for the XML-RPC protocol.
The empty string binds to all interfaces.
--xmlrpc-port=XMLRPC_PORT
specify the TCP port for the XML-RPC protocol
--no-xmlrpc disable the XML-RPC protocol
--proxy-mode Enable correct behavior when behind a reverse proxy
**XML-RPC Secure Configuration**::
--xmlrpcs-interface=XMLRPCS_INTERFACE
Specify the TCP IP address for the XML-RPC Secure
protocol. The empty string binds to all interfaces.
--xmlrpcs-port=XMLRPCS_PORT
specify the TCP port for the XML-RPC Secure protocol
--no-xmlrpcs disable the XML-RPC Secure protocol
--cert-file=SECURE_CERT_FILE
specify the certificate file for the SSL connection
--pkey-file=SECURE_PKEY_FILE
specify the private key file for the SSL connection
**NET-RPC Configuration**::
--netrpc-interface=NETRPC_INTERFACE
specify the TCP IP address for the NETRPC protocol
--netrpc-port=NETRPC_PORT
specify the TCP port for the NETRPC protocol
--no-netrpc disable the NETRPC protocol
**Web interface Configuration**::
--db-filter=REGEXP Filter listed database
**Static HTTP service**::
--static-http-enable
enable static HTTP service for serving plain HTML
files
--static-http-document-root=STATIC_HTTP_DOCUMENT_ROOT
specify the directory containing your static HTML
files (e.g '/var/www/')
--static-http-url-prefix=STATIC_HTTP_URL_PREFIX
specify the URL root prefix where you want web
browsers to access your static HTML files (e.g '/')
**Testing Configuration**::
--test-file=TEST_FILE
Launch a YML test file.
--test-report-directory=TEST_REPORT_DIRECTORY
If set, will save sample of all reports in this
directory.
--test-enable Enable YAML and unit tests.
--test-commit Commit database changes performed by YAML or XML
tests.
**Logging Configuration**::
--logfile=LOGFILE file where the server log will be stored
--no-logrotate do not rotate the logfile
--syslog Send the log to the syslog server
--log-handler=PREFIX:LEVEL
setup a handler at LEVEL for a given PREFIX. An empty
PREFIX indicates the root logger. This option can be
repeated. Example: "openerp.orm:DEBUG" or
"werkzeug:CRITICAL" (default: ":INFO")
--log-request shortcut for --log-
handler=openerp.netsvc.rpc.request:DEBUG
--log-response shortcut for --log-
handler=openerp.netsvc.rpc.response:DEBUG
--log-web shortcut for --log-
handler=openerp.addons.web.common.http:DEBUG
--log-sql shortcut for --log-handler=openerp.sql_db:DEBUG
--log-level=LOG_LEVEL
specify the level of the logging. Accepted values:
['info', 'debug_rpc', 'warn', 'test', 'critical',
'debug_sql', 'error', 'debug', 'debug_rpc_answer',
'notset'] (deprecated option).
**SMTP Configuration**::
--email-from=EMAIL_FROM
specify the SMTP email address for sending email
--smtp=SMTP_SERVER specify the SMTP server for sending email
--smtp-port=SMTP_PORT
specify the SMTP port
--smtp-ssl specify the SMTP server support SSL or not
--smtp-user=SMTP_USER
specify the SMTP username for sending email
--smtp-password=SMTP_PASSWORD
specify the SMTP password for sending email
**Database related options**::
-d DB_NAME, --database=DB_NAME
specify the database name
-r DB_USER, --db_user=DB_USER
specify the database user name
-w DB_PASSWORD, --db_password=DB_PASSWORD
specify the database password
--pg_path=PG_PATH specify the pg executable path
--db_host=DB_HOST specify the database host
--db_port=DB_PORT specify the database port
--db_maxconn=DB_MAXCONN
specify the the maximum number of physical connections
to posgresql
--db-template=DB_TEMPLATE
specify a custom database template to create a new
database
**Internationalisation options**::
Use these options to translate OpenERP to another language.See i18n
section of the user manual. Option '-d' is mandatory.Option '-l' is
mandatory in case of importation
--load-language=LOAD_LANGUAGE
specifies the languages for the translations you want
to be loaded
-l LANGUAGE, --language=LANGUAGE
specify the language of the translation file. Use it
with --i18n-export or --i18n-import
--i18n-export=TRANSLATE_OUT
export all sentences to be translated to a CSV file, a
PO file or a TGZ archive and exit
--i18n-import=TRANSLATE_IN
import a CSV or a PO file with translations and exit.
The '-l' option is required.
--i18n-overwrite overwrites existing translation terms on updating a
module or importing a CSV or a PO file.
--modules=TRANSLATE_MODULES
specify modules to export. Use in combination with
--i18n-export
**Security-related options**::
--no-database-list disable the ability to return the list of databases
**Advanced options**::
--cache-timeout=CACHE_TIMEOUT
set the timeout for the cache system
--debug enable debug mode
--stop-after-init stop the server after its initialization
-t TIMEZONE, --timezone=TIMEZONE
specify reference timezone for the server (e.g.
Europe/Brussels
--osv-memory-count-limit=OSV_MEMORY_COUNT_LIMIT
Force a limit on the maximum number of records kept in
the virtual osv_memory tables. The default is False,
which means no count-based limit.
--osv-memory-age-limit=OSV_MEMORY_AGE_LIMIT
Force a limit on the maximum age of records kept in
the virtual osv_memory tables. This is a decimal value
expressed in hours, and the default is 1 hour.
--max-cron-threads=MAX_CRON_THREADS
Maximum number of threads processing concurrently cron
jobs.
--virtual-memory-limit=VIRTUAL_MEMORY_LIMIT
Maximum allowed virtual memory per Gunicorn process.
When the limit is reached, any memory allocation will
fail.
--virtual-memory-reset=VIRTUAL_MEMORY_RESET
Maximum allowed virtual memory per Gunicorn process.
When the limit is reached, the worker will be reset
after the current request.
--cpu-time-limit=CPU_TIME_LIMIT
Maximum allowed CPU time per Gunicorn process. When
the limit is reached, an exception is raised.
--unaccent Use the unaccent function provided by the database
when available.
Server configuration file
+++++++++++++++++++++++++
::
[options]
addons_path = /home/openerp/workspace/openerp-dev/addons/trunk,/home/openerp/workspace/openerp-dev/web/trunk/addons
admin_passwd = admin
cache_timeout = 100000
cpu_time_limit = 60
csv_internal_sep = ,
db_host = False
db_maxconn = 64
db_name = False
db_password = False
db_port = False
db_template = template0
db_user = openerp
dbfilter = .*
debug_mode = False
demo = {}
email_from = False
import_partial =
list_db = True
log_handler = [':INFO']
log_level = info
logfile = False
login_message = False
logrotate = True
max_cron_threads = 4
netrpc = True
netrpc_interface =
netrpc_port = 8070
osv_memory_age_limit = 1.0
osv_memory_count_limit = False
pg_path = None
pidfile = False
proxy_mode = False
reportgz = False
secure_cert_file = server.cert
secure_pkey_file = server.pkey
server_wide_modules = None
smtp_password = False
smtp_port = 25
smtp_server = localhost
smtp_ssl = False
smtp_user = False
static_http_document_root = None
static_http_enable = False
static_http_url_prefix = None
syslog = False
test_commit = False
test_enable = False
test_file = False
test_report_directory = False
timezone = False
translate_modules = ['all']
unaccent = False
virtual_memory_limit = 805306368
virtual_memory_reset = 671088640
without_demo = False
xmlrpc = True
xmlrpc_interface =
xmlrpc_port = 8069
xmlrpcs = True
xmlrpcs_interface =
xmlrpcs_port = 8071

73
doc/02_architecture.rst
View File

@ -33,16 +33,11 @@ three main components:
Another layer allows communications between the server and a web browser,
the Web layer. Having more than one server is possible, for example in
conjunction with a load balancing mechanism.
- the client, which allow users to access OpenERP. Two clients exist, a
desktop GTK client and a browser-based client
- the client running in the a web browser as javascript application.
- the GTK client access directly to the OpenERP Server
- users can also use standard web browsers to access OpenERP. In that
case, an OpenERP application is loaded. It handles communications between
the browser and the Web layer of the server.
The database server and the OpenERP server can be installed on the same computer,
or distributed onto separate computer servers, for example for performance considerations.
The database server and the OpenERP server can be installed on the same
computer, or distributed onto separate computer servers, for example for
performance considerations.
.. _`Figure 1`:
.. figure:: _static/02_openerp_architecture.png
@ -116,8 +111,9 @@ The services granted by the ORM are among other :
The web layer offers an interface to communicate with standard browsers.
In the 6.1 version of OpenERP, the web-client has been rewritten and integrated
into the OpenERP server tier. This layer relies on CherryPy for the routing
layer of communications, especially for session and cookies management.
into the OpenERP server tier. This web layer is a WSGI-compatible application
based on werkzeug. It handles regular http queries to server static file or
dynamic content and JSON-RPC queries for the RPC made from the browser.
**Modules**
@ -137,20 +133,8 @@ and display the result (e.g. a list of customers) in different ways
(as forms, lists, calendars, ...). Upon user actions, it sends queries
to modify data to the server.
Two clients can be used for user access to OpenERP, a GTK client and a
browser-based client. The GTK client communicates directly with the server.
Using the GTK client requires the client to be installed on the workstation
of each user.
The browser-based client holds an OpenERP application that handles communications
between the browser and the Web layer of the server. The static code of the web
application is minimal. It consists of a minimal flow of HTML that is in charge
of loading the application code in Javascript. This client-side OpenERP application
sends user requests to the server, and gets data back. Data management is
done dynamically in this client. Using this client is therefore easy for
users, but also for administrators because it does not require any software
installation on the user machine.
The default client of OpenERP is an JavaScript application running in the
browser that communicates with the server using JSON-RPC.
MVC architecture in OpenERP
===========================
@ -194,37 +178,32 @@ OpenERP follows the MVC semantic with
- view : views are defined in XML files in OpenERP.
- controller : The objects of OpenERP.
Network communications and WSGI
===============================
OpenERP is an HTTP web server and may also be deployed as an WSGI-compliant
application.
Network communications
======================
GTK clients communicate with the OpenERP server using XML-RPC protocol by
default. However, using a secured version XML-RPCS is possible when configurating
your OpenERP instance. In previous versions of OpenERP, a custom protocol
called NET-RPC was used. It was a binary version of the XML-RPC protocol,
allowing faster communications. However, this protocol will no longer be
used in OpenERP. The use of JSON-RPC is also planned for the 6.1 version
of OpenERP.
Web-based clients communicate using HTTP protocol. As for XML-RPC, it is
possible to configure OpenERP to use secured HTTPS connections.
Services and WSGI
=================
Clients may communicate with OpenERP using sessionless XML-RPC, the recommended
way to interoperate with OpenERP. Web-based clients communicates using the
session aware JSON-RPC.
Everything in OpenERP, and objects methods in particular, are exposed via
the network and a security layer. Access to the data model is in fact a ‘service’
and it is possible to expose new services. For instance, a WebDAV service and
a FTP service are available.
While not mandatory, the services can make use of the `WSGI
<http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface>`_ stack. WSGI is
a standard solution in the Python ecosystem to write HTTP servers, applications,
and middleware which can be used in a mix-and-match fashion. By using WSGI,
it is possible to run OpenERP in any WSGI compliant server. It is also
possible to use OpenERP to host a WSGI application.
Services can make use of the `WSGI
<http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface>`_ stack. WSGI is a
standard solution in the Python ecosystem to write HTTP servers, applications,
and middleware which can be used in a mix-and-match fashion. By using WSGI, it
is possible to run OpenERP in any WSGI compliant server. It is also possible to
use OpenERP to host a WSGI application.
A striking example of this possibility is the OpenERP Web layer that is
the server-side counter part to the web clients. It provides the requested
data to the browser and manages web sessions. It is a WSGI-compliant application.
As such, it can be run as a stand-alone HTTP server or embedded inside OpenERP.
The HTTP namespaces /openerp/ /object/ /common/ are reserved for the XML-RPC
layer, every module restrict it's HTTP namespace to /<name_of_the_module>/

349
doc/03_module_dev_01.rst
View File

@ -3,16 +3,15 @@ Module structure
A module can contain the following elements:
- **Business object** : declared as Python classes extending the OpenObject c
lass osv.Model, the persistence of these resource is completly managed
by OpenObject,
- **Business object** : declared as Python classes extending the class
osv.Model, the persistence of these resource is completly managed by
OpenERP's ORM.
- **Data** : XML/CSV files with meta-data (views and workflows declaration),
configuration data (modules parametrization) and demo data (optional but
recommended for testing),
- **Wizards** : stateful interactive forms used to assist users, often available
as contextual actions on resources,
- **Reports** : RML (XML format). MAKO or OpenOffice report templates, to be
merged with any kind of business data, and generate HTML, ODT or PDF reports.
- **Reports** : RML (XML format). HTML/MAKO or OpenOffice report templates, to
be merged with any kind of business data, and generate HTML, ODT or PDF
reports.
.. figure:: _static/03_module_gen_view.png
:width: 75%
@ -23,120 +22,91 @@ A module can contain the following elements:
Each module is contained in its own directory within either the server/bin/addons
directory or another directory of addons, configured in server installation.
To create a new module, the following steps are required:
To create a new module for example the 'OpenAcademy' module, the following
steps are required:
- create a ``my_module`` subdirectory in the source/addons directory
- create the module description file ``__init__.py``
- create the module declaration file ``__openerp__.py``
- create a ``openacademy`` subdirectory in the source/addons directory
- create the module import file ``__init__.py``
- create the module manifield file ``__openerp__.py``
- create **Python** files containing **objects**
- create **.xml files** holding module data such as views, menu entries
or demo data
- optionally create **reports**, **wizards** or **workflows**
- optionally create **reports** or **workflows**
Description file __init__.py
++++++++++++++++++++++++++++
Python import file __init__.py
++++++++++++++++++++++++++++++
The ``__init__.py`` file is the Python module descriptor, because an OpenERP
module is also a regular Python module. Like any Python module, it is executed
at program start. It needs to import the Python files that need to be loaded.
The ``__init__.py`` file is the Python import file, because an OpenERP module
is also a regular Python module. The file should import all the other python
file or submodules.
It contains the importation instruction applied to all Python files of the
module, without the .py extension. For example, if a module contains a single
python file named ``mymodule.py``, the file should look like:
For example, if a module contains a single python file named ``openacademy.py``,
the file should look like:
import module
import openacademy
Declaration file __openerp__.py
Manifest file __openerp__.py
+++++++++++++++++++++++++++++++
In the created module directory, you must add a **__openerp__.py** file.
This file, which must be in Python format, is responsible to
This file, which must be a Python dict literal, is responsible to
1. determine the *XML files that will be parsed* during the initialization
of the server, and also to
2. determine the *dependencies* of the created module.
3. declare additional meta data
This file must contain a Python dictionary with the following values:
::
name The (Plain English) name of the module.
name The name of the module in English.
version The version of the module.
summary Short description or keywords
description The module description (text).
category The categrory of the module
author The author of the module.
website The website of the module.
license The license of the module (default:GPL-2).
depends List of modules on which this module depends. The base
module must almost always be in the dependencies because
some necessary data for the views, reports, ... are in
the base module.
init_xml List of .xml files to load when the server is launched
with the "--init=module" argument. Filepaths must be
relative to the directory where the module is. OpenERP
XML file format is detailed in this section.
update_xml List of .xml files to load when the server is launched with
the "--update=module" launched. Filepaths must be relative
to the directory where the module is. Files in **update_xml**
concern: views, reports and wizards.
website URL of the website of the module.
license The license of the module (default: AGPL-3).
depends List of modules on which this module depends beside base.
data List of .xml files to load when the module is installed or updated.
demo List of additional .xml files to load when the module is
installed or updated and demo flag is active.
installable True or False. Determines whether the module is installable
or not.
auto_install True or False (default: False). If set to ``True``, the
module is a link module. It will be installed as soon
as all its dependencies are installed.
For the ``my_module`` module, here is an example of ``__openerp__.py``
For the ``openacademy`` module, here is an example of ``__openerp__.py``
declaration file:
.. code-block:: python
{
'name' : "My Module",
'name' : "OpenAcademy",
'version' : "1.0",
'author' : "OpenERP",
'author' : "OpenERP SA",
'category' : "Tools",
'depends' : ['base',],
'init_xml' : [],
'demo_xml' : [
'module_demo.xml'
],
'update_xml' : [
'module_view.xml',
'data/module_data.xml',
'depends' : ['mail'],
'data' : [
'openacademy_view.xml',
'openacademy_data.xml',
'report/module_report.xml',
'wizard/module_wizard.xml',
],
'demo' : [
'openacademy_demo.xml'
],
'installable': True,
'auto_install': False,
}
The files that must be placed in init_xml are the ones that relate to the
workflow definition, data to load at the installation of the software and
the data for the demonstrations.
XML Files
+++++++++
XML files located in the module directory are used to modify the structure of
the database. They are used for many purposes, among which we can cite :
* initialization and demonstration data declaration,
* views declaration,
* reports declaration,
* wizards declaration,
* workflows declaration.
General structure of OpenERP XML files is more detailed in the
:ref:`xml-serialization` section. Look here if you are interested in learning
more about *initialization* and *demonstration data declaration* XML files. The
following section are only related to XML specific to *actions, menu entries,
reports, wizards* and *workflows* declaration.
Objects
+++++++
All OpenERP resources are objects: menus, actions, reports, invoices, partners, ... OpenERP is based on an object relational mapping of a database to control the information. Object names are hierarchical, as in the following examples:
All OpenERP resources are objects: invoices, partners. Metadata are also object
too: menus, actions, reports... Object names are hierarchical, as in the
following examples:
* account.transfer : a money transfer
* account.invoice : an invoice
@ -144,14 +114,15 @@ All OpenERP resources are objects: menus, actions, reports, invoices, partners,
Generally, the first word is the name of the module: account, stock, sale.
Other advantages of an ORM;
Those object are declared in python be subclassing osv.Model
* simpler relations : invoice.partner.address[0].city
* objects have properties and methods: invoice.pay(3400 EUR),
* inheritance, high level constraints, ...
It is easier to manipulate one object (example, a partner) than several tables (partner address, categories, events, ...)
The ORM of OpenERP is constructed over PostgreSQL. It is thus possible to
query the object used by OpenERP using the object interface (ORM) or by
directly using SQL statements.
But it is dangerous to write or read directly in the PostgreSQL database, as
you will shortcut important steps like constraints checking or workflow
modification.
.. figure:: images/pom_3_0_3.png
:scale: 50
@ -160,23 +131,23 @@ It is easier to manipulate one object (example, a partner) than several tables (
*The Physical Objects Model of [OpenERP version 3.0.3]*
PostgreSQL and ORM
------------------
XML Files
+++++++++
The ORM of OpenERP is constructed over PostgreSQL. It is thus possible to
query the object used by OpenERP using the object interface or by directly
using SQL statements.
XML files located in the module directory are used to initialize or update the
the database when the module is installed or updated. They are used for many
purposes, among which we can cite :
But it is dangerous to write or read directly in the PostgreSQL database, as
you will shortcut important steps like constraints checking or workflow
modification.
* initialization and demonstration data declaration,
* views declaration,
* reports declaration,
* workflows declaration.
.. note::
The Physical Database Model of OpenERP
Pre-Installed Data
------------------
General structure of OpenERP XML files is more detailed in the
:ref:`xml-serialization` section. Look here if you are interested in learning
more about *initialization* and *demonstration data declaration* XML files. The
following section are only related to XML specific to *actions, menu entries,
reports, wizards* and *workflows* declaration.
Data can be inserted or updated into the PostgreSQL tables corresponding to the
OpenERP objects using XML files. The general structure of an OpenERP XML file
@ -188,12 +159,8 @@ is as follows:
<openerp>
<data>
<record model="model.name_1" id="id_name_1">
<field name="field1">
"field1 content"
</field>
<field name="field2">
"field2 content"
</field>
<field name="field1"> "field1 content" </field>
<field name="field2"> "field2 content" </field>
(...)
</record>
<record model="model.name_2" id="id_name_2">
@ -203,7 +170,52 @@ is as follows:
</data>
</openerp>
Fields content are strings that must be encoded as *UTF-8* in XML files.
Record Tag
//////////
**Description**
The addition of new data is made with the record tag. This one takes a
mandatory attribute : model. Model is the object name where the insertion has
to be done. The tag record can also take an optional attribute: id. If this
attribute is given, a variable of this name can be used later on, in the same
file, to make reference to the newly created resource ID.
A record tag may contain field tags. They indicate the record's fields value.
If a field is not specified the default value will be used.
The Record Field tag
////////////////////
The attributes for the field tag are the following:
name : mandatory
the field name
eval : optional
python expression that indicating the value to add
ref
reference to an id defined in this file
model
model to be looked up in the search
search
a query
**Example**
.. code-block:: xml
<record model="ir.actions.report.xml" id="l0">
<field name="model">account.invoice</field>
<field name="name">Invoices List</field>
<field name="report_name">account.invoice.list</field>
<field name="report_xsl">account/report/invoice.xsl</field>
<field name="report_xml">account/report/invoice.xml</field>
</record>
Let's review an example taken from the OpenERP source (base_demo.xml in the base module):
@ -250,47 +262,6 @@ The field **company_id** is a many-to-one relation from the user object to the c
This is a classical example of the use of **search** in demo data: here we do not really care about which partner we want to use for the test, so we give an empty list. Notice the **model** attribute is currently mandatory.
Record Tag
//////////
**Description**
The addition of new data is made with the record tag. This one takes a mandatory attribute : model. Model is the object name where the insertion has to be done. The tag record can also take an optional attribute: id. If this attribute is given, a variable of this name can be used later on, in the same file, to make reference to the newly created resource ID.
A record tag may contain field tags. They indicate the record's fields value. If a field is not specified the default value will be used.
**Example**
.. code-block:: xml
<record model="ir.actions.report.xml" id="l0">
<field name="model">account.invoice</field>
<field name="name">Invoices List</field>
<field name="report_name">account.invoice.list</field>
<field name="report_xsl">account/report/invoice.xsl</field>
<field name="report_xml">account/report/invoice.xml</field>
</record>
Field tag
/////////
The attributes for the field tag are the following:
name : mandatory
the field name
eval : optional
python expression that indicating the value to add
ref
reference to an id defined in this file
model
model to be looked up in the search
search
a query
Function tag
////////////
@ -311,69 +282,9 @@ eval
<function model="ir.ui.menu" name="search" eval="[[('name','=','Operations')]]"/>
Getitem tag
///////////
Takes a subset of the evaluation of the last child node of the tag.
type : mandatory
int or list
index : mandatory
int or string (a key of a dictionary)
**Example**
Evaluates to the first element of the list of ids returned by the function node
.. code-block:: xml
<getitem index="0" type="list">
<function model="ir.ui.menu" name="search" eval="[[('name','=','Operations')]]"/>
</getitem>
i18n
""""
Improving Translations
//////////////////////
.. describe:: Translating in launchpad
Translations are managed by
the `Launchpad Web interface <https://translations.launchpad.net/openobject>`_. Here, you'll
find the list of translatable projects.
Please read the `FAQ <https://answers.launchpad.net/rosetta/+faqs>`_ before asking questions.
.. describe:: Translating your own module
.. versionchanged:: 5.0
Contrary to the 4.2.x version, the translations are now done by module. So,
instead of an unique ``i18n`` folder for the whole application, each module has
its own ``i18n`` folder. In addition, OpenERP can now deal with ``.po`` [#f_po]_
files as import/export format. The translation files of the installed languages
are automatically loaded when installing or updating a module. OpenERP can also
generate a .tgz archive containing well organised ``.po`` files for each selected
module.
.. [#f_po] http://www.gnu.org/software/autoconf/manual/gettext/PO-Files.html#PO-Files
Process
"""""""
Defining the process
////////////////////
Through the interface and module recorder.
Then, put the generated XML in your own module.
Views
"""""
Technical Specifications - Architecture - Views
///////////////////////////////////////////////
+++++
Views are a way to represent the objects on the client side. They indicate to the client how to lay out the data coming from the objects on the screen.
@ -454,21 +365,23 @@ The squared nodes represent other Workflows;
* the shipping
i18n
----
Appendix
+++++++++
.. versionchanged:: 5.0
Configure addons locations
--------------------------
Each module has its own ``i18n`` folder. In addition, OpenERP can now deal with
``.po`` [#f_po]_ files as import/export format. The translation files of the
installed languages are automatically loaded when installing or updating a
module.
Translations are managed by the `Launchpad Web interface
<https://translations.launchpad.net/openobject>`_. Here, you'll find the list
of translatable projects.
Please read the `FAQ <https://answers.launchpad.net/rosetta/+faqs>`_ before asking questions.
.. [#f_po] http://www.gnu.org/software/autoconf/manual/gettext/PO-Files.html#PO-Files
By default, the only directory of addons known by the server is server/bin/addons.
It is possible to add new addons by
- copying them in server/bin/addons, or creating a symbolic link to each
of them in this directory, or
- specifying another directory containing addons to the server. The later
can be accomplished either by running the server with the ``--addons-path=``
option, or by configuring this option in the openerp_serverrc file,
automatically generated under Linux in your home directory by the
server when executed with the ``--save`` option. You can provide several
addons to the ``addons_path`` = option, separating them using commas.

286
doc/03_module_dev_03.rst
View File

@ -4,15 +4,24 @@ Views and Events
Introduction to Views
---------------------
As all data of the program is stored in objects, as explained in the Objects section, how are these objects exposed to the user ? We will try to answer this question in this section.
As all data of the program is stored in objects, as explained in the Objects
section, how are these objects exposed to the user ? We will try to answer this
question in this section.
First of all, let's note that every resource type uses its own interface. For example, the screen to modify a partner's data is not the same as the one to modify an invoice.
First of all, let's note that every resource type uses its own interface. For
example, the screen to modify a partner's data is not the same as the one to
modify an invoice.
Then, you have to know that the OpenERP user interface is dynamic, it means that it is not described "statically" by some code, but dynamically built from XML descriptions of the client screens.
Then, you have to know that the OpenERP user interface is dynamic, it means
that it is not described "statically" by some code, but dynamically built from
XML descriptions of the client screens.
From now on, we will call these screen descriptions views.
A notable characteristic of these views is that they can be edited at any moment (even during the program execution). After a modification to a displayed view has occurred, you simply need to close the tab corresponding to that 'view' and re-open it for the changes to appear.
A notable characteristic of these views is that they can be edited at any
moment (even during the program execution). After a modification to a displayed
view has occurred, you simply need to close the tab corresponding to that
'view' and re-open it for the changes to appear.
Views principles
++++++++++++++++
@ -57,9 +66,66 @@ As we can see below in the purple zone of the screen, there is also a way to dis
:scale: 50
:align: center
On Change
+++++++++
The on_change attribute defines a method that is called when the content of a view field has changed.
This method takes at least arguments: cr, uid, ids, which are the three classical arguments and also the context dictionary. You can add parameters to the method. They must correspond to other fields defined in the view, and must also be defined in the XML with fields defined this way::
<field name="name_of_field" on_change="name_of_method(other_field'_1_', ..., other_field'_n_')"/>
The example below is from the sale order view.
You can use the 'context' keyword to access data in the context that can be used as params of the function.::
<field name="shop_id" on_change="onchange_shop_id(shop_id)"/>
.. code-block:: python
def onchange_shop_id(self, cr, uid, ids, shop_id):
v={}
if shop_id:
shop=self.pool.get('sale.shop').browse(cr,uid,shop_id)
v['project_id']=shop.project_id.id
if shop.pricelist_id.id:
v['pricelist_id']=shop.pricelist_id.id
v['payment_default_id']=shop.payment_default_id.id
return {'value':v}
When editing the shop_id form field, the onchange_shop_id method of the sale_order object is called and returns a dictionary where the 'value' key contains a dictionary of the new value to use in the 'project_id', 'pricelist_id' and 'payment_default_id' fields.
Note that it is possible to change more than just the values of
fields. For example, it is possible to change the value of some fields
and the domain of other fields by returning a value of the form:
return {'domain': d, 'value': value}
:returns: a dictionary with any mix of the following keys:
``domain``
A mapping of ``{field: domain}``.
The returned domains should be set on the fields instead of the
default ones.
``value``
A mapping of ``{field: value}}``, the values will be set on the
corresponding fields and may trigger new onchanges or attrs
changes
``warning`` A dict with the keys ``title`` and ``message``. Both
are mandatory. Indicate that an error message should be
displayed to the user.
Tree views
-----------
----------
These views are used when we work in list mode (in order to visualize several resources at once) and in the search screen. These views are simpler than the form views and thus have less options.
@ -67,81 +133,6 @@ These views are used when we work in list mode (in order to visualize several re
:scale: 50
:align: center
Graph views
--------------
A graph is a new mode of view for all views of type form. If, for example, a sale order line must be visible as list or as graph, define it like this in the action that open this sale order line. Do not set the view mode as "tree,form,graph" or "form,graph" - it must be "graph,tree" to show the graph first or "tree,graph" to show the list first. (This view mode is extra to your "form,tree" view and should have a separate menu item):
.. code-block:: xml
<field name="view_type">form</field>
<field name="view_mode">tree,graph</field>
view_type::
tree = (tree with shortcuts at the left), form = (switchable view form/list)
view_mode::
tree,graph : sequences of the views when switching
Then, the user will be able to switch from one view to the other. Unlike forms and trees, OpenERP is not able to automatically create a view on demand for the graph type. So, you must define a view for this graph:
.. code-block:: xml
<record model="ir.ui.view" id="view_order_line_graph">
<field name="name">sale.order.line.graph</field>
<field name="model">sale.order.line</field>
<field name="type">graph</field>
<field name="arch" type="xml">
<graph string="Sales Order Lines">
<field name="product_id" group="True"/>
<field name="price_unit" operator="*"/>
</graph>
</field>
</record>
The graph view
A view of type graph is just a list of fields for the graph.
Graph tag
++++++++++
The default type of the graph is a pie chart - to change it to a barchart change **<graph string="Sales Order Lines">** to **<graph string="Sales Order Lines" type="bar">** You also may change the orientation.
:Example :
.. code-block:: xml
<graph string="Sales Order Lines" orientation="horizontal" type="bar">
Field tag
+++++++++
The first field is the X axis. The second one is the Y axis and the optional third one is the Z axis for 3 dimensional graphs. You can apply a few attributes to each field/axis:
* **group**: if set to true, the client will group all item of the same value for this field. For each other field, it will apply an operator
* **operator**: the operator to apply is another field is grouped. By default it's '+'. Allowed values are:
+ +: addition
+ \*: multiply
+ \**: exponent
+ min: minimum of the list
+ max: maximum of the list
:Defining real statistics on objects:
The easiest method to compute real statistics on objects is:
1. Define a statistic object which is a postgresql view
2. Create a tree view and a graph view on this object
You can get en example in all modules of the form: report\_.... Example: report_crm.
Search views
--------------
@ -320,6 +311,82 @@ We can save this search criteria as a Shortcut or save as Filter.
Filters are user specific and can be modified via the Manage Filters option in the filters drop-down.
Graph views
-----------
A graph is a new mode of view for all views of type form. If, for example, a sale order line must be visible as list or as graph, define it like this in the action that open this sale order line. Do not set the view mode as "tree,form,graph" or "form,graph" - it must be "graph,tree" to show the graph first or "tree,graph" to show the list first. (This view mode is extra to your "form,tree" view and should have a separate menu item):
.. code-block:: xml
<field name="view_type">form</field>
<field name="view_mode">tree,graph</field>
view_type::
tree = (tree with shortcuts at the left), form = (switchable view form/list)
view_mode::
tree,graph : sequences of the views when switching
Then, the user will be able to switch from one view to the other. Unlike forms and trees, OpenERP is not able to automatically create a view on demand for the graph type. So, you must define a view for this graph:
.. code-block:: xml
<record model="ir.ui.view" id="view_order_line_graph">
<field name="name">sale.order.line.graph</field>
<field name="model">sale.order.line</field>
<field name="type">graph</field>
<field name="arch" type="xml">
<graph string="Sales Order Lines">
<field name="product_id" group="True"/>
<field name="price_unit" operator="*"/>
</graph>
</field>
</record>
The graph view
A view of type graph is just a list of fields for the graph.
Graph tag
++++++++++
The default type of the graph is a pie chart - to change it to a barchart change **<graph string="Sales Order Lines">** to **<graph string="Sales Order Lines" type="bar">** You also may change the orientation.
:Example :
.. code-block:: xml
<graph string="Sales Order Lines" orientation="horizontal" type="bar">
Field tag
+++++++++
The first field is the X axis. The second one is the Y axis and the optional third one is the Z axis for 3 dimensional graphs. You can apply a few attributes to each field/axis:
* **group**: if set to true, the client will group all item of the same value for this field. For each other field, it will apply an operator
* **operator**: the operator to apply is another field is grouped. By default it's '+'. Allowed values are:
+ +: addition
+ \*: multiply
+ \**: exponent
+ min: minimum of the list
+ max: maximum of the list
:Defining real statistics on objects:
The easiest method to compute real statistics on objects is:
1. Define a statistic object which is a postgresql view
2. Create a tree view and a graph view on this object
You can get en example in all modules of the form: report\_.... Example: report_crm.
Calendar Views
--------------
@ -1367,62 +1434,3 @@ flexible if you define the child views separately and then specify which child
view to use as part of the one2many field.
Events
------
On Change
+++++++++
The on_change attribute defines a method that is called when the content of a view field has changed.
This method takes at least arguments: cr, uid, ids, which are the three classical arguments and also the context dictionary. You can add parameters to the method. They must correspond to other fields defined in the view, and must also be defined in the XML with fields defined this way::
<field name="name_of_field" on_change="name_of_method(other_field'_1_', ..., other_field'_n_')"/>
The example below is from the sale order view.
You can use the 'context' keyword to access data in the context that can be used as params of the function.::
<field name="shop_id" on_change="onchange_shop_id(shop_id)"/>
.. code-block:: python
def onchange_shop_id(self, cr, uid, ids, shop_id):
v={}
if shop_id:
shop=self.pool.get('sale.shop').browse(cr,uid,shop_id)
v['project_id']=shop.project_id.id
if shop.pricelist_id.id:
v['pricelist_id']=shop.pricelist_id.id
v['payment_default_id']=shop.payment_default_id.id
return {'value':v}
When editing the shop_id form field, the onchange_shop_id method of the sale_order object is called and returns a dictionary where the 'value' key contains a dictionary of the new value to use in the 'project_id', 'pricelist_id' and 'payment_default_id' fields.
Note that it is possible to change more than just the values of
fields. For example, it is possible to change the value of some fields
and the domain of other fields by returning a value of the form:
return {'domain': d, 'value': value}
:returns: a dictionary with any mix of the following keys:
``domain``
A mapping of ``{field: domain}``.
The returned domains should be set on the fields instead of the
default ones.
``value``
A mapping of ``{field: value}}``, the values will be set on the
corresponding fields and may trigger new onchanges or attrs
changes
``warning`` A dict with the keys ``title`` and ``message``. Both
are mandatory. Indicate that an error message should be
displayed to the user.