From ed2317f997017609b7791b08a05ab50d59c3484d Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 16 Sep 2024 19:02:38 +0200 Subject: [PATCH 1/4] [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} From 470f46f5933aee81590db84aafc3c6118b787d52 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 16 Sep 2024 19:03:46 +0200 Subject: [PATCH 2/4] [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 --- Documentation/ApiOverview/DatabaseRecords/Index.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/ApiOverview/DatabaseRecords/Index.rst b/Documentation/ApiOverview/DatabaseRecords/Index.rst index 618d040a61..2e97b6b373 100644 --- a/Documentation/ApiOverview/DatabaseRecords/Index.rst +++ b/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: From dc73d0c79b5c05668baf545c2abb5ffdabdfa32d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Fr=C3=B6mken?= Date: Thu, 19 Sep 2024 22:22:01 +0200 Subject: [PATCH 3/4] Update Documentation/ApiOverview/DatabaseRecords/Index.rst --- Documentation/ApiOverview/DatabaseRecords/Index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ApiOverview/DatabaseRecords/Index.rst b/Documentation/ApiOverview/DatabaseRecords/Index.rst index 2e97b6b373..b6c5f60607 100644 --- a/Documentation/ApiOverview/DatabaseRecords/Index.rst +++ b/Documentation/ApiOverview/DatabaseRecords/Index.rst @@ -101,7 +101,7 @@ 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: +.. _database-record-objects: Record objects ============== From b553e0d48019eab73207c84e37959bf398c39230 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Fr=C3=B6mken?= Date: Thu, 19 Sep 2024 22:28:20 +0200 Subject: [PATCH 4/4] Apply suggestions from code review --- .../ApiOverview/DatabaseRecords/RecordObjects.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst b/Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst index b3dbb6150e..831dd32359 100644 --- a/Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst +++ b/Documentation/ApiOverview/DatabaseRecords/RecordObjects.rst @@ -1,6 +1,6 @@ :navigation-title: Record objects -.. include:: /Includes.rst.txt -.. _record_objects: +.. include:: /Includes.rst.txt +.. _record_objects: ============== Record objects @@ -30,7 +30,7 @@ In TypoScript you can use the usually in combination with the :ref:`DatabaseQueryProcessor ` to pass record objects to the Fluid templating engine. -.. _record_objects_php: +.. _record_objects_php: Provide records in PHP ====================== @@ -41,7 +41,7 @@ Provide records in PHP In PHP a record object can be created by the :php:`\TYPO3\CMS\Core\Domain\RecordFactory`. -.. _record_objects_fluid: +.. _record_objects_fluid: Use records in Fluid ====================