Most Powerful Open Source ERP

How To Use Preferences

How To showing how to set preferences in ERP5.
  • Last Update:2017-10-23
  • Version:002
  • Language:en

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:

  1. Site Preference portal type
  2. User level preferences
  3. Group level preferences
  4. 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