Wendelin Exanalytics Libre

WENDELIN combines Scikit Learn machine learning and NEO distributed storage for out-of-core data analytics in python

Table of Contents

  • User Interface Conventions
  • Coding Conventions
  • Additional Conventions
  • CSS
  • Skin images

    This document defines ERP5 naming conventions.

    Contents:

    1. User Interface Conventions
      1. Titles
        1. Module Titles
      2. Document Titles
        1. Tab Titles
        2. Field Titles
        3. Sentences
    2. Coding Conventions
      1. Pseudo Constant
      2. Attributes, Properties and IDs
      3. Variables
      4. Class
        1. Rule Class
      5. Interface
      6. Method
      7. Function
      8. Script (Python)
      9. Page Template
      10. Z SQL Method
      11. ERP5 Form
        1. ERP5 Report
      12. ListBox
      13. Style Sheet
      14. SQL Column id
      15. Related Keys
    3. Additional Conventions
      1. Workflow States
    4. CSS
      1. Reserved IDs
      2. Reserved classes
      3. Recommended classes
    5. Skin images
      1. Images
      2. Icons
      3. Undefined Topics

    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.

    Example:

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

    Titles

    Module Titles

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

    Example:

    Accounting Transactions
    Purchase Packing Lists

    Document Titles

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

    Example:

    Accouting Transaction
    Purchase Packing List

    If a document has sub-documents, the title of a ListBox follows the same rule as module titles written above.

    Example:

    Accounting Transaction Lines
    Purchase Packing List Lines

    Tab Titles

    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.

    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.

    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.

    Example:

    Discount
    Transactions

    Field Titles

    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.

    Example:

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

    Sentences

    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.

    Coding Conventions

    Python coding conventions 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

    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).

    Bad Examples:

    friends
    getFriends

    Good Examples:

    friend_list
    friend_count
    getFriendList
    getFriendCount
    getFriendListSize
    countFriendList

    Use explicit naming instead of abbreviations to make code easily readable by third parties.

    Bad Examples:

    lstpt
    pt
    ptlst

    Good Examples:

    last_portal_type
    portal_type
    types_tool
    portal_type_list

    Pseudo Constant

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

    Example:

    CONSTANT_NAME

    Attributes, Properties and IDs

    Attributes can be assigned to an object, to a class. Properties can be assigned to Zope object.

    Example:

    base_price
    attribute_name

    Variables

    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.

    Good examples:

    base_price
    attribute_name
    document
    movement
    

    Bad examples:

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

    Class

    Classes are defined in python within products.

    Example:

    Document
    MetaResource
    Resource
    ClassName

    Rule Class

    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

    Example:

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

    Interface

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

    Example:

    Predicate
    DublinCore
    InterfaceName

    Method

    Methods are defined for each class in python, using mixedCase and starts with a verb.

    Good Example:

    getTitle
    getBasePrice
    edit
    setPrice
    convertStringToFloat

    Bad Example:

    get_title
    get_base_price
    basePrice
    stringToFloat

    Exception if ZMI:

    manage_doMethodName

    Function

    Fuction is the same as Method.

    Script (Python)

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

    PortalType_methodName

    For Example:

    AccountingTransactionLine_getSourceItemList
    PurchaseInvoiceTransaction_init

    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_

    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.

    Bad Example:

    ERP5Site_getFieldTranslatedTitle
    ERP5Site_getFormTranslatedTitle
    ERP5Site_validateRequiredFile

    Good Example:

    Field_getTranslatedTitle
    Form_getTranslatedTitle
    Document_validateRequiredFile

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

    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.

    Example:

    Document_validateRequiredFile
    SaleOrder_validateClientDestination
    Movement_validateSourceAndDestination

    Page Template

    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).

    Example:

    Document_viewAsHTML
    Document_viewAsODT
    Document_viewAsPDF
    Document_viewProfileWidget
    Base_viewBreadcrumbWidget

    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

    Bad Example:

    custom_invoice_render
    breadcrumb_render
    document_widget_render
    content_renderLibrary

    Good Example:

    Base_viewStandardRenderer
    TextDocument_viewTextContentRenderer
    WebSite_viewStandardWidgetRenderer

    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).

    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

    Z SQL Method

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

    In portal_catalog:

    z_method_name

    In portal_skins:

    PortalType_zMethodName

    ERP5 Form

    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.

    Example:

    AccountModule_viewAccountList
    Base_viewUIDialog

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

    PortalType_viewMethodNameDialog

    Example:

    UseCase_viewActorFastInputDialog

    ERP5 Report

    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:

    PortalType_viewReportNameReportDialog 

    For the report:

    PortalType_viewReportNameReport

    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:

    PortalType_getReportNameReportSectionList

    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.

    ListBox

    ListBoxes use list methods, count methods and stat methods.

    Example:

    AccountingTransactionModule_zGetAccountingTransactionList
    AccountingTransactionModule_countAccountingTransactionList
    AccountingTransactionModule_statAccountingTransactionList

    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).

    ListBoxes use selection names.

    Example:

    module_name_selection

    Style Sheet

    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.

    Bad Example:

    default_ooo_template
    Base_DefaultOOoStyleSheet
    UseCaseModule_UseCaseReportStyleSheet

    Good Example:

    Invoice_getODTStyleSheet
    Base_getODTStyleSheet
    Folder_getODSStyleSheet

    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:

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

    SQL Column id

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

    Example:

    title
    simulation_state
    has_cell_content

    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.

    Bad Example:

    destinationType

    Good Example:

    destination_title
    destination_portal_type
    grand_parent_simulation_state

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

    Bad Example:

    stock_sectionCategory

    Good Example:

    stock_section_category_uid

    Additional Conventions

    Workflow States

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

    Bad Example:

    ship
    to_ship
    validated_by_cto

    Good Example:

    hot
    inactive
    ready
    shipped
    received
    ordered

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

    Bad Example:

    Validated by the Boss
    Source Boss Valault Accepted
    To Send Later

    Good Example:

    Hot
    Inactive
    Ready
    Shipped
    Received
    Ordered

    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

    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.

    Reserved 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)

    Reserved classes

    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

    jps: why are we using classes instead of IDs here ?

    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

    Skin images

    Images

    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 required.

    erp5_logo.png
    nature_banner.jpg
    rounder_corner.gif

    Icons

    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 now expired, it is possible to use GIF without risk outside Europe too. The standard size for icons is 16x16.

    document_icon.gif
    web_site_icon.gif

    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 (ex. erp5_ancient_style_media)

    Undefined Topics

    The following topics does not have any convention yet:

    portal types' action IDs