How to configure RelationStringField

Relation explained

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.

Example

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:

- create a base category guru in <your_site>/portal_categories

- assign a portal_type Person to a base category guru (in portal_types tool, or by using Property Sheets)

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 ERP5Form control). Configure it as follows:

- set Base Category to guru

- enter Person into Portal Type box (since only a person can be somebody's guru, we want the list of objects to display only this type of objects)

- set Catalog Index to title

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 non-empty title.

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.

Multi-relation

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.

Fields description

python: here.Base_getRelatedObjectParameter(parameter='foo')

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.

Using other fields

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 catalogued, which is required.

Create RelationStringField with id my_guru_source_reference and configure it:

- set Base Category to guru

- enter Person into Portal Type box (since only a person can be somebody's guru, we want the list of objects to display only this type of objects)

- set Catalog Index to source_reference

- on TALES tab fill Default with:

python: context.getGuruValue().getSourceReference() or ''

<!> 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.

HowToConfigureRelationField (last edited 2008-10-21 14:47:42 by BorisKocherov)