.. include:: /Includes.rst.txt
.. _usage:
=====
Usage
=====
Look provides a single Fluid view helper. Wrap it around the frontend markup
of a content element and the page module shows that markup as a real preview.
.. contents::
:local:
:depth: 1
.. _usage-content-blocks:
Previews for Content Blocks
===========================
`Content Blocks `__
render the file :file:`templates/backend-preview.html` of a content block in
the page module. Reuse the frontend rendering there and wrap it in the view
helper:
.. code-block:: html
:caption: EXT:my_site/ContentBlocks/ContentElements/textmedia/templates/backend-preview.html
Three things are worth noting:
* :html:`` with a :html:`Content` section is the
layout Content Blocks provides for backend previews. Without it, Content
Blocks renders the template three times (header, content, footer) and the
preview appears three times.
* The markup inside the view helper is whatever your frontend template
produces. Here it is a Fluid component that receives the record; it could
just as well be a partial or plain HTML. Wrapping the element in the same
container markup as the frontend (:html:``)
makes sure the grid and spacing rules of your CSS apply.
* :html:`css` and :html:`js` take the assets of your frontend build. They
are loaded inside the preview frame only, never in the backend itself.
.. figure:: /Images/PreviewSection.png
:alt: A content element with a coloured section background rendered in the page module
:class: with-shadow
Section backgrounds, decorative borders and buttons come from the site's
own stylesheet.
.. _usage-fluid-templates:
Previews for classic content elements
=====================================
Content element types without Content Blocks can use the view helper in the
Fluid template that TYPO3 renders for the page module preview. Register the
template with page TSconfig:
.. code-block:: typoscript
:caption: EXT:my_site/Configuration/page.tsconfig
mod.web_layout.tt_content.preview.textmedia = EXT:my_site/Resources/Private/Templates/Preview/Textmedia.html
The template receives the raw database row as :html:`{record}` and can wrap
its rendering in the view helper the same way:
.. code-block:: html
:caption: EXT:my_site/Resources/Private/Templates/Preview/Textmedia.html
See the `TSconfig reference `__
for the details of :typoscript:`mod.web_layout.tt_content.preview`.
.. _usage-viewhelper:
The view helper
===============
.. code-block:: html
.. confval-menu::
:name: viewhelper-arguments
:display: table
:type:
:default:
.. confval:: scale
:name: viewhelper-scale
:type: float
:default: extension configuration :confval:`contentPreview.scale ` (0.5)
Factor the frontend is scaled down with inside the preview. :code:`0.5`
shows the site at half size, :code:`1` at its natural size. The frame
is always as wide as the page module column; the scale decides how
much of the frontend width fits into it.
.. confval:: height
:name: viewhelper-height
:type: integer
:default: extension configuration :confval:`contentPreview.height ` (0)
Maximum height of the preview in pixels. Elements that are taller are
cut off and fade out at the bottom, so editors see that there is more.
:code:`0` means no limit: the frame grows with its content.
.. figure:: /Images/PreviewHeightLimit.png
:alt: A preview cut off at a fixed height with a fade-out at the bottom
:class: with-shadow
A preview with :html:`height="250"`. The fade-out marks that the
element continues below.
.. confval:: bodyClass
:name: viewhelper-bodyclass
:type: string
:default: (empty)
Class attribute of the :html:`` inside the preview frame. Use it
when your stylesheet expects a class on the body, for example a theme
or a scope class.
.. confval:: css
:name: viewhelper-css
:type: array
:default: []
Stylesheets to load inside the frame, as :code:`EXT:` paths or public
URLs. Usually the CSS bundle of your frontend build. Look's own small
stylesheet (scaling, fade-out) is always loaded first.
.. confval:: js
:name: viewhelper-js
:type: array
:default: []
JavaScript modules to load inside the frame, as :code:`EXT:` paths or
public URLs. They are loaded as :html:`