Table of Contents
User Interface Conventions¶
Text shown by the UI is classified into titles and sentences. Basically, they
should be British English by default. The text is translated by Localizer. To
reduce the cost of translations, you should not increase the variation of
messages shown to the user.
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.
- ID (an abbreviation of identifier)
- FAX (an abbreviation of facsimile)
- VAT (an abbreviation of value added tax)
Modules show titles in the window decoration bar and in ListBoxes. They should
be plural, separated by space, with no article, and capitalized.
Purchase Packing Lists
Documents show titles in the window decoration bar. They should be singular,
sperated by space, with no article, and capitalized.
Purchase Packing List
If a document has sub-documents, the title of a ListBox follows the same rule
as module titles written above.
Accounting Transaction Lines
Purchase Packing List Lines
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, exceptionally.
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.
One more tab is shown only to Managers. It should be put after anything else,
and entitled with Metadata.
Other 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.
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.
OpenOffice Source File Example
Paths of Objects whose Workflow Histories should be Exported
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.
%d objects have been saved.
%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.
The document is saved in /path/to/the/file .
The document is saved in /path/to/the/file.
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
objects which can be published and accessed through the OFS implement
acquisition of attributes and, in certain cases, skinning
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
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).
Use explicit naming instead of abbreviations to make code easily readable by third parties.
A pseudo-constant is a global reusable value stored as an attribute (of a Class,
of a module) which is considered as a constant.
Attributes, Properties and IDs¶
Attributes can be assigned to an object, to a class. Properties can be assigned
to Zope object.
Variables can be defined within a python 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.
azerty # not a word
doc # abbreviation
object # python reserved keyword
Class¶es are defined in python within products.
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
Order Root Simulation Rule (current Order Rule)
Invoice Simulation Rule (current Invoicing Rule)
Invoice Root Simulation Rule (current Invoice Rule)
Interface are created in the 'Interface' folder of a file system Zope Product,
they are CamelCase:
Methods are defined for each class in python, using mixedCase and starts with
Exception if ZMI:
Fuction is the same as Method.
Python scripts in the OFS are meant to be called on the context of a portal type,
then the naming must follow:
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
( see _getTypeBaseMethod for Products.ERP5Type.Base.Base class )
Scripts that apply to the whole site or don't need a specific context can be
prefixed with ERP5Site_
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.
Python scripts are often used in listboxes, refer to ListBox section for specific
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.
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
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.
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.
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. Macro IDs should follow the same
conventions as for variables (small caps).
<html tal:define="foo string:renderer">
<title tal:content="template/title">The title</title>
<p tal:content="foo">foo value</p>
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:
Exception for UI control page template (lower case):
Z SQL Method¶
Z SQL Method¶s are stored as IDs in the OFS but act as methods
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.
ERP5 Forms are often used to show dialogs for exporting, importing, fast input,
etc. In this case, they must be named:
ERP5 Report is an extension of ERP5 Form to produce reports. We first have a
dialog that will redirect to the report.
Example for a report named ReportName on PortalType objects; For the dialog:
For the report:
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.
use list methods, count methods and stat methods.
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¶es use selection names.
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
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:
SQL Column id¶
All columns of all tables used by ERP5 should be lower case. Exceptions are only
allowed in the compatibility table.
Related Keys are used inside the portal_catalog. You can define some in the
Related Keys should be named like SQL column ids, because they are virtual columns.
We should not use abreviations.
Sometimes, we want to specify from which table we will take values (when it
is not the default catalog one).
The name of a workflow state should be a single adjective or a single verbal adjective.
The translation of workflow states should follow the same rule: use a single adjective
or verbal adjective.
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.
CSS classes are used in ERP5 to render content as HTML page. More information
can be found in the 'ERP5 XHTML Style' documentation. CSS classes may also be
used in the future to render XML pages.
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)
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 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
We recommend the use of PNG for diagrams and logos and JPEG for pictures of
nature of people. GIF should be limited to cases for which transparency is
We recommend the use of GIF for small icons because gif is the only icon format
which is supported well by all browsers with transparency. Since GIF patents are
it is possible to use GIF without risk outside Europe too. The standard size for
icons is 16x16.
NOTE: every business template which provides a new portal type must also provide
an icon for it. Business templates which provide a custom style may also provide
a complete set of icons for all portal types in a dedicated skin folder
The following topics does not have any convention yet: