Differences

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

--- examples:builder:belongsto_relation [2021/03/28 20:57]
pdsci-admin [Step 5: Define the type of relation]
+++ 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 94: / Line 94: @@
 \\
 Where
-  * //'agegroup'// is the variable to address the relation from the parent model,
+  * //'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
 \\
@@ Line 102: / Line 102: @@
 ===== 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**.\\
-The variable defined in step 5 for the relation has to be added to the parent table as a field to be able to hold the ID of the child 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//
 \\
 \\
@@ Line 108: / Line 110: @@
 \\
 \\
-===== 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|}}
 \\
 \\