[FEATURE] Automatically resolve relations for records

Documentation/ColumnsConfig/Type/Category/Index.rst

@@ -17,7 +17,20 @@ is generated automatically.
 ..  literalinclude:: _Snippets/_CategorySimple.php
     :caption: EXT:my_extension/Configuration/TCA/Overrides/someTable.php
 
-The following options can be overridden via :ref:`page TSconfig, TCE form
+..  contents::
+
+..  note::
+
+    It is possible to configure a category tree with `type=select`
+    and `renderType=selectTree` when you want to override specific fields,
+    but in most cases the simplified :php:`category` TCA type is sufficient.
+
+..  _columns-category-tsconfig:
+
+Influencing category trees with page TSconfig
+=============================================
+
+The following options can be overridden via :ref:`page TSconfig, TCEform
 <t3tsref:pageTsConfigTceFormConfig>`:
 
 *   `size`
@@ -26,11 +39,45 @@ The following options can be overridden via :ref:`page TSconfig, TCE form
 *   `readOnly`
 *   `treeConfig`
 
-..  note::
+..  _columns-category-record-objects:
 
-    It is still possible to configure a category tree with `type=select`
-    and `renderType=selectTree` when you want to override specific fields,
-    but in most cases the simplified :php:`category` TCA type is sufficient.
+Category properties in record objects
+=====================================
+
+..  versionadded:: 13.3
+
+If option `relationship <https://docs.typo3.org/permalink/t3tca:confval-category-relationship>`_
+is set to `manyToMany` (default) the `record object <https://docs.typo3.org/permalink/t3coreapi:record-objects>`_
+provides a collection (:php-short:`\TYPO3\CMS\Core\Collection\LazyRecordCollection`)
+of :php-short:`\TYPO3\CMS\Core\Domain\Record` objects, where each represents a
+category record.
+
+The categories can then be displayed like this in Fluid:
+
+..  code-block:: html
+    :caption: Displaying a `manyToMany` relationship to categories in Fluid
+
+    <ul>
+        <f:for each="{myRecord.categories}" as="category">
+            <li>{category.title}</li>
+        </f:for>
+    </ul>
+
+
+..  _columns-category-record-objects-one:
+
+Records that allow a single category (one to one or one to many)
+----------------------------------------------------------------
+
+If option `relationship <https://docs.typo3.org/permalink/t3tca:confval-category-relationship>`_
+is set `oneToMany` or `oneToOne`, the property represents a
+:php-short:`\TYPO3\CMS\Core\Domain\Record` object directly, so it can be output
+like
+
+..  code-block:: html
+    :caption: Displaying a `oneToMany` relationship to categories in Fluid
+
+    My category: {myRecord.category.title}
 
 ..  _columns-category-properties:
 

Documentation/ColumnsConfig/Type/Category/_Properties/_Relationship.rst.txt

@@ -2,7 +2,7 @@
 
 ..  confval:: relationship
     :name: category-relationship
-    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['relationship']
     :type: string
     :Scope: Display  / Proc.
     :RenderType: all

Documentation/ColumnsConfig/Type/Group/Index.rst

@@ -43,6 +43,94 @@ is generated automatically.
     Examples
     StoredDataValues
 
+
+..  _columns-group-record-objects:
+
+Group properties in record objects
+==================================
+
+..  versionadded:: 13.3
+
+..  _columns-group-record-objects-many-to-many:
+
+Many to many relationships in a group field
+-------------------------------------------
+
+If option `relationship <https://docs.typo3.org/permalink/t3tca:confval-category-relationship>`_
+is set to `manyToMany` (default) the `record object <https://docs.typo3.org/permalink/t3coreapi:record-objects>`_
+provides a collection (:php-short:`\TYPO3\CMS\Core\Collection\LazyRecordCollection`)
+of :php-short:`\TYPO3\CMS\Core\Domain\Record` objects, where each represents a
+record of the target table.
+
+..  tabs::
+
+    ..  group-tab:: UML
+
+        ..  uml:: _codesnippets/_many_to_many.plantuml
+            :caption: Students know which courses they are in
+
+    ..  group-tab:: Fluid
+
+        The group fields can then be displayed like this in Fluid:
+
+        ..  code-block:: html
+            :caption: Displaying a `manyToMany` relationship to courses in Fluid
+
+            <ul>
+                <f:for each="{student.courses}" as="course">
+                    <li>{course.title}: ({course.code}), {course.credits}</li>
+                </f:for>
+            </ul>
+
+    ..  group-tab:: TCA
+
+        ..  literalinclude:: _codesnippets/_relationship-many-to-many.php
+
+The relationship in the above example is uni-directional: While students knows
+about their courses, the course would not know which or how many students
+use it
+
+In order to have a true bi-directional many-to-many relationship, table "myitem"
+also need a field pointing to "mytable" and that field must also have the
+relationship many-to-many. Then you can use the option
+`MM_opposite_field  <https://docs.typo3.org/permalink/t3tca:confval-group-mm-opposite-field>`_
+to point from "mytable" to the field in "myitem". If both fields use the same
+`MM  <https://docs.typo3.org/permalink/t3tca:confval-group-mm>`_ table changing
+the relationship on one side also changes the relationship on the other side.
+
+..  _columns-group-record-objects-many-to-one:
+
+Many to one relationships in a group field
+------------------------------------------
+
+If option `relationship <https://docs.typo3.org/permalink/t3tca:confval-category-relationship>`_
+is set `manyToMOne` or `oneToOne`, the property represents a
+:php-short:`\TYPO3\CMS\Core\Domain\Record` object directly, so it can be output
+like
+
+..  tabs::
+
+    ..  group-tab:: UML
+
+        ..  uml:: _codesnippets/_many_to_one.plantuml
+            :caption: Each Course has one Teacher
+
+    ..  group-tab:: Fluid
+
+        The group field can then be displayed like this in Fluid (single record, no loop):
+
+        ..  code-block:: html
+            :caption: Displaying a single `teacher` record in Fluid
+
+            Teacher: {course.teacher.name}
+
+    ..  group-tab:: TCA
+
+        ..  literalinclude:: _codesnippets/_relationship-many-to-one.php
+
+This example is unidirectional: While the course has a teacher assigned, the
+teacher does not know which courses they are teaching.
+
 ..  _columns-group-properties:
 ..  _columns-group-properties-type:
 

Documentation/ColumnsConfig/Type/Group/_Properties/_Relationship.rst.txt

@@ -0,0 +1,58 @@
+..  _columns-group-properties-relationship:
+
+..  confval:: relationship
+    :name: group-relationship
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['relationship']
+    :type: string
+    :Scope: Display  / Proc.
+    :RenderType: all
+    :Default: manyToMany
+
+    ..  versionadded:: 13.3
+
+    This setting influences the `Record object <https://docs.typo3.org/permalink/t3coreapi:database-record-objects>`_
+    representing this database record to be used in Fluid templates.
+
+    If this option is set to
+    `oneToOne` or `manyToOne`, then a :php:`\TYPO3\CMS\Core\Domain\Record` object
+    or :php:`NULL` is provided as value for the field. `maxitems  <https://docs.typo3.org/permalink/t3tca:confval-group-maxitems>`_
+    is automatically set to 1.
+
+    In the other cases a collection
+    (:php:`\TYPO3\CMS\Core\Collection\LazyRecordCollection`) of
+    :php:`\TYPO3\CMS\Core\Domain\Record` objects is attached as value.
+
+    All possible values are:
+
+    `manyToOne`
+        The current record may have a relationship to maximal one record.
+
+    `oneToOne`
+        Same as `manyToOne` but record it references may also just have maximal
+        one relation to the current record type. This is currently not enforced.
+
+    `manyToMany` (default):
+        The current record can have a relationship to multiple records.
+        If `MM  <https://docs.typo3.org/permalink/t3tca:confval-group-mm>`_
+        is set the relation will be stored in an intermediate MM - many to many
+        table. Otherwise it will be stored as comma separated list of integers.
+
+    `oneToMany`
+        Same as `manyToMany` but record it references may just have maximal
+        one relation to the current record type. This is currently not enforced.
+
+    In the following example a group field is displayed as oneToOne:
+
+    ..  code-block:: php
+
+        $GLOBALS['TCA'][$myTable]['columns']['myfield'] = [
+            'config' => [
+                'type' => 'group',
+                'relationship' => 'oneToOne'
+            ]
+        ];
+
+    The behaviour of the TCA option :ref:`maxitems <columns-group-properties-maxitems>`
+    is kept for backward compatibility. This means
+    it is possible to have a :php:`oneToMany` relation with maximum one value
+    allowed.

Documentation/ColumnsConfig/Type/Group/_codesnippets/_many_to_many.plantuml

@@ -0,0 +1,23 @@
+@startuml
+    left to right direction
+
+    entity "Student" as ST {
+      *uid : int
+      *pid : int
+      name : string
+      email : string
+      --
+      courses : LazyRecordCollection<Course>
+    }
+
+    entity "Course" as CO {
+      *uid : int
+      *pid : int
+      title : string
+      code : string
+      credits : int
+    }
+
+    ' Navigability only from student to course
+    ST "0..M" --> "0..N" CO : courses
+    @enduml

Documentation/ColumnsConfig/Type/Group/_codesnippets/_many_to_one.plantuml

@@ -0,0 +1,23 @@
+@startuml
+left to right direction
+
+entity "Course" as CO {
+  *uid : int
+  *pid : int
+  title : string
+  code : string
+  credits : int
+  --
+  teacher : Record<Teacher>
+}
+
+entity "Teacher" as TE {
+  *uid : int
+  *pid : int
+  name : string
+  email : string
+}
+
+CO "0-N" -->  "0-1" TE: teacher
+
+@enduml

Documentation/ColumnsConfig/Type/Group/_codesnippets/_relationship-many-to-many.php

@@ -0,0 +1,11 @@
+<?php
+
+$TCA['tx_myextension_student']['columns']['courses'] = [
+    'label' => 'Courses',
+    'config' => [
+        'type' => 'group',
+        'allowed' => 'tx_myextension_course',
+        'MM' => 'tx_myextension_student_course_mm',
+        'relationship' => 'manyToMany',
+    ],
+];

Documentation/ColumnsConfig/Type/Group/_codesnippets/_relationship-many-to-one.php

@@ -0,0 +1,11 @@
+<?php
+
+$TCA['tx_myextension_course']['columns']['teacher'] = [
+    'label' => 'Teacher',
+    'config' => [
+        'type' => 'group',
+        'allowed' => 'tx_myextension_teacher',
+        // The same teacher can teach several courses
+        'relationship' => 'manyToOne',
+    ]
+];

Documentation/ColumnsConfig/Type/Inline/_Properties/_Relationship.rst.txt

@@ -0,0 +1,59 @@
+..  _columns-inline-properties-relationship:
+
+..  confval:: relationship
+    :name: inline-relationship
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['relationship']
+    :type: string
+    :Scope: Display  / Proc.
+    :RenderType: all
+    :Default: manyToMany
+
+    ..  versionadded:: 13.3
+
+    This setting influences the `Record object <https://docs.typo3.org/permalink/t3coreapi:database-record-objects>`_
+    representing this database record to be used in Fluid templates.
+
+    If this option is set to
+    `oneToOne` or `manyToOne`, then a :php:`\TYPO3\CMS\Core\Domain\Record` object
+    or :php:`NULL` is provided as value for the field. `maxitems  <https://docs.typo3.org/permalink/t3tca:confval-inline-maxitems>`_
+    is automatically set to 1.
+
+    In the other cases a collection
+    (:php:`\TYPO3\CMS\Core\Collection\LazyRecordCollection`) of
+    :php:`\TYPO3\CMS\Core\Domain\Record` objects is attached as value.
+
+    All possible values are:
+
+    `manyToOne`
+        The current record may have a relationship to maximal one record.
+
+    `oneToOne`
+        Same as `manyToOne` but record it references may also just have maximal
+        one relation to the current record type. This is currently not enforced.
+
+    `manyToMany` (default):
+        The current record can have a relationship to multiple records.
+        If `MM  <https://docs.typo3.org/permalink/t3tca:confval-inline-mm>`_
+        is set the relation will be stored in an intermediate MM - many to many
+        table. Otherwise it will be stored as comma separated list of integers.
+
+    `oneToMany`
+        Same as `manyToMany` but record it references may just have maximal
+        one relation to the current record type. This is currently not enforced.
+
+    In the following example an inline field only accepts one record. It
+    is not necessary to set `maxitems  <https://docs.typo3.org/permalink/t3tca:confval-inline-maxitems>`_-
+
+    ..  code-block:: php
+
+        $GLOBALS['TCA'][$myTable]['columns']['myfield'] = [
+            'config' => [
+                'type' => 'inline',
+                'relationship' => 'manyToOne'
+            ]
+        ];
+
+    The limiting behaviour of the TCA option :ref:`maxitems <columns-inline-properties-maxitems>`
+    is kept for backward compatibility. This means
+    it is possible to have a :php:`oneToMany` relation with maximum one value
+    allowed.