This How To describes the approach to proxify form fields to keep customisation
to a minimum by reusing existing field libraries. From Guidelines on Module Creation.
Field library is an ERP5 form which will not be accessed from users but used as
a container of proxy fields used as template field by other fields contained in
other real forms and reports. In other words, it is a collection of template
fields of proxy fields commonly used in a business template.
Using proxy field is very useful for providing consistent UI and reducing code
For example, comment field is one of the very common fields in whole ERP5 system
and it should be always the same size everywhere. Then we use proxy field, we can
define the height and width only once to the template field in the core field
library and the remaining is that all other comment fields just inherit the core
template field. This way, we can make consistent UI easily. If we did not use
proxy field, we had to set the same height and width for all comment fields one
by one, this is very hard to maintain.
About field library, this is a kind of buffer between the core field library in
erp5_core and the real fields to be displayed to users. We saw an example of
comment field above, it was a common field globally. But sometimes we want to
change an appearance of generic fields only in some business template. In such
case, we cannot change the core template fields, because they are used globally.
So we can change a field library of a target business template instead. Then we
can customize some fields only in a business template and this does not affect
UIs defined by other business templates.
Sometimes we can find similar patterns in ERP5. For example, when we use a
RelationStringField, we often name it like "my_source_title" by following our
naming convention. And from such names, we can find a pattern. The name suggests
this field uses source category and searches document by title. And we can make
a template field for RelationStringField and put a tales expression to parse
field id and find category name and index property. Once we have such a template
field which is an abstraction of a pattern we don't have to enter a category
name and an index property name each time when adding RelationStringField,
but just using a proxy field and inherit the template field is enough. We can
omit entering various parameters and it is also useful for maintenance, future
changes. Above is a very wide range example which can apply whole ERP5, but we
can find many other small patterns in a specific context managed by single business
template like Accounting, DMS. Therefore finding a pattern and making a template
field is very practical use case of proxy field and field library.
Sometimes we have to enter the same information in multiple places. For example,
a company has the same reference naming rule for Service and Product. In such case,
we have to apply the same input validation functionality to Product_view.my_reference
and Service_view.my_reference. Then we can say that both my_reference in Product_view
and Service_view are the same in reality. In such case, we should make a template field
in field library and reuse the field to inherit from proxy fields in both Product_view
nd Service_view. And in this way even if the input validation rule was changed, we
only have to update the template field and no need to touch proxy fields.
This section describes the procedure that has been used to convert erp5_base
business template to use proxy fields. The goal is to have configuration bits
shared by multiple fields defined in only one place.
Look at existing document types and find out what information is shared by those
documents. For example, Organisations, Person both share the concept of geographical
address, which is the fields city, postal code or region. Those fields are also
used by Address portal type itself.
In our address example, you should create a field library named Address_viewFieldLibrary,
containing fields like my_city or my_region. Fields in the field library will be
proxyfields to level 0 fields, from Base_viewFieldLibrary, which defines the
default look of the fields.
For this you should use fields from existing business forms as a starting point,
for example, you can copy and paste Address_view/my_city as Address_viewFieldLibrary/my_city
and then use proxify tool on Address_viewFieldLibrary to make my_city a proxyfield of
the default string field from Base_viewFieldLibrary.
Fields in those "conceptual" field libraries must usually define title and description.
Replace all fields in your business forms by fields from conceptual field library
you just created. For this you should also use the proxify tool. Fields in those
forms (like Organisation_view) should delegate almost all their values, especially
title and description which must be defined in only one place. The proxify tool
doesn't delegate values that are differents from the original field than the
target relation field.
For rare cases where the field is not shared by any other forms, you can make a
proxyfield directly to the first level field from Base_viewFieldLibrary.
The important rule is that your proxyfields must delegate everything possible.
Everytime a value is NOT delagated, it's an exception, and it should have an
explanation. You can use this code to display all non delegated values:
skin_folder = context.getPortalObject().portal_skins.erp5_base # <- XXX configure this
for field_id, field in skin_folder.ZopeFind(skin_folder, search_sub=1, obj_metatypes=('ProxyField',)):
form = field.aq_parent
field_path = '%s/%s' % (form.getId(), field.getId())
print '<a href="%s/%s/manage_main">%s</a><br/>' % (skin_folder.absolute_url(), field_path, field_path)
tf = field.getRecursiveTemplateField()
for v in tf.values:
if not field.is_delegated(v):
print " %s<br/>" % v