Table of Contents

• Introduction
• Recommendation
  • Knowing Python And Zope Is Required For Developing ERP5
  • PDF Style Sheet Should Also Follow Form And Method Conventions
  • Reserved CSS Classes Should Not Be Used Or Overloaded
  • Use Recommended Layout CSS Classes
• Rule
  • A Python Class Is Defined Inside ERP5 Product Only
  • Abbreviations Are Not Allowed In ERP5 Code
  • Assign Properties To Zope Objects Only
  • Attribute Must Be Assigned Only To Object Or Class
  • Dialog Form Name Is Postfixed With Dialog
  • Do Not Add Any New Messages To User Interface
  • Document Has Mandatory View And Optional Detais And History Tab
  • Field Title Must Be Singular, Capitalized And Uses Space Separator
  • Form Name Uses Lowercase View After Portal Type
  • Form Report Dialog Is Postfixed With Report
  • Interface Name Uses Camelcase
  • Language Priority
  • Listbox Method Is Named Using Module Type And Portal Type List
  • Listbox Selection Uses Name Selection Postfix
  • Listbox Uses List, Stat Or Count Method
  • Metadata Is Last Tab For Managers
  • Method In Listbox Is Prefixed With Listbox Section
  • Method Name Is Prefixed With Portal Or Meta Type, Class Or Interface
  • Method Name Uses Mixed Case And Begins With Verb
  • Module Title Is Plural, Capitalized And Space Separated
  • Only Site Wide Script Uses ERP5Site Prefix
  • Page Template Containing Multiple Macros Is Postfixed With Renderer
  • Page Template Macro Id Is Lowercase
  • Page Template Macro Variables Must Be Defined In Header
  • Page Template Uses Method Naming Conventions
  • Plural In ERP5 Is Written Using List And Count
  • Pseudo Constant Uses Uppercase In ERP5
  • Python Script Method Name Be Prefixed With Portal Type
  • Report Method Name Uses ReportSectionList Postfix
  • Report Name Uses Portal Type Followed By View Report Name And Report
  • Rule Uses Optional Root And Mandatory Simulation Rule Postfix
  • Sentence Starts With Capital Letter And Finishes With Semi-Colon Or Full-Stop
  • SQL Column Id Is Lowercase
  • Use Singular For Related Key Like Column Id
  • Tab Title Is Singular Capitalized And Space Separated
  • User Interface Module Title Is Singular, Separated By Space And Capitalized
  • User Interface Must Use Uppercase Abbreviations
  • Validator Method Is Prefixed With Validator
  • Variable Name Is Lowercase Separated By Underscore
  • Workflow State Is Single Adjective Or Verb
  • ZSQL Method Is Lowercase And Uses Z Prefix And Underscore Separator
  • ZSQL Method Is Prefixed With Z In Portal Skin
  • Tool Title Is Plural, Capitalized And Space Separated
• Crime
  • Never Forget Edit Workflow On Documents
  • Never Print Directly
  • Never Render Reports Directly
  • Never Use Or Overload Reserved CSS Ids

Introduction¶

Programming conventions cover conventions related to working with ERP5 (and should be merged with coding conventions). The guidelines cover different topics from user interface to coding in ERP5 in general. The goal of this guideline is to ensure that ERP5 code stays maintainable and consistent.

Recommendation¶

Knowing Python And Zope Is Required For Developing ERP5¶

Python PEP 8 is a good start for python coders. It defines precisely the multiple naming conventions from which we have to choose. A must read.

Zope extends the python object model by adding

• Zope Objects
  objects which can be published and accessed through the OFS implement acquisition of attributes and, in certain cases, skinning
• Zope Methods
  It is possible to extend the behaviour of a Zope Object as defined in its class by calling special kinds of methods (DTML, Page Template, Python Script) stored in the OFS as Zope Objects

PDF Style Sheet Should Also Follow Form And Method Conventions¶

Style Sheets are used for PDF Template and OOo Template. They should follow the same kind of convention as for forms or python scripts. The underlying idea is that a style sheet may either be a file or a dynamic content generated either by a script or by a page template. This can be useful for example to dynamically change the rendering style of a PDF invoice based on the company which is issuing the invoice (source_section). As a result, style sheets are named after method conventions.

Good Example:

Invoice_getODTStyleSheet
Base_getODTStyleSheet
Folder_getODSStyleSheet

Bad Example:

default_ooo_template
Base_DefaultOOoStyleSheet
UseCaseModule_UseCaseReportStyleSheet

Also, when using OOo Template, styles (defined in open office) inside the OOo file used as template have to be named correctly. Note that if you use space or underscores (eg. report_title) in the style name, the XML definition created by openoffice will contain style:name (report_5f_title) and style:display-name (report_title), hyphens (-) are not escapted, that's why it's probably better to name them in hyphens. Styles should have meaningfull name, for example:

Good Example:

report-title
report-section-title-level1
report-column-title
report-column-content-monetary
report-column-content-text

Reserved CSS Classes Should Not Be Used Or Overloaded¶

The following classes are used by 'XHTML Style' to define specific page blocks. This list must be provided to custom style Web designers to prevent them from using an existing ID for a different page element.

.actions      // Action tabs
.wrapper      // A group of widgets
.document     // The document and associated controls
.content      // The document content as such
.dialog_box   // The dialog and dialog controls
.list_dialog  // The dialog content as such

The following recommended class names are used to associated a class to a group in an ERP5 Form. They are recommended names for layout design.

.column       // A widget area to place in a column
.left         // A widget area to place in a left column
.right        // A widget area to place in a right column

Use Recommended Layout CSS Classes¶

The following names are used to associated a class to a group in an ERP5 Form. They are recommended names for layout design.

.column       // A widget area to place in a column
.left         // A widget area to place in a left column
.right        // A widget area to place in a right column

Rule¶

A Python Class Is Defined Inside ERP5 Product Only¶

Classes are defined in python within products.

Good Example:

Document
MetaResource
Resource
ClassName

Abbreviations Are Not Allowed In ERP5 Code¶

Use explicit naming instead and no abbreviations to make code easily readable by other developers and be able to understand you wrote after some time has passed.

Good Example:

last_portal_type
portal_type
types_tool
portal_type_list
right_hand_side_symbol_length

Bad Example:

lstpt
pt
ptlst
rhs_len

Assign Properties To Zope Objects Only¶

Properties can be assigned to Zope object.

Good Example:

base_price
attribute_name
Variables

Attribute Must Be Assigned Only To Object Or Class¶

Attributes can be assigned to an object or to a class

Dialog Form Name Is Postfixed With Dialog¶

ERP5 Forms are often used to show dialogs for exporting, importing, fast input, etc. In this case, they must be named: PortalType_viewMethodNameDialog

Good Example:

UseCase_viewActorFastInputDialog

Bad Example:

UseCase_viewActorFastInput

Do Not Add Any New Messages To User Interface¶

Do not increase the variation of messages shown to the user.

Document Has Mandatory View And Optional Detais And History Tab¶

Documents show tabs with titles. The first tab should be View. But, if a document has multiple views for different tasks, they should be Task View (exception).

Good Example:

Accounting View
Invoice View

The second last tab should be Details, if a document has a detailed view. The last tab should be History, if a document has a history.

Field Title Must Be Singular, Capitalized And Uses Space Separator¶

The titles of fields, in ERP5 Forms and generated by Scripts and Page Templates, should be singular or plural according to the context, separated by space, with no article. If there is no good reason, singular forms should be used. First word, and all other words except for closed-class words, are capitalized.

Good Example:

Transaction Id
First Name
Delivery Date
State
Open Office Source File Example
EAN-13 Code
Paths of Objects whose Workflow Histories should be Exported

Bad Example:

deliveryDate
state
first_name

Form Name Uses Lowercase View After Portal Type¶

ERP5 Forms are stored as IDs in the OFS and they are associated to one or more portal types or classes as actions. They must always start with view after the name of a portal type or a class.

Good Example:

AccountModule_viewAccountList
Base_viewUIDialog

Form Report Dialog Is Postfixed With Report¶

Example for a report named ReportName on PortalType objects; For the dialog:

Good Example:

PortalType_viewReportNameReportDialog

Interface Name Uses Camelcase¶

Interface are created in the 'Interface' folder of a file system Zope Product, they are CamelCase:

Good Example:

Predicate
DublinCore
InterfaceName

Language Priority¶

• Maximum language priority should be 10
• site language priority should be 8
• selected language priority in print script should be 10

Good Example:

Listbox Method Is Named Using Module Type And Portal Type List¶

List methods have the form ModuleType_getPortalTypeList (Script) or ModuleType_zGetPortalTypeList (Z SQL Method).

Count methods have the form ModuleType_countPortalTypeList (Script) or ModuleType_zCountPortalTypeList (Z SQL Method).

Stat methods have the form ModuleType_statPortalTypeList (Script) or ModuleType_zStatPortalTypeList (Z SQL Method).

Listbox Selection Uses Name Selection Postfix¶

ListBoxes use selection names.

Good Example:

module_name_selection

Listbox Uses List, Stat Or Count Method¶

ListBoxes use list methods, count methods and stat methods.

Good Example:

AccountingTransactionModule_zGetAccountingTransactionList
AccountingTransactionModule_countAccountingTransactionList
AccountingTransactionModule_statAccountingTransactionList

Metadata Is Last Tab For Managers¶

One more tab is shown only to Managers. It should be put after anything else, and entitled with Metadata.

Method In Listbox Is Prefixed With Listbox Section¶

Python scripts are often used in listboxes, refer to ListBox section for specific naming conventions.

Method Name Is Prefixed With Portal Or Meta Type, Class Or Interface¶

In the PortalType_methodName, PortalType can be:

• a portal type name
• a meta type name, without space
• a class name ( eg. Movement_lookupPrice )
• an interface name

Method Name Uses Mixed Case And Begins With Verb¶

Methods (Functions are also methods) are defined for each class in python, using mixedCase and starts with a verb.

Good Examples:

getTitle
getBasePrice
edit
setPrice
convertStringToFloat

Exception if ZMI:

Good Examples:

manage_doMethodName

Bad Examples:

get_title
get_base_price
basePrice
stringToFloat

Module Title Is Plural, Capitalized And Space Separated¶

Modules show titles in the window decoration bar and in ListBoxes. They should be plural, separated by space, with no article, and capitalized.

Good Example:

Accounting Transactions
Purchase Packing Lists

Only Site Wide Script Uses ERP5Site Prefix¶

Scripts that apply to the whole site or don't need a specific context can be prefixed with ERP5Site_

ERP5Site_getModuleItemList
ERP5Site_reindexAll

However, most scripts do apply to a well defined context. It is essential for naming clarity and logic to find out which context is applicable.

Good Example:

Field_getTranslatedTitle
Form_getTranslatedTitle
Document_validateRequiredFile

Bad Example:

ERP5Site_getFieldTranslatedTitle
ERP5Site_getFormTranslatedTitle
ERP5Site_validateRequiredFile

Page Template Containing Multiple Macros Is Postfixed With Renderer¶

In some cases, Page templates are used as a repository of macros. A single page template may contain multiple reusable macros which participate in a global rendering process. In this case, we should not only follow the same naming convention as for scripts (CapitalizedWords) but also make sure that such page templates can be called and tested on a standard object. This means that no page template should ever be designed in such way that does not make it renderable by invoking it on an appropriate portal type instance.

The underlying idea is sometimes called prototype programming (cf. Self) or delegation (cf. HyperCard). It is similar to the idea of proxy fields in ERP5 Forms. Rather than using abstract macros from isolated page templates, new page templates should be designed by reusing bits from another working page template. However, to make the system more maintenable, it is recommended to gather all macros in a large page template which serves as a kind of example of reusable UI components. This why the name of such pages should end with Renderer.

Good Example:

Base_viewStandardRenderer
TextDocument_viewTextContentRenderer
WebSite_viewStandardWidgetRenderer

Bad Example:

custom_invoice_render
breadcrumb_render
document_widget_render
content_renderLibrary

Page Template Macro Id Is Lowercase¶

Macro IDs should follow the same conventions as for variables (small caps).

Good Example:

<html tal:define="foo string:renderer">
  <head>
    <title tal:content="template/title">The title</title>
  </head>
  <body>
    <tal:block metal:define-macro="my_box">
      <p tal:content="foo">foo value</p>
    </tal:block>
  </body>
</html>

In very rare cases, whenever a library of macros seems to be unrelated to anything and may not be renderer on a standard object, we recommend to prefix the page with PageTemplate_. The implied meaning is that the library is being renderer in the context of another page template. This is a last resort example and should if possible never be used.

Last Resort Example:

PageTemplate_viewCustomTableRenderer

Exception for UI control page template (lower case):

form_view
report_view
view_main
main_template
template_xhtml_style
field_render

Page Template Macro Variables Must Be Defined In Header¶

The coding of macro libraries should follow certain conventions too. All variables used in the macro should be defined in the page template header so that standalone rendering remains possible.

Page Template Uses Method Naming Conventions¶

Page templates are normally used for rendering an object. They play the same role as a script or a form and should therefore follow the same naming conventions (CapitalizedWords).

Good Example:

Document_viewAsHTML
Document_viewAsODT
Document_viewAsPDF
Document_viewProfileWidget
Base_viewBreadcrumbWidgetn

Plural In ERP5 Is Written Using List And Count¶

ERP5 coding style favours maximum explicitness, least ambiguity and high verbosity.

The use of plural forms or abbreviations should thus be considered as forbidden in ERP5 code unless it is required by inherited classes or imported modules defined outside ERP5. Instead of plural forms, use names ending with the list suffix (for a collection of values) or with the count suffix (for the number of values in a collection).

Good Example:

friend_list
friend_count
getFriendList
getFriendCount
getFriendListSize
countFriendList

Bad Example:

friends
getFriends

Pseudo Constant Uses Uppercase In ERP5¶

A pseudo-constant is a global reusable value stored as an attribute (of a Class, of a module) which is considered as a constant.

Good Example:

CONSTANT_NAME

Python Script Method Name Be Prefixed With Portal Type¶

Python scripts in the OFS are meant to be called on the context of a portal type, then the naming must follow: PortalType_methodName

Good Example:

AccountingTransactionLine_getSourceItemList
PurchaseInvoiceTransaction_init

Bad Example:

getSourceItemList

Report Method Name Uses ReportSectionList Postfix¶

Reports uses a 'Report Method' which is supposed to return the list of ReportSection object. This method (often a python script) must be named like:

In the case of report box, then PortalType_viewReportNameReport is an ERP5 Form containing a report box, usually named simply your_report, which also uses a report method named PortalType_getReportNameReportSectionList.

Good Example:

PortalType_getReportNameReportSectionList

Report Name Uses Portal Type Followed By View Report Name And Report¶

ERP5 Report is an extension of ERP5 Form to produce reports. We first have a dialog that will redirect to the report.

Good Example:

PortalType_viewReportNameReport

Rule¶ Uses Optional Root And Mandatory Simulation Rule Postfix

Simulation system is now under refactoring, and for new implementation, we use the following naming convention for Rule Classes (and portal types).

• any rule should end with ' Simulation Rule' (not like current 'XXX Rule')
• root applied rule should end with ' Root Simulation Rule' (not like current 'Delivery Rule' for root version of 'Delivering Rule')
• rule name should refer expected delivery of its child simulation movement

Good Example:

Order Root Simulation Rule (current Order Rule)
Invoice Simulation Rule (current Invoicing Rule)
Invoice Root Simulation Rule (current Invoice Rule)

Sentence Starts With Capital Letter And Finishes With Semi-Colon Or Full-Stop¶

Sentences should be syntactically correct and natural as English. Every sentence should be terminated with a period, a colon, or a semi-colon, according to the context. Every sentence should be plain simple, and follow sentence case: only first word is capitalized.

If you are not sure whether a noun should be singular or plural, use plural.

Good Example:

%d objects have been saved.

Bad Example:

%d object(s) has/have been saved.

The user does not care about whether 1 object has been saved. or 1 object have been saved. as long as the user must choose which is appropriate by her own eyes. It is more important to produce readable text.

If a sentence contains an URL or a path, you should insert space between the URL or the path, so that the user can easily select it by a mouse.

Good Example:

The document is saved in /path/to/the/file .

Bad Example:

The document is saved in /path/to/the/file.

SQL Column Id Is Lowercase¶

All columns of all tables used by ERP5 should be lower case. Exceptions are only allowed in the compatibility table.

Good Example:

title
simulation_state
has_cell_content

Use Singular For Related Key Like Column Id¶

Related Keys are used inside the portal_catalog. You can define some in the settings tab.

Related Keys should be named like SQL column ids, because they are virtual columns. We should not use abreviations.

Good Example:

destination_title
destination_portal_type
grand_parent_simulation_state

Bad Example:

destinationType

Sometimes, we want to specify from which table we will take values (when it is not the default catalog one).

Good Example:

stock_section_category_uid

Bad Example:

stock_sectionCategory

Tab Title Is Singular Capitalized And Space Separated¶

Besides the standard tabs View, Details, History and Metadata, tabs, if any, should be singular or plural according to the context, separated by space, with no article, and capitalized. If there is no good reason, singular forms should be used.

Good Example:

Discount
Transactions

User Interface Module Title Is Singular, Separated By Space And Capitalized¶

Documents show titles in the window decoration bar. They should be singular, sperated by space, with no article, and capitalized.

Good Example:

Accounting Transactions
Purchase Packing Lists

Bad Example:

ACCOUNTING TRANSACTION
purchase_packing_list

If a document has sub-documents (person -> contact), the title of a listBox follows the same rule as module titles written above.

User Interface Must Use Uppercase Abbreviations¶

In principle, words are written as Word or word according to the context. However, if words are abbreviations, they are written as WORD as long as this is natural according to the usage among English-speaking people.

Examples:

• ID (an abbreviation of identifier)
• FAX (an abbreviation of facsimile)
• VAT (an abbreviation of value added tax)

Validator Method Is Prefixed With Validator¶

Python scripts are used in form validators. The naming convention for validators is to use the applicavle portal type, class, or interface (ex. Document) and prefix the method with validate.

Good Example:

Document_validateRequiredFile
SaleOrder_validateClientDestination
Movement_validateSourceAndDestination

Variable Name Is Lowercase Separated By Underscore¶

Variables can be defined within a Python or JavaScript method or function, within a python script Zope object, within a page template Zope Object or within a DTML Method Zope Object. Variable shall be not abbreviated word in English and shall not conflict with python or Zope keywords.

Good Example:

base_price
attribute_name
document
movement

Bad Example:

azerty   # not a word
doc      # abbreviation
object   # python reserved keyword

Good Example:

var delivery_note = 1;

Bad Example:

var deliveryNote = 1;

Workflow State Is Single Adjective Or Verb¶

The name of a workflow state should be a single adjective or a single verbal adjective.

Good Example:

hot
inactive
ready
shipped
received
ordered

Bad Example:

ship
to_ship
validated_by_cto

The translation of workflow states should follow the same rule: use a single adjective or verbal adjective.

Good Example:

Hot
Inactive
Ready
Shipped
Received
Ordered

Bad Example:

Validated by the Boss
Source Boss Valault Accepted
To Send Later

The use of a single word allows for simplifying the display of complex search queries which may be need to select documents which are in one of multiple states.

ZSQL Method Is Lowercase And Uses Z Prefix And Underscore Separator¶

Z SQL Methods are stored as IDs in the OFS but act as methods

Good Example:

z_method_name

ZSQL Method Is Prefixed With Z In Portal Skin¶

Z SQL Methods are stored as IDs in the OFS but act as methods

Good Example:

PortalType_zMethodName

Tool Title Is Plural, Capitalized And Space Separated¶

Tools show titles in the window decoration and navigation bar. They should be plural, separated by space, with no article, and capitalized.

Good Examples:

Business Templates
Selections

Bad Examples:

Template Tool
Trash Tool
portal_selections

Crime¶

Never Forget Edit Workflow On Documents¶

edit_workflow is required to track the creation and modification history on a Document. Always chain a document to edit_workflow. This does not apply though to modules (which contain documents). Sub objects of a Document should either be chained to edit_workflow or to an appropriate interaction workflow which triggers the edit workflow of a related document (ex. the parent).

Never Print Directly¶

Unless there is a single print action, all print actions should behave as reports and Lead the user to a dialogue.

Never Render Reports Directly¶

Every list view in ERP5 should contain a default report button. Clicking on this button should never display directly a report. Instead, it must first display a standard dialogue with a few parameters (or no parameters). The report is only created once the dialogue button has been pressed.

Good Example:

Bad Example:

Never Use Or Overload Reserved CSS Ids¶

The following IDs are used by 'ERP5 XHTML Style' to define specific page blocks. This list must be provided to custom style Web designers to prevent them from using an existing ID for a different page element.

#main_form            // The single form at the root of the page
#bars                 // The group of bars in non web mode
#main_bar             // The main bar
#context_bar          // The context bar
#status               // The group of status information in non web mode
#breadcrumb           // The breadcrumb of the page
#logged_in_as         // The login information
#transition_message   // The transition message (error, confirmation, etc.)
#master               // The group of form content and controls
#main_content         // The main content group (in Web mode)