-
Notifications
You must be signed in to change notification settings - Fork 14
Listing variations with summary component #462
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
e523b8d
a23e6c0
91b08ab
26fc510
86c36ed
14afbb2
2c08290
546e253
8442d4a
f67b239
61274d2
8e1c2e8
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 ? ( | ||
<FormattedDate | ||
key="day" | ||
date={effective} | ||
format={{ | ||
year: 'numeric', | ||
month: 'long', | ||
day: 'numeric', | ||
}} | ||
className="day" | ||
/> | ||
) : null, | ||
item.head_title, | ||
] | ||
.filter((x) => x) | ||
.flatMap((x) => [' | ', x]) | ||
.slice(1); | ||
|
||
return ( | ||
<> | ||
{headline.length ? <div className="headline">{headline}</div> : null} | ||
<HeadingTag className="title"> | ||
{item.title ? item.title : item.id} | ||
</HeadingTag> | ||
{!item.hide_description && ( | ||
<p className="description">{item.description}</p> | ||
)} | ||
</> | ||
); | ||
}; | ||
|
||
export default BlogPostSummary; | ||
``` | ||
|
||
The custom summary component must be registered in the Volto registry in your add-on's `applyConfig` function. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. One of the things that I discussed with @stevepiercy several times is to standardize glossary and concepts. We haven't settled yet on one, but I'd call this "default configuration loader" and try to be consistent everywhere. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @sneridagh I'm happy to update it once there's a glossary entry I can link to. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @stevepiercy how could we do it? More than words, are even concepts... like in this case. "Every time we refer to the |
||
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 <Summary item={item} />; | ||
``` |
Uh oh!
There was an error while loading. Please reload this page.