The relationship fields.ini directive

Synopsis

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.

Table Structure:

courses:
   course_id : int (primary key)
   course_title : varchar

branches:
   branch_id : int (primary key)
   branch_name : varchar
   branch_description: text

course_branches:
   course_id : int
   branch_id : int

Relationship definition: (from the tables/courses/relationships.ini file):

[branches]
    course_branches.course_id="$course_id"
    course_branches.branch_id=branches.branch_id

Field definitions: (from tables/courses/fields.ini file):

[branches]
  transient=1
  relationship=branches
  widget:type=checkbox

Things to notice:

This is a many-to-many relationship (hence the need for the course_branches join table.
The [branches] field is a transient field.
The relationship directive from the fields.ini file references our branches relationship that was defined in the relationships.ini file.
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.

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:

[branches]
  transient=1
  relationship=branches
  widget:type=grid
  widget:columns="branch_name,branch_description"

In this case we are able to edit the branch name and description in each row of the grid.

The relationship fields.ini directive

Synopsis

Example 1: Checkboxes to add/remove categories

Example 2: Using a grid widget

See Also