Skip to content

Commit 5bbbe83

Browse files
davisaglidavisagli
committed
revise volto_frontpage
1 parent 7aa9b08 commit 5bbbe83

1 file changed

Lines changed: 39 additions & 37 deletions

File tree

‎docs/mastering-plone/volto_frontpage.md‎

Lines changed: 39 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,13 @@ myst:
33
html_meta:
44
"description": "How to use the listing block with a custom criterion"
55
"property=og:description": "How to use the listing block with a custom criterion"
6-
"property=og:title": "Creating a dynamic front page with Volto blocks"
6+
"property=og:title": "Create a dynamic front page listing"
77
"keywords": "Volto, catalog, index, listing, criteria"
88
---
99

1010
(volto-frontpage-label)=
1111

12-
# Creating a dynamic front page with Volto blocks
13-
14-
Show selected content on the front page by criterion.
12+
# Create a dynamic front page listing
1513

1614
```{card}
1715
In this part you will:
@@ -26,9 +24,7 @@ Tools and techniques covered:
2624

2725
````{card} Frontend chapter
2826
29-
Despite this is a frontend chapter, we are working on **backend** code in `ploneconf.site`.
30-
31-
Checkout `ploneconf.site` at tag "initial":
27+
Check out `mastering-plone-project` at tag `behaviors_1`:
3228
3329
```shell
3430
git checkout behaviors_1
@@ -44,49 +40,60 @@ More info in {doc}`code`
4440
````
4541

4642

47-
We prepared a behavior for content types to store the information if the content should be featured in the previous chapter.
43+
In the previous chapter, we prepared a behavior for content types to store the choice of whether the content should be featured.
4844
And we enhanced the catalog search by adding index and metadata "featured".
4945
Now we turn this into a criterion for a listing block that shows featured content.
5046

5147

5248
(volto-frontpage-criterion-label)=
5349

54-
## Add Index as collection criterion
50+
## Query criteria
5551

56-
To understand why we need a collection criterion for a dynamic front page in Volto and what a collection criterion is, we have to look at the listing block of Volto.
52+
To understand what a query criterion is, we have to look at the listing block of Volto.
5753

5854
```{figure} _static/volto_frontpage.png
5955
:alt: Listing Block sidebar
6056
```
6157

6258
In the sidebar, we see the {guilabel}`Criteria` select menu, and if we click there, it'll show some of the selectable criteria ordered in categories like the following:
6359

64-
- `Metadata` contains indexes that are counting as metadata like Type (means Portal Types) and Review State
65-
- `Text` contains indexes that are counting as text-data like Description and Searchable Text
66-
- `Dates` contains indexes which are working with date-data like Effective Date and Creation Date
60+
- `Metadata` contains indexes that are counting as metadata like Type (meaning content type) and Review State
61+
- `Text` contains indexes that are counting as text data like Description and Searchable Text
62+
- `Dates` contains indexes which are working with date data like Effective Date and Creation Date
63+
64+
These criteria control how the listing is filtered to include the content items we want to show.
6765

68-
To get all talks we marked as `featured` we have to get the listing block to recognize our newly created index.
66+
## Add an index to the query criteria
67+
68+
To get all talks we marked as `featured`, we have to get the listing block to recognize our newly created index.
6969
This means we have to add our index to the collection criteria, to be selectable by the editor.
7070

71-
To add our new index as a criterion to be applicable in a listing block or a collection, we have to switch to our `backend`. There we have to create a plone.app.registry record for our index. This can be achieved by adding a new file {file}`profiles/default/registry/querystring.xml`:
71+
To add our new index as a criterion to be applicable in a listing block or a collection, we have to create a plone.app.registry record for our index.
72+
This can be achieved by adding a new file {file}`backend/src/ploneconf/site/profiles/default/registry/querystring.xml`:
7273

7374
```{code-block} xml
7475
:linenos:
7576
76-
<?xml version="1.0"?>
77+
<?xml version="1.0" encoding="utf-8"?>
7778
<registry xmlns:i18n="http://xml.zope.org/namespaces/i18n"
78-
i18n:domain="plone">
79+
i18n:domain="plone"
80+
>
7981
8082
<records interface="plone.app.querystring.interfaces.IQueryField"
81-
prefix="plone.app.querystring.field.featured">
82-
<value key="title" i18n:translate="">Featured</value>
83-
<value key="enabled">True</value>
84-
<value key="sortable">False</value>
85-
<value key="operations">
86-
<element>plone.app.querystring.operation.boolean.isTrue</element>
87-
<element>plone.app.querystring.operation.boolean.isFalse</element>
88-
</value>
89-
<value key="group" i18n:translate="">Metadata</value>
83+
prefix="plone.app.querystring.field.featured"
84+
>
85+
<value key="title"
86+
i18n:translate=""
87+
>Featured</value>
88+
<value key="enabled">True</value>
89+
<value key="sortable">False</value>
90+
<value key="operations">
91+
<element>plone.app.querystring.operation.boolean.isTrue</element>
92+
<element>plone.app.querystring.operation.boolean.isFalse</element>
93+
</value>
94+
<value key="group"
95+
i18n:translate=""
96+
>Metadata</value>
9097
</records>
9198
9299
</registry>
@@ -95,11 +102,11 @@ To add our new index as a criterion to be applicable in a listing block or a col
95102
To understand this code snippet, we have to know the information and tags we are using:
96103

97104
- The prefix `plone.app.querystring.field.featured` refers to the featured index we just created.
98-
- The operations elements define the provided criterion values to filter the listing.
105+
- The operations elements define which operations can be used when filtering by this index.
99106
- The group value defines the group under which the entry shows up in the selection widget, in our case `Metadata`.
100107

101-
```{note}
102-
For a list of existing QueryField declarations and operations see https://github.com/plone/plone.app.querystring/blob/master/plone/app/querystring/profiles/default/registry.xml
108+
```{tip}
109+
For a list of Plone's default querystring criteria and declarations and operations, see https://github.com/plone/plone.app.querystring/blob/master/plone/app/querystring/profiles/default/registry.xml
103110
```
104111

105112
We can now restart the instance and re-install the add-on.
@@ -108,8 +115,8 @@ We can now restart the instance and re-install the add-on.
108115
## Add a listing block to show the featured content
109116

110117
Now we go back to our frontend.
111-
To create a new listing block on the front-page we have to click on `edit` and then create one new block.
112-
Now you choose the block `Listing` from the menu:
118+
To create a new listing block on the front page we have to click on `edit` and then create one new block.
119+
Choose the block `Listing` from the menu:
113120

114121
```{figure} _static/volto_frontpage_1.png
115122
:alt: Most used blocks in Volto
@@ -123,9 +130,4 @@ You can select the 'featured' criterion:
123130
:align: left
124131
```
125132

126-
## Outlook: Block variations
127-
128-
The listing block comes with default variations for the display.
129-
The editor can choose from these variations to change the template for the listing: with thumbnail image or without, etc..
130-
Your project maybe needs a custom template. The way to go would be to create an additional variation of the listing block.
131-
See {ref}`plone6docs:extensions-block-variations` for more information.
133+
Now the listing shows only the items in the site that have the `featured` checkbox checked.

0 commit comments

Comments
 (0)