Differences

This shows you the differences between two versions of the page.

--- examples:builder:belongsto_relation [2021/03/28 20:10]
pdsci-admin [Step 4: Create the controller]
+++ examples:builder:belongsto_relation [2021/04/11 19:27] (current)
pdsci-admin [The belongsTo relation]
@@ Line 9: / Line 9: @@
   * Required: a //**parent** table// and a //**child** table//
   * Create a model for the child table with list and form
-  * Add a field named: //[childModelName]// **to the parent table**
+  * Add a field named: //[childModelName]_id// **to the parent table**
   * Extend **the parent controller** with relation behaviour
   * Extend **the parent model** with the desired relation definition (//hasOne//)
@@ Line 76: / Line 76: @@
 /* {{:examples:builder:belongsto-agegroup.14-sidemenu5.jpg?direct&960|}} */
 \\
-===== Step : =====
+===== Step 5: Define the type of relation =====
+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:\\
+<sxh php highlight: [5]>
+<?php
+    ...
+    public $belongsTo = [
+        'agegroup' => ['Pds\Library\Models\Agegroup']
+    ];
+    ...
+</sxh>
+\\
+Where
+  * //'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
+\\
 {{:examples:builder:belongsto-agegroup.15-modelcompletition1.jpg?direct&960|}}
 \\
 \\
-===== Step : =====
+===== Step 6: Add the related field to the parent table =====
+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//
+\\
+\\
 {{:examples:builder:belongsto-agegroup.16-tablecompletition1.jpg?direct&960|}}
 \\
 \\
-===== Step : =====
+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:\\
+<sxh php highlight: [5]>
+<?php
+    ...
+    public $belongsTo = [
+        'agegroup' => ['Pds\Library\Models\Agegroup',
+                       'key' => 'age_id']
+    ];
+    ...
+</sxh>
+\\
+In this case the field in the parent table has to be named //age_id//.
+\\
+\\
+===== Step 7: Add related fields to form and list =====
+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//
+\\
+\\
 {{:examples:builder:belongsto-agegroup.19-modelcompletition3.jpg?direct&960|}}
 \\
 \\