Relation string field allows you to define and edit a relationship between an
object and another objects. A relation is always based on one of base categories
- for example, a shipment is related to a client with a destination relation,
and to a supplier with a source relation.
Table of Contents
Let's take an example: you maintain a database of people who belong to a sect.
Every member may have a guru whom he follows. To implement this relation,
we need to take the following steps:
Now every Person object has dynamically generated functions like getGuru
getGuruTitle getGuruId getGuruValue (which returns and object), setGuru etc.
(while generating functions, ERP5 eliminates underscores from category names
and capitalises first letters).
Then go to a Person_view form, and add a Relation String Field with id
my_guru_title (the my_ prefix is required in every
HowTo Create New Forms control).
Configure it as follows:
This is it - now when you go to your Person_view form, you can click the gear
next to the field and select one person to be your guru. If you enter something
into the field before clicking the gear, it will search persons by title (that's
also why if you click the gear again you will get a list of one person only).
The little airplane takes you straight to your guru.
Remember that for this to work properly, an object you relate to must have a
You can explore this relation from the other end, too - if you want to know
your followers, run a function getGuruRelatedValueList. To see them, just
create a Listbox and use this function as its list method.
If your sect allows a person to follow more than one guru at the same time,
then instead of a Relation String Field use a Multi Relation String Field, and
name it my_guru_title_list. Everything else is the same. Remember that in this
case functions getGuru, getGuruTitle etc. will return only one of them - if you
write a script, use functions like getGuruTitleList, getGuruValueList and so on.
RelationStringField inherits from many ListField field (some of same may not be
revelant and only be used for internal rendering process). Most of these fields
are actually parameters to configure the listbox which will give you the choice
of objects to choose from to define the relation. However, in the default
implementaion, some of them work and others do not. This is because for performance
reasons the !Base_viewRelatedObjectList form takes only the most commonly used
parameters (columns and default sort). If you want to configure a parameter and
it doesn't seem to work, you have to customize !Base_viewRelatedObjectList.listbox
by finding the appropriate field and entering into its TALES expression something
Here is fields specific to RelationStringField.
skill_id | guru
VERY IMPORTANT NOTE:
For now (21 sep 2006), it only works, when user will click on that little round
button right on field. If user prefill that field and update form, data won't
be restricted to your customization, which would be inconsistent. Use it on your
own risk. More information avaiable on erp5-dev list. To restrict data entered
directly you would need to use an external validator which wouldn't allow for
data inconsistent with your customization.
By default RelationStringField allows you to present title or reference of related
objects. But what if you'd like to present your own or any other field? In case
of person we may use source_reference property - it is
which is required.
Create RelationStringField with id my_guru_source_reference and configure it:
python: context.getGuruValue().getSourceReference() or ''
Note: Use tests for emptiness in production system.
Now system will be able to present relation using Person's title and reference, with same interface as my_guru_title field.