Teaser Selection
================
The "teaser_selection" content type is used for displaying teasers to other
content in your website. These teasers could be arranged as list or grid, like
in this example:
.. figure:: ../../img/teaser-selection-web.png
:align: center
In the administration interface, the widget is displayed as a selector for the
teasers. Content managers can choose a number of target contents. By default,
the text from the "Excerpt & Categories" tab of the target content is shown.
You can however customize the text of the teaser if you like.
.. figure:: ../../img/teaser-selection-admin.png
:align: center
Configuration
-------------
Add a field of type "teaser_selection" to your page template:
.. code-block:: xml
Teasers
Twig
----
In Twig, the field contains an array of teasers. Iterate the array and format
the teasers as you like:
.. code-block:: twig
{% for teaser in content.teasers %}
{{ teaser.title }}
{% set teaserImage = sulu_resolve_media(teaser.mediaId, app.request.locale) %}
{% if teaserImage %}
{% endif %}
{{ teaser.description|raw }}
{{ teaser.moreText|default('Read more') }}
{% endfor %}
Each teaser is an object with the following properties:
.. list-table::
:header-rows: 1
* - Property
- Type
- Description
* - id
- string
- The ID of the teaser
* - type (e.g. content or article)
- string
- The type of the teaser
* - locale
- string
- The locale, e.g. "de_AT"
* - title
- string
- The title of the teaser. This is usually taken from the "Excerpt
& Categories" tab of the target content, but can be changed for each
teaser
* - description
- string
- The description of the teaser. This is usually taken from the "Excerpt
& Categories" tab of the referenced content, but can be changed for
each teaser
* - moreText
- string
- The text of the "More" link
* - mediaId
- string
- The ID of the image displayed with the teaser. Defaults to the first
image in the tab "Excerpt & Categories", but can be changed for each
teaser
* - url
- string
- The relative URL of the target content
Parameters
----------
The following parameters can be used to customize the field in the page template:
.. list-table::
:header-rows: 1
* - Parameter
- Type
- Description
* - present_as
- collection
- A collection of strings. Each string is typically a CSS class that is
used to render the teaser list. You can configure the ```` of
each entry that is shown in the admin
* - min
- string
- The minimum number of selected teasers
* - max
- string
- The maximum number of selected teasers
Configurable Presentation
-------------------------
Sometimes, a content manager wants to control exactly how a list of teasers
is presented. You can plan for different rendering variants in your design and
let the content manager choose one variant in the administration interface.
Use the ``present_as`` option to configure the rendering variants:
.. code-block:: xml
Teasers
3 Columns
5 Columns
The content manager can choose one of these variants in the administration
interface:
.. figure:: ../../img/teaser-selection-menu.png
:align: center
The selected value can be used to set the CSS class of the teaser element in Twig:
.. code-block:: twig
Custom Content with Teaser Providers
------------------------------------
If you want to display teasers of custom data, create an implementation of
``TeaserProviderInterface``. For example, we'll make it possible to select
from a list of recipes:
.. code-block:: php
'id'], // The mapping of the teaserItem to the path parameters of the above view (optional)
);
}
/**
* Returns the actual teaser data.
*
* @return Teaser[] The teasers
*/
public function find(array $ids, $locale)
{
if (0 === count($ids)) {
return [];
}
$items = ...; // load items by id
foreach ($items as $item) {
$result[] = new Teaser(...);
}
return $result;
}
}
Register the provider in Symfony's service container and tag it with
``sulu.teaser.provider`` to make it functional:
.. code-block:: xml