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

• Example
• Multi-relation
• Fields description
• Using other fields
• Related Articles

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 /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 HowTo Create New Forms 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:

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

Here is fields specific to RelationStringField.

• Update Method:
  The method called on update. No need to change this one.
• Jump Method:
  The method called when clicking on the airplane to jump to the related object.
• Allow Jump:
  Wether the field allow to jump to related object(s) or not.
• Base Category:
  The base category for the relation.
• Portal Type:
  The portal type of related objects. Also used for relation "color"
• Allow Creation:
  When no related objects are found, if this parameter is checked, user will be able to directly create objects from this RelationField.
• Container Getter Method:
  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_id related 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:
  • Update Base_viewRelatedObjectList's listbox TALES field List Method with:

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

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

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 ''

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.

Related Articles¶