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 preview renderer is used to facilitate (record) previews in TYPO3. This class is responsible for generating the preview and the wrapping.
Writing a PreviewRenderer¶
A custom preview renderer must implement the interface
\TYPO3\CMS\Backend\Preview\PreviewRendererInterface
which contains
the following API methods:
- interface TYPO3\CMS\Backend\Preview\PreviewRendererInterface¶
Interface PreviewRendererInterface
Contract for classes capable of rendering previews of a given record from a table. Responsible for rendering preview header, preview content and wrapping of those two values.
Responsibilities are segmented into three methods, one for each responsibility, which is done in order to allow overriding classes to change those parts individually without having to replace other parts. Rather than relying on implementations to be friendly and divide code into smaller pieces and give them (at least) protected visibility, the key methods are instead required on the interface directly.
Callers are then responsible for calling each method and combining/wrapping the output appropriately.
- renderPageModulePreviewHeader(TYPO3\\CMS\\Backend\\View\\BackendLayout\\Grid\\GridColumnItem $item)¶
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.
- Parameters
$item (
TYPO3\CMS\Backend\View\BackendLayout\Grid\GridColumnItem
) -- the item
- Return type
string
- renderPageModulePreviewContent(TYPO3\\CMS\\Backend\\View\\BackendLayout\\Grid\\GridColumnItem $item)¶
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.
- Parameters
$item (
TYPO3\CMS\Backend\View\BackendLayout\Grid\GridColumnItem
) -- the item
- Return type
string
Render a footer for the record to display in page module below the body of the item's preview.
- Parameters
$item (
TYPO3\CMS\Backend\View\BackendLayout\Grid\GridColumnItem
) -- the item
- Return type
string
- wrapPageModulePreview(string $previewHeader, string $previewContent, TYPO3\\CMS\\Backend\\View\\BackendLayout\\Grid\\GridColumnItem $item)¶
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.
- Parameters
$previewHeader (
string
) -- the previewHeader$previewContent (
string
) -- the previewContent$item (
TYPO3\CMS\Backend\View\BackendLayout\Grid\GridColumnItem
) -- the item
- Return type
string
Implementing these methods allows you to control the exact composition of the preview.
This means assuming your preview renderer 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 extend
\TYPO3\CMS\Backend\Preview\StandardContentPreviewRenderer
in your custom
preview renderer 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 approaches:
Any record
$GLOBALS['TCA'][$table]['ctrl']['previewRenderer'] = MyVendor\MyExtension\Preview\MyPreviewRenderer::class;
This specifies the preview renderer to be used for any record in
$table
.Table has a type field/attribute
$GLOBALS['TCA'][$table]['types'][$type]['previewRenderer'] = MyVendor\MyExtension\Preview\MyPreviewRenderer::class;
This specifies the preview renderer only for records of type
$type
as determined by the type field of your table.Table and field have a
subtype_value_field
TCA settingIf your table and field have a
subtype_value_field
TCA setting (likett_content.list_type
for example) and you want to register a preview renderer that applies only when that value is selected (assume, 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] = MyVendor\MyExtension\Preview\MyPreviewRenderer::class;
Where
$type
is, for example,list
(indicating a plugin) and$subType
is the value of thelist_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.
Note
The content elements text
, textpic
, textmedia
and
image
have their own PreviewRenderer
. Therefore it's not
sufficient to overwrite the StandardContentPreviewRenderer
but
you need to use the second approach from above for every single of
these content elements.