diff --git a/docs/_static/summary.png b/docs/_static/summary.png new file mode 100644 index 00000000..3fc932ea Binary files /dev/null and b/docs/_static/summary.png differ diff --git a/docs/index.md b/docs/index.md index 733583ab..19f3de26 100644 --- a/docs/index.md +++ b/docs/index.md @@ -160,6 +160,7 @@ We are working at the same time on a new spec for blocks: [The Block Model v3](. :maxdepth: 1 install feature-flags +summary contributing upgrade-guide block-model-v3 diff --git a/docs/summary.md b/docs/summary.md new file mode 100644 index 00000000..7d3e3f5d --- /dev/null +++ b/docs/summary.md @@ -0,0 +1,119 @@ +--- +myst: + html_meta: + 'description': 'How to use the Summary component in Volto Light Theme' + 'property=og:description': 'How to use the Summary component in Volto Light Theme' + 'property=og:title': 'Customizing' + 'keywords': 'Volto Light Theme, summary, listing, teaser, content type' +--- + +# Summary component + +```{versionadded} volto-light-theme 6.0.0-alpha.13 + +``` + +The `Summary` component is used to render key information about a content item in several locations: + +- listing block +- search block +- teaser block + +```{figure} /_static/summary.png +:alt: Screenshot of a Volto listing highlighting the Summary component +:target: /_static/summary.png +The default summary includes the kicker, title, and description. +``` + +## Built-in summary implementations + +Volto Light Theme includes the following summary implementations for core content types: + +- `DefaultSummary`: Includes the kicker, title, and description. This component is used for any content type that doesn't have a specific summary component registered. +- `NewsItemSummary`: Includes the publication date, kicker, title, and description for News Items. +- `EventSummary`: Includes the start and end date, kicker, title, and description for Events. +- `FileSummary`: Includes the file size and type for Files. + +## Register a summary for a content type + +You can create a custom summary implementation and register it for a content type. + +The summary component must accept `item` and `HeadingTag` as props. +Here is an example which renders the publication date for a `Blog Post` content type: + +```js +import { parseDateFromCatalog } from '@kitconcept/volto-light-theme/helpers/dates'; +import FormattedDate from '@plone/volto/components/theme/FormattedDate/FormattedDate'; + +const BlogPostSummary = (props) => { + const { item, HeadingTag = 'h3' } = props; + + const effective = parseDateFromCatalog(item.effective); + const headline = [ + effective ? ( + + ) : null, + item.head_title, + ] + .filter((x) => x) + .flatMap((x) => [' | ', x]) + .slice(1); + + return ( + <> + {headline.length ?
{headline}
: null} + + {item.title ? item.title : item.id} + + {!item.hide_description && ( +

{item.description}

+ )} + + ); +}; + +export default BlogPostSummary; +``` + +The custom summary component must be registered in the Volto registry in your add-on's `applyConfig` function. +For example, this registers the `BlogPostSummary` component as the summary to be used for a custom content type named `Blog Post`: + +```js +import BlogPostSummary from 'volto-my-add-on/components/Summary/BlogPostSummary'; + +const applyConfig = (config) => { + config.registerComponent({ + name: 'Summary', + component: BlogPostSummary, + dependencies: ['Blog Post'], + }); +}; +``` + +## Use the summary component + +You can use the `Summary` component to render a content type anywhere that the summary serialization is available (such as from `items` in the Plone REST API, or the results from the `@querystring-search` endpoint). + +Use it like this: + +```js +import config from '@plone/volto/registry'; +import DefaultSummary from '@kitconcept/volto-light-theme/components/Summary/DefaultSummary'; + +const Summary = + config.getComponent({ + name: 'Summary', + dependencies: [item['@type']], + }).component || DefaultSummary; + +return ; +```