Teaser Block
New in version Volto: 16.14.0
Volto comes with a Teaser block, which when given a content object as a target, is able to pull information from the targeted content object and show it in the block.
By default, this information includes the title
, description
, head_title
, and preview_image
fields.
It shows them in a summary layout, with the image on the left, and the head title, title, and description on the right in order from top to bottom.
Settings
The Teaser has the following settings:
- Target
The target is either an existing content item in your Plone site, or an external URL
- Title
The title is the title of the Teaser block.
By default is copied over from the Teaser target.
- Head title
The head title is a heading that appears above the title of the Teaser Block.
By default is copied over from the Teaser target.
- Description
The description is plain text that summarizes or describes the Teaser.
By default is copied over from the Teaser target.
- Image override
The image override is either an existing image in your Plone site, or an external URL.
It overrides the image provided by the Teaser target.
Style wrapper properties
The Teaser has a styling property to align the image.
The image can be aligned to the left (default), right, or top.
The styling wrapper properties can be extended using the Block style wrapper.
Variations
A Teaser block has a default variation.
A variation can be extended using Block variations.
Data adapter
The Teaser has a data adapter function that allows you to both tap into the changes in the settings and issue changes in other settings fields.
This is valuable in the Teaser block because it saves an internal cache of the target element.
If you select the target, these values are updated.
When you update the target, by default these values remain, but you can issue another behavior.
The data adapter function is defined in the block's setting dataAdapter
.
You can override it and add your own function, if required.
The following is the default adapter.
You should stick to this signature in your custom adapters.
import { isEmpty } from 'lodash';
export const TeaserBlockDataAdapter = ({
block,
data,
id,
onChangeBlock,
value,
}) => {
let dataSaved = {
...data,
[id]: value,
};
if (id === 'href' && !isEmpty(value) && !data.title && !data.description) {
dataSaved = {
...dataSaved,
title: value[0].Title,
description: value[0].Description,
head_title: value[0].head_title,
};
}
onChangeBlock(block, dataSaved);
};
Custom components in registry
The Teaser block looks up a couple of components in the Component registry that you can provide in case you want to modify the default behavior.
Image component
The image component used in the Teaser can be overridden using your own custom image component.
By default, it uses an <img />
tag with the following signature.
<Image
src={hasImageComponent ? href : defaultImageSrc}
alt=""
loading="lazy"
/>
You can register your as:
import Image from './components/Image/MyImageComponent';
...
config.registerComponent({
name: 'Image',
component: Image,
});
Content type dependent Body
component
The Teaser component supports specifying a custom component depending on the target content type.
You can provide your own component, registering a component, for example, in your add-on configuration as shown below.
import NewsItem from './components/Blocks/Teaser/NewsItem';
...
config.registerComponent({
name: 'Teaser',
component: NewsItem,
dependencies: 'News Item',
});
The name
must be Teaser
, but then as a dependency you must provide the name of the content type.
After this, if you select a content type News Item
as the target of the teaser, the Body
component used will be NewsItem
instead of the default one.
Custom Body
component
The Teaser body provides a default Body
component that can be overridden.
Although it can be done via component shadowing, it is recommended that you override it using the variations
block setting field.
import CustomTeaserBlockDefaultBody from './components/Blocks/Teaser';
...
variations: [
{
id: 'default',
isDefault: true,
title: 'Default',
template: CustomTeaserBlockDefaultBody,
},
],
The custom content type Body
component mentioned in the previous section is compatible with this customization.
In this case, the content type customization will take precedence, if it matches with the content type of the target.
Migration from volto-blocks-grid
From Volto 16.14.0 the Teaser block, as it's in the volto-blocks-grid
add-on version 7.0.0, is included in Volto core.
Because of the add-on configuration priority, if you have volto-blocks-grid
installed in your project, the Teaser block from the add-on (and your project amendments to the configuration, if any) will be applied and used.
In case you want to use the core Teaser block, you need to re-apply the core configuration for the Teaser block in your project or add-ons.