This document explains how to use the PreferenceTool to integrate user preferences
in ERP5.
Table of Contents
The PreferenceTool¶
- By default, users create User Level preferences. These have higher priority.
- Group preferences have lower priority. They are associated to a group of users by assigning the role definition Auditor to a group of users.
- Site preferences are the lowest priority. Site managers must ensure they always exist and are enabled, because ERP5 UI parts assume this.
The preferenceTool is a generic tool to integrate user preferences in ERP5. It
allows users to add preference documents in the preference folder. The idea is to
have different level of priority on Preference objects:
Using Preferences¶
When accessing a preference, a manager can change the priority of the preference.
The form for viewing a preference have a special behaviours when the authenticated
user has a Manager role.
Setting Site Preference Priority¶
When you create a new preference it is created with User priority be default.
Later the site manager can change the preference priority to Site by changing the
Priority field on a preference. Enabling a site preference will not set
it into Enabled state but into Globally Enabled. This is a special
state, where all site members have view permission on it.
Setting Group Preference Priority¶
Creating a group preference is similar to a site preference, except that you
need to configure roles so that the targeted group of users has Auditor role.
Differences Between Site Preference And Preference¶
There are two different portal types: Preference which is intended for
users and group of users to configure the application behavior and Site Preference
who are intended for managers to configure the global behavior of a site. Only
managers can create and enable Site Preferences.
How Do Preferences Work?¶
A Preference must be explicitly activated (ie. in Enabled or Globally Enabled state)
to be taken into account by PreferenceTool. Any active preference on which the
user has the View permission is looked up for this user.
When a user activates a preference, all other user level preferences
he owns are automatically de-activated. A user can only have one active preference at a time.
To query a user preference you must directly call the method on the PreferenceTool, for example:
portal.portal_preferences.getPreferredAccountingTransactionSourceSection()
or
portal.portal_preferences.getPreference('preferred_accounting_transaction_source_section')
The first call will work if you have associated a Property Sheet that defines the
preferred_accounting_transaction_source_section attribute or categoryon your
Preference Portal Type. Note that the preferred_ part of the name is not automatically
added, the property is actually called preferred_accounting_transaction_source_section.
Then it will lookup the preferred_accounting_transaction_source_section on all
active Preferences that the user can access (ie. Preference on which he is Owner
or Auditor), in that order:
- Site Preference portal type
- User level preferences
- Group level preferences
- Site level preferences
If the value is not set to None nor an empty list, this preference is used,
otherwise, PreferenceTool tries to get the value on the next preference. If
nothing was found, then PreferenceTool returns None (or the empty list, depending
on what value was found on the Preference itself).
Adding New Preferences¶
-
Define a new Property Sheet for the attribute you want to make a preference.
Mark this attribute as a preference by checking preference in the property
definition. Note that the Property Sheet ID must be postfixed with Preference
(e.g. LocalizationPreference).
-
Create an ERP5Form for the user to set this preference. (or reuse an existing one)
-
Then you can call preference methods on portal_preferences.
-
PreferenceTool also exist in TALES context of ERP5Form as preferences
Using HTML Style Preferences¶
- Developper Mode assists a developer:
- adds link to Base_viewInspectionReport
- adds ability to edit forms, forms' actions and forms' fields
- Contextual Help adds link to contextual help, with url as defined in Documentation URL preference
- Translator Mode helps translating site, by creating special links in forms' fields and some other translateable objects
- Documentation URL is a URL used by contextual help system
How preferences are used in erp5_accounting¶
The PreferenceTool was initially created for erp5_accounting, because to display
Accounts balances, we must know what source_section, what currency, etc. relate
to a certain user. Therefore the user must set accounting preferences containing
the following inforomation:
- section group category, used for reporting in the Account Module main page, list of Transactions for an Account and list of Transaction for an Entity
- section organisation Object, used for prefilling Accounting Transaction documents
- currency, used for prefilling Accounting Transaction documents and reporting in Account Module main page, list of Transactions for an Account and list of Transaction for an Entity
- gap used to display gapId for Account objects who belong to multiple accounting plan classifications.
- start and stop_date to limit transactions for Account Module main page, list of Transactions for an Account and list of Transaction for an Entity to a given date range.
- simulation_state to limit transactions for Account Module main page, list of Transactions for an Account and list of Transaction for an Entity to a given date range.
Most accounting preferences are also used for reporting.
The preferences settings also relate directly to the default Accounting Module View
(Accounting Transaction list) as well as its 'Search' function initial settings.
Those settings can be overwritten of course temporarly on the 'Search' refining page.
Preference Templates¶
Preferences can be used as a placeholder for the user to create template
documents that he can reuse later to add new documents to a folder.
Refer to How To Create Templates
for more information.
System Preferences¶
Some business templates require system-wide preferences. Document conversion for example
requires to connect to an external service (like Cloudooo) and thus
needs a preference parameter with the URL to connect to. These system preferenes
are also accessible via portal_preferences.
Note there should be only one (!) system preference enabled and that ERP5 might already
have created a system preference (obfusiciatingly called Created by Promise Alarms). If you create another one, it
will not take precedence over the existing one automatically, so newly set parameters will not
work when calling a method like getPreferredDocumentConversionServerUrl.
Add your parameters to the above preference instead of creating new system preferences. Make
sure the preference is enabled and if necessary, clear (portal-) caches and restart your zope
(in the webrunner interface). Then parameters should be updated.
Related Articles¶