Certain types of widgets (e.g. grid (v1.0) and checkbox (v1.2)) support the relationship directive which allows them to effectively add/remove records from a specified relationship. This directive only works with transient fields.
Example 1: Checkboxes to add/remove categories
(Note: This example requires Xataface 1.2 or higher to work)
Suppose we have a database that keeps track of courses and the branch of research that they belong to. A course can be part of multiple branches. We want to be able to select the branches that a particular course belongs to on the edit form for that course using checkboxes.
course_id : int (primary key)
course_title : varchar
branch_id : int (primary key)
branch_name : varchar
course_id : int
branch_id : int
You can call the field anything that you like. There is no need for it to have the same name as the relationship. It just turned out that way in this example.
Example 2: Using a grid widget
Let's modify example 1 slightly to use a grid widget instead of checkboxes. The grid widget will allow us edit the records in a relationship using dynamic table. It automatically uses the correct widget for each column of the table according to the definition in the target table's fields.ini file. Most of the definition can remain the same. We only change the fields.ini file directive: