From ed2317f997017609b7791b08a05ab50d59c3484d Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 16 Sep 2024 19:02:38 +0200 Subject: [PATCH] [FEATURE] Document record objects Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1000 Related: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/91 Releases: main --- .../ApiOverview/DatabaseRecords/Index.rst | 16 ++++ .../DatabaseRecords/RecordObjects.rst | 83 +++++++++++++++++++ .../_CodeSnippets/_FluidUsage.html | 49 +++++++++++ 3 files changed, 148 insertions(+) create mode 100644 Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst create mode 100644 Documentation/ApiOverview/DatabaseRecords/_CodeSnippets/_FluidUsage.html diff --git a/Documentation/ApiOverview/DatabaseRecords/Index.rst b/Documentation/ApiOverview/DatabaseRecords/Index.rst index 2a3be723d7..618d040a61 100644 --- a/Documentation/ApiOverview/DatabaseRecords/Index.rst +++ b/Documentation/ApiOverview/DatabaseRecords/Index.rst @@ -95,6 +95,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 ` +when no :ref:`extbase domain model ` is available. + +Read more in chapter :ref:`record_objects`. + .. _database-records-models: Extbase domain models diff --git a/Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst b/Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst new file mode 100644 index 0000000000..b3dbb6150e --- /dev/null +++ b/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 ` 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 `, +usually in combination with the :ref:`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 ` 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 ` 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 `, 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. diff --git a/Documentation/ApiOverview/DatabaseRecords/_CodeSnippets/_FluidUsage.html b/Documentation/ApiOverview/DatabaseRecords/_CodeSnippets/_FluidUsage.html new file mode 100644 index 0000000000..7185cd1bed --- /dev/null +++ b/Documentation/ApiOverview/DatabaseRecords/_CodeSnippets/_FluidUsage.html @@ -0,0 +1,49 @@ + +{record.title} +{record.uid} +{record.pid} + + +{record.languageId} +{record.languageInfo.translationParent} +{record.languageInfo.translationSource} + + +{record.overlaidUid} + + + + + +{record.mainType} + + +{record.recordType} + + +{record.fullType} + + +{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} + + +{data.computedProperties.versionedUid} +{data.computedProperties.localizedUid} +{data.computedProperties.requestedOverlayLanguageId} +{data.computedProperties.translationSource} + + +{data.versionInfo.workspaceId} +{data.versionInfo.liveId} +{data.versionInfo.state.name} +{data.versionInfo.state.value} +{data.versionInfo.stageId}