Listings
A listing answers a question about your records and renders the answer. The same listing definition can produce a page, a block on another page, a table, an RSS feed, a calendar or a kanban board — because what to show and how to show it are separate decisions.
Back office → Structure → Listings.
The parts
| Part | Decides |
|---|---|
| Source | Which records — content type, vocabulary, or another agenda |
| Filters | Which of them — published, in a category, above a price |
| Path filters | Filters taken from the address, so one listing serves many pages |
| Sorts | In what order |
| Fields | What is shown of each record |
| Displays | Where it appears: page, block, feed, table, calendar, board |
| Pager | How many, and how the rest is reached |
Path filters are the powerful part
A path filter takes its value from the address. One listing, one definition, serves every category page you will ever have.
Each path filter decides three things worth understanding:
- When the value is missing — show everything, show nothing, or return not-found. The right answer differs per listing and getting it wrong is how a category page becomes a list of the entire catalogue.
- Whether to validate — a value that is not a real term can be refused cleanly instead of silently matching nothing.
- Whether to include children — "under Inverters" versus "exactly Inverters".
A non-existent term is not a server error
A filter given a value that cannot be a term returns a clean not-found. If you meet an error page instead, report it.
Displays
One definition, several appearances:
- Page — a listing at its own address
- Block — placed on other pages through the layout
- Table — columns, sortable headers
- Feed — RSS for readers and aggregators
- Calendar — anything with a date
- Board — kanban columns from a term field, drag to change
Embedding
A listing can be placed inside a page. It is also the one place where care is needed:
A listing must not embed itself
Directly or through a chain. The platform refuses beyond a small depth and reports the refusal, because the alternative is a page that renders the same panel a thousand times. The symptom is memorable: a page that takes a minute to load while every single query is fast.
Fields, and the link that is not always wanted
Each field in a listing has a formatter, and a field can be rendered as a link to the record or as plain text. Turning the link off is a per-field setting — a title is not automatically a link just because it is a title.
AJAX
Filters, sorting and paging can update in place without a page load. Switch it on per display when the listing is a tool rather than a page.