The belongsTo relation

With the belongsTo relation a record from a parent table can be linked to a record of a child table, but not excusively. This may be useful e.g. to assign a record to a predefined type, or group.
In our library example we will add the ability to assign a recommended age-group to each book. These age groups can be pre-defined and set in a table named “Agegroups”. Each book will belong to exactly one agegroup (or none!)

In the library example used in this wiki, the parent will be the book table, the child table is a description table where a single description (a record) can be linked to exactly one book.

This is the parent form book embedding the related child field called Record finder where the selected agegroup is displayed:

By clicking on the icon at the right of the field (the three lines with a dot at the left) the Record finder dialog opens, where one item can be selected.

Prerequisites are

• an installed builder plugin
• any source code editor or e.g. the Developer Tools plugin with built-in Code editor like to be seen on the screenshoots

Required skills

• how to work with builder
• how to create a plugin with builder
• how to create tables and forms with builder

Preparations

• a parent table to embed a relation to a child table
• a child table for the items out of which a single one can be choosen for a parent record

First thing is to prepare a child table holding all the information required. Important is one field that is intended to be the one displayed later at the parent form. In our library example it is the field named title.

Next step is to create the model for this table. This can be done by the side menu models and create. The model name should be in singular form, capital first letter. The model in the library example is called Agegroup.


In the model can be defined which table columns are to be displayed in list view…


… and what the form to edit data will look like:

To create a side menu for a table (list view to be precise) a controller is required. On the other hand creating the controller a side menu can be optionally entered.
So it's necessary to create the menu first, then the controller and then go back again to the menu and add the reference to the controller. Or - the more convenient way - to edit the name of the controller to create in advance.
The controller is to edit in the URL line including the path. In the library example this will be pds/library/agegroups

The controller tells OctoberCMS how to handle data. By convention the name of the controller is the name of the table (plural). The related model is the one created before (Agegroup in our example) and the side menu entry is prepared too.

The type of the needed relation has to be defined - as usual - in the parents model php file. This file has been created by the Builder plugin (see step 2) and located in the plugins models directory.
In the library example this is /pds/library/models/Book.php

The code to add the relation to the model is in the example:

<?php
    ...
    
    public $belongsTo = [
        'agegroup' => ['Pds\Library\Models\Agegroup']
    ];
    
    ...    

• 'agegroup' is the reference to address the child model as a variable (from the parent),
• 'Pds\Library\Models\Agegroup' is the path to the child model to be related and embedded in the parent form and list

Unlike the hasOne and hasMany relation the belongsTo relation requires to change the parent table.
To be exact, in the parent table a field is required to hold the id of the related child record.
By default October assumes the name of this field as merging the name of the reference to the child model trailed by '_id': [child model reference]_id.
In our example the name of this field will be agegroup_id



If, because of any reason, the key field in the parent table cannot be named in the pattern of [child model reference]_id the key name has to be defined in the definition of this relation within the parent model (step 5). In our example this could be like:

<?php
    ...
    
    public $belongsTo = [
        'agegroup' => ['Pds\Library\Models\Agegroup',
                       'key' => 'age_id']
    ];
    
    ...    

The final step is to add a field to the parent form view, where the related data can be selected and a column to the list view.

For the form view and the belongsTo relation either a Record finder widget or a Relation widget (which appears as dropdown for a belongsTo relation) can be used. The Record finder gives a more convenient way to select a record, especially if the child table holds a lot of records. If there are only a few to expect in the child table the Relation widget is a good choice too.

Anyhow, if the Record finder is the preferred choice, the most important thing to define ist the List configuration (see the property box at the right in the picture below). Here a reference to the list view of the child model is required. In the library this is $/pds/library/models/agegroup/columns.yaml.
If for some reason the definition of the child list view is not suitable for the Record finder - for example if there are too many columns defined that are not of essence for the selection of a related record - another list view can be defined in the child model. For example to hold only the columns needed. Let's call this additional view columns_finder.yaml. Then the reference has to be $/pds/library/models/agegroup/columns_finder.yaml