Differences

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

--- examples:builder:belongsto_relation [2021/03/28 10:57]
pdsci-admin [What it will look like]
+++ 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 64: / Line 64: @@
 \\
 ===== Step 3: Sidemenu =====
-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.\\
+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 //\\
 {{:examples:builder:belongsto-agegroup.11-sidemenu2.jpg?direct&960|}}
@@ Line 73: / Line 74: @@
 {{:examples:builder:belongsto-agegroup.10-controllercreation1.jpg?direct&960|}}
 \\
+/* {{:examples:builder:belongsto-agegroup.14-sidemenu5.jpg?direct&960|}} */
 \\
-{{:examples:builder:belongsto-agegroup.14-sidemenu5.jpg?direct&960|}}
+===== 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
 \\
-===== Step : =====
 {{: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|}}
 \\
 \\