2
.. i18n: Developing modules
3
.. i18n: -------------------
10
.. i18n: single: modules development
15
single: modules development
25
.. i18n: Here you will found informations about the organisation of the community in
26
.. i18n: OpenERP project. It include a description of the different tools used, the role
27
.. i18n: of the differents actors, and the different process for improvement management.
30
Here you will found informations about the organisation of the community in
31
OpenERP project. It include a description of the different tools used, the role
32
of the differents actors, and the different process for improvement management.
34
.. i18n: The whole organisation is managed through our launchpad projects: http://launchpad.net
35
.. i18n: Our projects on launchpad are currently organised like this:
38
The whole organisation is managed through our launchpad projects: http://launchpad.net
39
Our projects on launchpad are currently organised like this:
41
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
42
.. i18n: | **Project name** | **URL** | **Description** |
43
.. i18n: +============================+==============================================+============================================+
45
.. i18n: | **openobject** | https://launchpad.net/openobject | the main super-project (group) where all |
46
.. i18n: | | | bugs, features and faq are managed |
48
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
50
.. i18n: | **openobject-bi** | https://launchpad.net/openobject-bin | business intelligence project |
52
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
54
.. i18n: | **openobject-server** | https://launchpad.net/openobject-server | the openobject server |
56
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
58
.. i18n: | **openobject-client** | https://launchpad.net/openobject-client | the openobject application client (gtk) |
60
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
62
.. i18n: | **openobject-client-web** | https://launchpad.net/openobject-client-web | the openobject web client (previously |
63
.. i18n: | | | called eTiny) |
65
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
67
.. i18n: | **openobject-addons** | https://launchpad.net/openobject-addons | the project for all modules about |
68
.. i18n: | | | openobject |
70
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
72
.. i18n: | **openerp** | https://launchpad.net/openerp | packaging around openobject (a selection |
73
.. i18n: | | | of modules to build applications) |
75
.. i18n: +----------------------------+----------------------------------------------+--------------------------------------------+
78
+----------------------------+----------------------------------------------+--------------------------------------------+
79
| **Project name** | **URL** | **Description** |
80
+============================+==============================================+============================================+
82
| **openobject** | https://launchpad.net/openobject | the main super-project (group) where all |
83
| | | bugs, features and faq are managed |
85
+----------------------------+----------------------------------------------+--------------------------------------------+
87
| **openobject-bi** | https://launchpad.net/openobject-bin | business intelligence project |
89
+----------------------------+----------------------------------------------+--------------------------------------------+
91
| **openobject-server** | https://launchpad.net/openobject-server | the openobject server |
93
+----------------------------+----------------------------------------------+--------------------------------------------+
95
| **openobject-client** | https://launchpad.net/openobject-client | the openobject application client (gtk) |
97
+----------------------------+----------------------------------------------+--------------------------------------------+
99
| **openobject-client-web** | https://launchpad.net/openobject-client-web | the openobject web client (previously |
100
| | | called eTiny) |
102
+----------------------------+----------------------------------------------+--------------------------------------------+
104
| **openobject-addons** | https://launchpad.net/openobject-addons | the project for all modules about |
107
+----------------------------+----------------------------------------------+--------------------------------------------+
109
| **openerp** | https://launchpad.net/openerp | packaging around openobject (a selection |
110
| | | of modules to build applications) |
112
+----------------------------+----------------------------------------------+--------------------------------------------+
114
.. i18n: Getting Sources
115
.. i18n: +++++++++++++++
121
.. i18n: Please refer to :ref:`how-to-get-the-latest-trunk-source-code-link` in the Bazaar section
124
Please refer to :ref:`how-to-get-the-latest-trunk-source-code-link` in the Bazaar section
126
.. i18n: If you don't know the Bazaar version control system, please read the :ref:`documentation on Bazaar <bazaar-link>`
129
If you don't know the Bazaar version control system, please read the :ref:`documentation on Bazaar <bazaar-link>`
131
.. i18n: Coding Guidelines
132
.. i18n: +++++++++++++++++
138
.. i18n: Development Guidelines
139
.. i18n: """"""""""""""""""""""
142
Development Guidelines
143
""""""""""""""""""""""
152
.. i18n: Organisation of files in modules
153
.. i18n: ################################
156
Organisation of files in modules
157
################################
159
.. i18n: .. === Organisation of files in modules ===
162
.. === Organisation of files in modules ===
164
.. i18n: The structure of a module should be like this::
166
.. i18n: /module_name/
167
.. i18n: /module_name/__init__.py
168
.. i18n: /module_name/__terp__.py
169
.. i18n: /module_name/module.py
170
.. i18n: /module_name/module_view.xml
171
.. i18n: /module_name/module_wizard.xml
172
.. i18n: /module_name/module_report.xml
173
.. i18n: /module_name/module_data.xml
174
.. i18n: /module_name/module_demo.xml
175
.. i18n: /module_name/module_security.xml
176
.. i18n: /module_name/wizard/
177
.. i18n: /module_name/wizard/__init__.py
178
.. i18n: /module_name/wizard/wizard_name.py
179
.. i18n: /module_name/wizard/wizard_name_view.xml
180
.. i18n: /module_name/wizard/wizard_name_workflow.xml
181
.. i18n: /module_name/report/
182
.. i18n: /module_name/report/__init__.py
183
.. i18n: /module_name/report/report_name.sxw
184
.. i18n: /module_name/report/report_name.rml
185
.. i18n: /module_name/report/report_name.py
188
The structure of a module should be like this::
191
/module_name/__init__.py
192
/module_name/__terp__.py
193
/module_name/module.py
194
/module_name/module_view.xml
195
/module_name/module_wizard.xml
196
/module_name/module_report.xml
197
/module_name/module_data.xml
198
/module_name/module_demo.xml
199
/module_name/module_security.xml
201
/module_name/wizard/__init__.py
202
/module_name/wizard/wizard_name.py
203
/module_name/wizard/wizard_name_view.xml
204
/module_name/wizard/wizard_name_workflow.xml
206
/module_name/report/__init__.py
207
/module_name/report/report_name.sxw
208
/module_name/report/report_name.rml
209
/module_name/report/report_name.py
211
.. i18n: Objects and fields namings
212
.. i18n: ##########################
215
Objects and fields namings
216
##########################
225
.. i18n: Each object defined in your module must have at least one security rule
226
.. i18n: defined on it to make it accessible.
229
Each object defined in your module must have at least one security rule
230
defined on it to make it accessible.
239
.. i18n: Coding Guidelines
240
.. i18n: #################
246
.. i18n: Follow Python PEP 8: http://www.python.org/dev/peps/pep-0008/
249
Follow Python PEP 8: http://www.python.org/dev/peps/pep-0008/
258
.. i18n: General Style
259
.. i18n: #############
265
.. i18n: * use the Helvetica font everywhere
266
.. i18n: * margins (in millimeters):
269
.. i18n: - bottom: 16
270
.. i18n: - left: between 12 and 13 to allow punching holes without punching in the text area
271
.. i18n: - right: between 12 and 13
274
* use the Helvetica font everywhere
275
* margins (in millimeters):
279
- left: between 12 and 13 to allow punching holes without punching in the text area
280
- right: between 12 and 13
282
.. i18n: .. note:: the line separator between the header and the body can overlap slightly in the left and right margins: up to 9 millimeters on the left and up to 12 millimeters on the right
284
.. i18n: * for Titles use the font *Heveltica-Bold* with the size *14.5*
286
.. i18n: * put the context on each report: example, for the report account_balance: the context is the fiscal year and periods
288
.. i18n: * for the name of cells: use Capital Letter if the name contains more than one word (ex: Date Ordered)
289
.. i18n: * content and name of cells should have the same indentation
291
.. i18n: * for report, we can define two kinds of arrays:
293
.. i18n: - array with general information, like reference, date..., use:
295
.. i18n: + *Bold-Helvetica* and size=8 for cells name
296
.. i18n: + *Helvetica* size="8" for content
298
.. i18n: - array with detailed information, use:
300
.. i18n: + *Helvetica-Bold* size *9* for cells names
301
.. i18n: + *Helvetica* size *8* for content
304
.. note:: the line separator between the header and the body can overlap slightly in the left and right margins: up to 9 millimeters on the left and up to 12 millimeters on the right
306
* for Titles use the font *Heveltica-Bold* with the size *14.5*
308
* put the context on each report: example, for the report account_balance: the context is the fiscal year and periods
310
* for the name of cells: use Capital Letter if the name contains more than one word (ex: Date Ordered)
311
* content and name of cells should have the same indentation
313
* for report, we can define two kinds of arrays:
315
- array with general information, like reference, date..., use:
317
+ *Bold-Helvetica* and size=8 for cells name
318
+ *Helvetica* size="8" for content
320
- array with detailed information, use:
322
+ *Helvetica-Bold* size *9* for cells names
323
+ *Helvetica* size *8* for content
325
.. i18n: .. describe:: Headers and footers for internal reports:
327
.. i18n: * Internal report = all accounting reports and other that have only internal use (not sent to customers)
328
.. i18n: * height of headers should be shorter
329
.. i18n: * take off corporate header and footer for internal report (Use a simplified header for internal reports: Company's name, report title, printing date and page number)
333
.. i18n: - company's name: in the middle of each page
334
.. i18n: - report's name: is printed centered after the header
335
.. i18n: - printing date: not in the middle of the report, but on the left in the header
336
.. i18n: - page number: on each page, is printed on the right. This page number should contain the current page number and the total of pages. Ex: page 3/15
339
.. i18n: - to avoid wasting paper, we have taken off the footer
342
.. describe:: Headers and footers for internal reports:
344
* Internal report = all accounting reports and other that have only internal use (not sent to customers)
345
* height of headers should be shorter
346
* take off corporate header and footer for internal report (Use a simplified header for internal reports: Company's name, report title, printing date and page number)
350
- company's name: in the middle of each page
351
- report's name: is printed centered after the header
352
- printing date: not in the middle of the report, but on the left in the header
353
- page number: on each page, is printed on the right. This page number should contain the current page number and the total of pages. Ex: page 3/15
356
- to avoid wasting paper, we have taken off the footer
358
.. i18n: .. describe:: table line separator:
361
.. describe:: table line separator:
363
.. i18n: * it's prettier if each line in the table have a light grey line as separator
364
.. i18n: * use a grey column separator only for array containing general information
367
* it's prettier if each line in the table have a light grey line as separator
368
* use a grey column separator only for array containing general information
370
.. i18n: .. describe:: table breaking
372
.. i18n: * a table header should at least have two data rows (no table header alone at the bottom of the page)
373
.. i18n: * when a big table is broken, the table header is repeated on every page
376
.. describe:: table breaking
378
* a table header should at least have two data rows (no table header alone at the bottom of the page)
379
* when a big table is broken, the table header is repeated on every page
381
.. i18n: .. describe:: how to differentiate parents and children ?
383
.. i18n: * When you have more than one level, use these styles:
385
.. i18n: - for the levels 1 and 2:fontSize="8.0" fontName="Helvetica-Bold"
386
.. i18n: - from the third level, use:fontName="Helvetica" fontSize="8.0" and increase the indentation with 13 (pixels) for each level
387
.. i18n: - underline sums when the element is a parent
390
.. describe:: how to differentiate parents and children ?
392
* When you have more than one level, use these styles:
394
- for the levels 1 and 2:fontSize="8.0" fontName="Helvetica-Bold"
395
- from the third level, use:fontName="Helvetica" fontSize="8.0" and increase the indentation with 13 (pixels) for each level
396
- underline sums when the element is a parent
405
.. i18n: Naming Convention
406
.. i18n: ^^^^^^^^^^^^^^^^^
412
.. i18n: The name of the module are all lowercase, each word separated by underscrores.
413
.. i18n: Start always by the most relevant words, which are preferably names of others
414
.. i18n: modules on which it depends.
417
The name of the module are all lowercase, each word separated by underscrores.
418
Start always by the most relevant words, which are preferably names of others
419
modules on which it depends.
426
.. i18n: * account_invoice_layout
429
* account_invoice_layout
431
.. i18n: Information Required
432
.. i18n: ^^^^^^^^^^^^^^^^^^^^
438
.. i18n: Each module must contains at least:
441
Each module must contains at least:
444
.. i18n: * description
450
.. i18n: Modules Description
451
.. i18n: ^^^^^^^^^^^^^^^^^^^
457
.. i18n: Dependencies
458
.. i18n: ^^^^^^^^^^^^
464
.. i18n: Each module must contains:
467
Each module must contains:
469
.. i18n: * A list of dependencies amongst others modules: ['account','sale']
471
.. i18n: - Provide only highest requirement level, not need to set ['account','base','product','sale']
472
.. i18n: * A version requirement string where base is the OpenERP version as a Python expression
474
.. i18n: - account>=1.0 && base=4.4
477
* A list of dependencies amongst others modules: ['account','sale']
479
- Provide only highest requirement level, not need to set ['account','base','product','sale']
480
* A version requirement string where base is the OpenERP version as a Python expression
482
- account>=1.0 && base=4.4
484
.. i18n: Module Content
485
.. i18n: ^^^^^^^^^^^^^^
491
.. i18n: Each module must contains dema data for every object defined in the module.
494
Each module must contains dema data for every object defined in the module.
496
.. i18n: If you implemented workflows in the module, create demo data that passes
497
.. i18n: most branches of your workflow. You can use the module recorder to help you
498
.. i18n: build such demo data.
501
If you implemented workflows in the module, create demo data that passes
502
most branches of your workflow. You can use the module recorder to help you
503
build such demo data.
505
.. i18n: User Interface Guidelines
506
.. i18n: """""""""""""""""""""""""
509
User Interface Guidelines
510
"""""""""""""""""""""""""
519
.. i18n: Organising menus
520
.. i18n: ################
526
.. i18n: Here is a good example:
529
Here is a good example:
531
.. i18n: * Invoices (list)
533
.. i18n: - Customer Invoices (list)
538
- Customer Invoices (list)
540
.. i18n: + Draft Customer Invoices (list)
541
.. i18n: + Open Customer Invoices (list)
542
.. i18n: + New Customer Invoice (form)
543
.. i18n: - Supplier Invoices
546
+ Draft Customer Invoices (list)
547
+ Open Customer Invoices (list)
548
+ New Customer Invoice (form)
556
.. i18n: Add a *New ...* menu only if the user requires it, otherwise, open all
557
.. i18n: menus as lists. The *New ...* menu open as a form instead of a list. For example,
558
.. i18n: don't put *New ...* in a menu in the configuration part.
561
Add a *New ...* menu only if the user requires it, otherwise, open all
562
menus as lists. The *New ...* menu open as a form instead of a list. For example,
563
don't put *New ...* in a menu in the configuration part.
565
.. i18n: If you use folders that are clickable, their child must be of the
566
.. i18n: same object type. (we suppose that inheritancies are the same objects)
569
If you use folders that are clickable, their child must be of the
570
same object type. (we suppose that inheritancies are the same objects)
572
.. i18n: List are plurals:
577
.. i18n: * *Customer Invoice*, should be *Customer Invoices*
580
* *Customer Invoice*, should be *Customer Invoices*
582
.. i18n: If you want to create menu that filters on the user (*All* and *My*) put them at the same level:
585
If you want to create menu that filters on the user (*All* and *My*) put them at the same level:
608
.. i18n: Avoid Abbreviations in menus if possible. Example:
611
Avoid Abbreviations in menus if possible. Example:
613
.. i18n: * BoM Lines -> Bill of Materials Lines
616
* BoM Lines -> Bill of Materials Lines
618
.. i18n: Reporting Menu
619
.. i18n: ##############
625
.. i18n: The dashboard menu must be under the report section of each main menu
628
The dashboard menu must be under the report section of each main menu
630
.. i18n: * Good: Sales Management / Reporting / Dashboards / Sales Manager
631
.. i18n: * Bad: Dashboard / Sales / Sales Manager
634
* Good: Sales Management / Reporting / Dashboards / Sales Manager
635
* Bad: Dashboard / Sales / Sales Manager
637
.. i18n: If you want to manage the *This Month/ALL months* menu, put them at the latest level:
640
If you want to manage the *This Month/ALL months* menu, put them at the latest level:
642
.. i18n: * Reporting/Timesheet by User/All Month
643
.. i18n: * Reporting/Timesheet by User/This Month
646
* Reporting/Timesheet by User/All Month
647
* Reporting/Timesheet by User/This Month
649
.. i18n: Icons in the menu
650
.. i18n: #################
656
.. i18n: * The icon of the menu, must be set according to the end action of the wizard, example:
658
.. i18n: - wizard that prints a report, should use a report icon and not a wizard
659
.. i18n: - wizard that opens a list at the end, should use a list icon and not a wizard
662
* The icon of the menu, must be set according to the end action of the wizard, example:
664
- wizard that prints a report, should use a report icon and not a wizard
665
- wizard that opens a list at the end, should use a list icon and not a wizard
667
.. i18n: Order of the menus
668
.. i18n: ##################
674
.. i18n: The configuration menu must be at the top of the list, use a sequence=0
677
The configuration menu must be at the top of the list, use a sequence=0
679
.. i18n: The *Reporting* menu is at the bottom of the list, use a sequence=50.
682
The *Reporting* menu is at the bottom of the list, use a sequence=50.
684
.. i18n: Common Mistakes
685
.. i18n: ###############
691
.. i18n: * Edit Categories -> Categories
692
.. i18n: * List of Categories -> Categories
695
* Edit Categories -> Categories
696
* List of Categories -> Categories
705
.. i18n: Objects with States
706
.. i18n: ###################
712
.. i18n: * The state field, if any, must be at the bottom left corner of the view
713
.. i18n: * Buttons to make the state change at the right of this state field
716
* The state field, if any, must be at the bottom left corner of the view
717
* Buttons to make the state change at the right of this state field
719
.. i18n: Search Criterions
720
.. i18n: #################
726
.. i18n: Search criterions: search available on all columns of the list view
729
Search criterions: search available on all columns of the list view
731
.. i18n: Action Names
732
.. i18n: ^^^^^^^^^^^^
738
.. i18n: .. todo:: write 'Action Names' section
741
.. todo:: write 'Action Names' section
757
.. i18n: Default Language
758
.. i18n: ^^^^^^^^^^^^^^^^
764
.. i18n: The default language for every development must be U.S. english.
767
The default language for every development must be U.S. english.
769
.. i18n: For menus and fields, use uppercase for all first letters, excluding conjections:
772
For menus and fields, use uppercase for all first letters, excluding conjections:
774
.. i18n: * Chart of Accounts
779
.. i18n: Field Naming Conventions
780
.. i18n: ^^^^^^^^^^^^^^^^^^^^^^^^
783
Field Naming Conventions
784
^^^^^^^^^^^^^^^^^^^^^^^^
786
.. i18n: * Avoid generic terms in fields and use if possible explicit terms, some example:
788
.. i18n: - Name -> Sale Order Name
789
.. i18n: - Parent -> Bill of Material Parent
790
.. i18n: - Rate -> Currency Rate Conversion
791
.. i18n: - Amount -> Quantity Sold
794
* Avoid generic terms in fields and use if possible explicit terms, some example:
796
- Name -> Sale Order Name
797
- Parent -> Bill of Material Parent
798
- Rate -> Currency Rate Conversion
799
- Amount -> Quantity Sold
801
.. i18n: Here are some rules to respect:
804
Here are some rules to respect:
806
.. i18n: * many2one fields should respect this regex: '.*_id'
807
.. i18n: * one2many fields should respect this regex: '.*_ids'
808
.. i18n: * one2many relation table should respect this regex: '.*_rel'
809
.. i18n: * many2many fields should respect this regex: '.*_ids'
810
.. i18n: * use underscore to separate words
811
.. i18n: * avoid using uppercases
812
.. i18n: * if a field should be composed of several words, start by the most important words
814
.. i18n: * This is good: sale_price, partner_address_id
815
.. i18n: * This is bad: is_sellable
818
* many2one fields should respect this regex: '.*_id'
819
* one2many fields should respect this regex: '.*_ids'
820
* one2many relation table should respect this regex: '.*_rel'
821
* many2many fields should respect this regex: '.*_ids'
822
* use underscore to separate words
823
* avoid using uppercases
824
* if a field should be composed of several words, start by the most important words
826
* This is good: sale_price, partner_address_id
827
* This is bad: is_sellable
829
.. i18n: Object Naming Conventions
830
.. i18n: ^^^^^^^^^^^^^^^^^^^^^^^^^
833
Object Naming Conventions
834
^^^^^^^^^^^^^^^^^^^^^^^^^
836
.. i18n: * All objects must start by the name of the module they are defined in.
837
.. i18n: * If an object is composed of several words, use points to separate words
840
* All objects must start by the name of the module they are defined in.
841
* If an object is composed of several words, use points to separate words
850
.. i18n: * All Tree of resources are called *XXX's Structure*, unless a dedicated term exist for the concept
852
.. i18n: - Good: Location' Structure, Chart of Accounts, Categories' Structure
853
.. i18n: - Bad: Tree of Category, Tree of Bill of Materials
856
* All Tree of resources are called *XXX's Structure*, unless a dedicated term exist for the concept
858
- Good: Location' Structure, Chart of Accounts, Categories' Structure
859
- Bad: Tree of Category, Tree of Bill of Materials
861
.. i18n: Module Recorder
862
.. i18n: +++++++++++++++
868
.. i18n: .. todo:: write 'Module Recorder' section
871
.. todo:: write 'Module Recorder' section
873
.. i18n: Review quality
874
.. i18n: ++++++++++++++
880
.. i18n: - You can check your module quality using "base_module_quality" module available on stable addons
883
- You can check your module quality using "base_module_quality" module available on stable addons
added
removed
i18n/ru/source/contribute/05_developing_modules.rst
