[FEATURE] Document record objects

Documentation/ApiOverview/DatabaseRecords/Index.rst

@@ -20,6 +20,12 @@ for managing content and data within the system.
 ..  contents::
     :caption: Content on this page
 
+..  toctree::
+    :caption: Subpages
+    :glob:
+
+    *
+
 ..  _database-records-examples:
 
 Common examples of records in TYPO3:
@@ -95,6 +101,22 @@ subtypes in use where the field `CType` contains the value "list" and the field
 `list-type` contains the actual type. This second level of types exists for
 historic reasons. Read more about it in chapter :ref:`content-element-and-plugin`.
 
+.. _database-record-objects:
+
+Record objects
+==============
+
+..  versionadded:: 13.2
+    Record objects have been introduced as an experimental feature.
+
+Record objects are instances of :php:`\TYPO3\CMS\Core\Domain\Record` and
+contain an object-oriented representation of a database record.
+
+A record object can be used to output a database record in :ref:`Fluid <fluid>`
+when no :ref:`extbase domain model <database-records-models>` is available.
+
+Read more in chapter :ref:`record_objects`.
+
 .. _database-records-models:
 
 Extbase domain models

Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst

@@ -0,0 +1,83 @@
+:navigation-title: Record objects
+.. include:: /Includes.rst.txt
+.. _record_objects:
+
+==============
+Record objects
+==============
+
+..  versionadded:: 13.2
+    Record objects have been introduced as an experimental feature.
+
+Record objects are instances of :php:`\TYPO3\CMS\Core\Domain\Record`.
+
+They are an advanced data object holding the data of a database row, taking the
+:ref:`TCA definition <t3tca:start>` and possible relations of that database row
+into account.
+
+..  note::
+
+    The Record object is available but still considered experimental. Only the
+    usage in Fluid is public API.
+
+.. _record_objects_typoscript:
+
+Provide Records in TypoScript
+=============================
+
+In TypoScript you can use the
+:ref:`RecordTransformationProcessor <t3tsref:RecordTransformationProcessor>`,
+usually in combination with the :ref:`DatabaseQueryProcessor <t3tsref:DatabaseQueryProcessor>`
+to pass record objects to the Fluid templating engine.
+
+.. _record_objects_php:
+
+Provide records in PHP
+======================
+
+..  note::
+    Creating record objects in PHP is considered experimental.
+
+In PHP a record object can be created by the
+:php:`\TYPO3\CMS\Core\Domain\RecordFactory`.
+
+.. _record_objects_fluid:
+
+Use records in Fluid
+====================
+
+In frontend templates the record object is provided by
+:ref:`TypoScript <record_objects_typoscript>` or passed to Fluid by a
+:ref:`PHP class`.
+
+Content element preview templates automatically receive a record object
+representing the record of the content element that should currently be displayed.
+
+..  todo: Link Content element preview templates once documented
+
+The :ref:`Debug ViewHelper <f:debug> <t3viewhelper:typo3-fluid-debug>` output
+of the Record object is misleading for integrators,
+as most properties are accessed differently as one would assume.
+
+We are dealing with an object here. You however can access your record
+properties as you are used to with :fluid:`{record.title}` or
+:fluid:`{record.uid}`. In addition, you gain special, context-aware properties
+like the language :fluid:`{record.languageId}` or workspace
+:fluid:`{data.versionInfo.workspaceId}`.
+
+Overview of all possibilities:
+
+..  literalinclude:: _CodeSnippets/_FluidUsage.html
+    :caption: Demonstration of available variables in Fluid
+
+.. _record_objects_fluid-raw:
+
+Using the raw record
+--------------------
+
+The :php-short:`\TYPO3\CMS\Core\Domain\RecordFactory` object contains
+only the properties, relevant for
+the current :ref:`record type <database-records-types>`, for example `CType`.
+In case you need to access properties, which are not defined for the record
+type, the "raw" record can be used by accessing it via
+:fluid:`{record.rawRecord}`. Those properties are not transformed.

Documentation/ApiOverview/DatabaseRecords/_CodeSnippets/_FluidUsage.html

@@ -0,0 +1,49 @@
+<!-- Any property, which is available in the Record (like normal) -->
+{record.title}
+{record.uid}
+{record.pid}
+
+<!-- Language related properties -->
+{record.languageId}
+{record.languageInfo.translationParent}
+{record.languageInfo.translationSource}
+
+<!-- The overlaid uid -->
+{record.overlaidUid}
+
+<!-- Types are a combination of the table name and the Content Type name. -->
+<!-- Example for table "tt_content" and CType "textpic": -->
+
+<!-- "tt_content" (this is basically the table name) -->
+{record.mainType}
+
+<!-- "textpic" (this is the CType) -->
+{record.recordType}
+
+<!-- "tt_content.textpic" (Combination of mainType and record type, separated by a dot) -->
+{record.fullType}
+
+<!-- System related properties -->
+{data.systemProperties.isDeleted}
+{data.systemProperties.isDisabled}
+{data.systemProperties.isLockedForEditing}
+{data.systemProperties.createdAt}
+{data.systemProperties.lastUpdatedAt}
+{data.systemProperties.publishAt}
+{data.systemProperties.publishUntil}
+{data.systemProperties.userGroupRestriction}
+{data.systemProperties.sorting}
+{data.systemProperties.description}
+
+<!-- Computed properties depending on the request context -->
+{data.computedProperties.versionedUid}
+{data.computedProperties.localizedUid}
+{data.computedProperties.requestedOverlayLanguageId}
+{data.computedProperties.translationSource} <!-- Only for pages, contains the Page model -->
+
+<!-- Workspace related properties -->
+{data.versionInfo.workspaceId}
+{data.versionInfo.liveId}
+{data.versionInfo.state.name}
+{data.versionInfo.state.value}
+{data.versionInfo.stageId}