Configure Custom Backend Preview for Content Element¶
To allow editors a smoother experience, all custom content elements and plugins should be configured with a corresponding backend preview that shows an approximation of the element’s appearance in the TYPO3 page module. The following sections describe how to achieve that.
A PreviewRenderer
is used to facilitate (record) previews in TYPO3.
The feature consists of two concepts:
PreviewRendererResolver
which is a global implementation to detect whichPreviewRenderer
a given record needs.PreviewRenderer
which is the class responsible for generating the preview and the wrapping.
Writing a PreviewRenderer¶
A custom PreviewRenderer
must implement the interface \TYPO3\CMS\Backend\Preview\PreviewRendererInterface
which contains
the following API methods:
/**
* Dedicated method for rendering preview header HTML for
* the page module only. Receives the the GridColumnItem
* that contains the record for which a preview header
* should be rendered and returned.
*
* @param GridColumnItem $item
* @return string
*/
public function renderPageModulePreviewHeader(GridColumnItem $item): string;
/**
* Dedicated method for rendering preview body HTML for
* the page module only. Receives the the GridColumnItem
* that contains the record for which a preview should be
* rendered and returned.
*
* @param GridColumnItem $item
* @return string
*/
public function renderPageModulePreviewContent(GridColumnItem $item): string;
/**
* Render a footer for the record to display in page module below
* the body of the item's preview.
*
* @param GridColumnItem $item
* @return string
*/
public function renderPageModulePreviewFooter(GridColumnItem $item): string;
/**
* Dedicated method for wrapping a preview header and body
* HTML. Receives $item, an instance of GridColumnItem holding
* among other things the record, which can be used to determine
* appropriate wrapping.
*
* @param string $previewHeader
* @param string $previewContent
* @param GridColumnItem $item
* @return string
*/
public function wrapPageModulePreview(string $previewHeader, string $previewContent, GridColumnItem $item): string;
Note
Further methods are expected to be added in the future to support generic preview rendering, e.g. usages outside PageLayoutView
.
Implementing these methods allows you to control the exact composition of the preview.
This means assuming your PreviewRenderer
returns <h4>Header</h4>
from the header render method and <p>Body</p>
from
the preview content rendering method and your wrapping method does return '<div>' . $previewHeader . $previewContent . '</div>';
then the
entire output becomes <div><h4>Header</h4><p>Body</p></div>
when combined.
Should you wish to reuse parts of the default preview rendering and only change, for example, the method that renders
the preview body content, you can subclass \TYPO3\CMS\Backend\Preview\StandardContentPreviewRenderer
in your
own PreviewRenderer
class - and selectively override the methods from the API displayed above.
Configuring the implementation¶
Individual preview renderers can be defined by using one of the following two approaches:
$GLOBALS['TCA'][$table]['ctrl']['previewRenderer'] = My\PreviewRenderer::class;
This specifies the PreviewRenderer to be used for any record in $table
.
Or if your table has a “type” field/attribute:
$GLOBALS['TCA'][$table]['types'][$type]['previewRenderer'] = My\PreviewRenderer::class;
This specifies the PreviewRenderer only for records of type $type
as determined by the type field of your table.
Or finally, if your table and field have a subtype_value_field
TCA setting (like tt_content.list_type
for example)
and you want to register a preview renderer that applies only when that value is selected (e.g. when a certain plugin type
is selected and you can’t match it with the “type” of the record alone):
$GLOBALS['TCA'][$table]['types'][$type]['previewRenderer'][$subType] = My\PreviewRenderer::class;
Where $type
is for example list
(indicating a plugin) and $subType
is the value of the list_type
field when the
type of plugin you want to target is selected as plugin type.
Note
The recommended location is in the ctrl
array in your extension’s Configuration/TCA/$table.php
or
Configuration/TCA/Overrides/$table.php
file. The former is used when your extension is the one that creates the table,
the latter is used when you need to override TCA properties of tables added by the Core or other extensions.
Overriding the PreviewRendererResolver
¶
If necessary, the PreviewRendererResolver
can be overridden by setting:
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['backend']['previewRendererResolver'] = \TYPO3\CMS\Backend\Preview\StandardPreviewRendererResolver::class;
Once overridden, the old resolver will no longer be consulted.
\TYPO3\CMS\Backend\Preview\PreviewRendererResolverInterface
must be implemented by PreviewRendererResolvers
and
contains a single API method, public function resolveRendererFor($table, array $row, int $pageUid);
which
needs to return a single PreviewRenderer
based on the given input.