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)

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

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 like this:

Method called to find the container in which new object will be created if creation is allowed.

Catalog index :

The catalog index that correspond to the value entered in the field.

Relation Update Method :

The method called to update the relation. This method takes as arguments the list of related object's uid and the list of portal type. This method is responsible for setting the relation, or unsetting the relation if the list of uid is empty.

Parameter List :

A list of extra parameters passed to the catalog when searching for related objects. This is especially usefull, for exemple if you want to limit to objects in specific workflow states or related to a given category. In the above example, we could filter the list of guru to persons

having guru in their skills. Assuming we have a category called guru under skill base category, and skill_idrelated key exists, we can use the following :

skill_id | guru

List Method :

This is an alternative way (to Parameter List) of restricting data avaiable to user. You may restrict data, which will be shown to user while clicking onbutton associated with RelationStringField. To do so, you need to:

Then while configuring RelationStringField put in List Method field a name of a script which returns your list.

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.

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.