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¶

• Guidelines | A Document Form Uses The form_view Page Template
• Guidelines | Add Column Portal Type If Listbox Contains Multiple Types
• Guidelines | Add Date In Listbox As Editable Date-Time Field
• Guidelines | Add Viewable Listbox Fields To More Columns
• Guidelines | Define Count Method As countFolder On Module Listbox
• Guidelines | Dialog Form Name Is Postfixed With Dialog
• Guidelines | Do Not Mix Description And Comment
• Guidelines | Do Not Test Required In Field View Form
• Guidelines | Document Content Is Written In British English
• Guidelines | Field Title Must Be Singular, Capitalized And Uses Space Separator
• Guidelines | Form Name Uses Lowercase View After Portal Type
• Form Proxification
• Guidelines | Form Report Dialog Is Postfixed With Report
• Guidelines | Forms Must Use Left, Right, Center, Bottom And Hidden Groups
• Guidelines | Hide Listbox Editable Fields On The Form
• Guidelines | ListField Or MultListField For Categories Must Use Item List Method
• Guidelines | Listbox Must Only Be Put In Form Bottom Group
• Guidelines | Listbox Only Tabs Should Have A Read Only Title In Center Group
• Guidelines | Listbox Selection Name Must Follow module_name_selection Pattern
• Guidelines | Never Allow Relation String Fields To Set Relations To Categories
• Guidelines | Never Set Search Row And Select Column On Listbox Inside Document View
• Guidelines | Never Show Or Make User Work With Document Id
• Guidelines | Place Simulation And Validation Fields At Bottom Of Right Group
• Guidelines | Report Name Uses Portal Type Followed By View Report Name And Report
• Guidelines | Set Description On Form Fields
• Guidelines | Set Document Form Ids To PortalType_view
• Guidelines | Set Document Form Titles To What Is Displayed
• Guidelines | Set Form Action Base_doSelect On Forms
• Guidelines | Set Form Action To Base_edit
• Guidelines | Set Form Encytype to multipart/form-data When Using File Upload
• Guidelines | Set Form Id To ModulePortalType_viewPortalTypeList
• Guidelines | Set Form Title To What Is Displayed
• Guidelines | Set List Method To contentValues On Document Form Listbox
• Guidelines | Set Listbox Action To List Action On Document Form Listboxes
• Guidelines | Set Listbox Selection Name To form_name_selection_name
• Guidelines | Set Listbox Title To Plural Of Portal Type Title If Applicable
• Guidelines | Set Post Method And Utf-8 Encoding On Document Forms
• Guidelines | Split Large Forms On Multiple Tabs
• Guidelines | The Listbox Method Should Be Defined As SearchFolder To View Modules
• Guidelines | Use Correct Names For Simulation And Validation Titles
• Guidelines | Use form_list Page Template On Forms
• Guidelines | Use getTranslatedId To Display Document Ids In Listbox Or Form
• Guidelines | Use Method Post And UTF-8 Encoding On Forms
• Guidelines | Use Proxy Fields Of Proxy Fields In Form
• Guidelines | Use Translated Portal Type To Display Portal Type
• HowTo | Add Report
• HowTo | Configure Relationstring Field
• HowTo | Configure Parallellist Field
• HowTo | Configure Proxy Field
• HowTo | Create New Forms
• HowTo | Create OOO (Open Office) Report
• HowTo | Display or Edit HTML
• HowTo | Display Souce Code
• HowTo | Edit Listbox Data Source
• HowTo | Update PDF Form
• Technical Note | Web Forms