Most Powerful Open Source ERP

User Interface Guidelines

The purpose of this document is to define the guidelines of the User Interface in ERP5.
  • Last Update:2016-05-16
  • Version:001
  • Language:en

The purpose of this document is to define the guidelines of the User Interface in ERP5.

Table of Contents

Every ERP5 developper should have in mind the main principles and rules described below when creating or customizing forms in ERP5:

IDs are Hidden

The Id of an ERP5 document should never be handled by users or shown to them in View or List Forms. Id is a technical property in ERP5 and should not be significant for users.

IDs should never (and no longer) be used in ERP5 Forms. For an ERP5 user, an ERP5 document has to be identified by either its title, reference or int_index but not by its id which is a technical property.

Here are the responses to some frequent questions related to the need of displaying Ids in ERP5 List Forms :

Q : "I need to add an Id in my listbox because Id is the only defined property on a document (for example if a new document is created without any additionnal data entered and saved by the user). How can I remove Id from my listbox?"

R : Concerning main documents located a first level in ERP5 modules, a workflow should always be associated to the document and the workflow_state of such document is automatically set to the initial workflow state at creation of the document.That means, you can at any time click on the workflow state column in your listbox to access the document.

Concerning sub-documents (example : order lines in orders or transaction lines in accounting transactions), users want those documents to be identified by an integer index which can be modified so that they can have control over the sort order of the sub-documents in the listbox. That means int_index should be automatically set to a given value (integer conversion of id for example) when a new sub-document is created.

Q : "Id is needed, for example, in the contact listbox of Person and Organisation view forms because it is this only way to know which address or phone is the default one (some ids are automatically set to "default_address" or "default_telephone"). How can I remove Id from my listbox?

R : You should add a column in your listbox displaying if the sub-document defines a default value for the parent document. This information could be added to the portal type information column like in the following screenshot.

Workflow States

Workflow states should always be displayed as read only fields and have a specific location in ERP5 forms.

Workflow states should always be displayed as read-only string fields in ERP5 Forms. What should be displayed is always the "translated_workflow_state_title" so that the forms can be automatically localised.

In List mode, the listbox should always include the workflow states and display them as the last columns on the right.

In View mode, the workflow states should always be displayed at the bottom of the right group.

Portal Types in Listboxes

If a listbox in ERP5 is supposed to display objects having different portal types, then a portal type column is needed in the listbox to show this information. What should be displayed is always the "translated_portal_type" so that the forms can be automatically localised.

If a listbox in configured so that only objects from one portal type can be displayed, then the title of the listbox should be set to the plural of the given portal type title (ex : Sale Orders should be the title of a listbox displaying "Sale Order" objects).

Dates in Listboxes

When displaying a date in a listbox, one should always configure the listbox with a "listbox_date" editable Date-Time field so that the date format can be properly set and automatically localised.

Comments or Description

There is a common confusion between « comments » and« description ». Actually, the meaning of these properties is really different.

« Description » should be used to enter a short (one or two sentences) description of a document. « Comments » should be used to enter miscellaneous information concerning the document. All the information that can not take place in any other field or property should be considered as « comment ».

For example on a document representing a PC product, you could find in the description field technical details about the product. In the comment field you could have: « This product will be removed from the catalog of our supplier until the end of october».

Description should take place in the « left »group of a form. Comments should take place in the « center »group.

Of course, comments can be implemented in a more sophisticated way by considering that adding a comment on a document should be handled as a "comment" transition in the workflow associated to the document. This approach is a bit complex for common cases.

Related Articles