Content lists

Overview

Content lists are saved queries over content entries—similar to “views” in other CMSs. Filter by status, taxonomy term, and custom fields; sort and paginate; expose on the site, in Twig, or via the public API.

Prerequisites

Run migration 058_content_lists.sql via composer migrate before using content lists.

Admin path and permissions

Content → Content lists at /admin/content-lists.

Requires the manage_content_types permission (same gate as content type administration).

Creating a content list

1. Go to /admin/content-lists and click New list.
2. Enter a Name and URL Slug (used in URLs and Twig).
3. Pick a Content type — all results come from this type.
4. Optional: restrict by Statuses (published, draft, …).
5. Optional: filter by a Taxonomy term.
6. Add up to three field filters (e.g. score > 4).
7. Choose Sort (see below).
8. Enable exposure options:
   • Public page — /lists/{slug}?page=2
   • REST API — GET /api/v1/content-lists/{slug}
   • Or use in themes only (no public page required)
9. Save and use Preview to run the query with admin rules.

Field filter operators

Sort options

Sort by entry columns:

• published_at
• updated_at
• created_at
• title
• field:{field_key} — custom field value

Public storefront page

When Public page is enabled:

• URL: /lists/{slug}?page=2
• Theme override: themes/{theme}/views/content_lists/{slug}.twig or fallback content_lists/show.twig
• Default template reuses content index card grid styling

Twig: content_list() function

Embed lists in any theme template. Storefront-safe: embeds use published visibility.

{% set pack = content_list('top-reviews', 6) %}
{% for card in pack.entries %}
  <a href="/{{ pack.type.slug }}/{{ card.row.slug }}">
    {{ card.row.title }}
  </a>
{% endfor %}

Arguments: content_list(slug, limit, page). Returns type metadata and entry card rows.

REST API

GET /api/v1/content-lists/{slug}?page=1

Requires an API key with read scope. Response includes list, meta, and data (entry summaries).

Draft statuses in the list definition require read_drafts scope unless the list is configured as published-only.

Preview

From the list edit screen, click Preview. Preview runs the query with admin rules—drafts appear when selected in status filters.

Migration note

Content lists were added in migration 058_content_lists.sql. If the menu item is missing or saves fail, run composer migrate and confirm your CMS version includes content lists support.

Example scenarios

These patterns show what content lists are for in real projects—not just the admin fields.

Homepage “Top reviews” block

Goal: Show the six highest-scoring published reviews on the home page.

1. Create list slug top-reviews for content type Review.
2. Status: Published only.
3. Field filter: score gte 4 (number field).
4. Sort: field:score descending.
5. In page/home.twig: {% set pack = content_list('top-reviews', 6) %} and loop pack.entries into your card partial.

“Latest from Product news” taxonomy strip

Goal: A blog sidebar with only posts in the Product news category.

1. List slug product-news-latest, type Blog.
2. Taxonomy filter: term Product news.
3. Sort: published_at descending.
4. Embed with content_list('product-news-latest', 5)—no public list page required.

Staff-curated “Featured guides”

Goal: Editors tick a boolean featured on guide entries; marketing displays only those.

1. Add boolean field featured on the Guide type.
2. List filter: featured eq 1.
3. Enable Public page at /lists/featured-guides for a shareable directory, or keep theme-only.

Partner directory (public list URL)

Goal: A standalone /lists/partners page without custom PHP.

1. Type Partner with logo media field and summary text.
2. List: published only, sort by title ascending.
3. Enable Public page; optional theme override content_lists/partners.twig.

Mobile app feed via REST

Goal: Same query as the website, consumed by an iOS app.

1. Enable REST API on list homepage-feed.
2. Create API key with read scope.
3. App calls GET /api/v1/content-lists/homepage-feed?page=1 and maps data to native cells.

Preview before launch

Goal: Verify filters include drafts during QA.

1. Include Draft in status filter temporarily.
2. Click Preview on the list edit screen—preview uses admin rules so drafts appear.
3. Remove draft status before go-live; storefront embeds always use published visibility.

Troubleshooting

• Empty list on site but entries exist — Check field filters, status filters, and publish dates.
• API 403 — API key lacks read or read_drafts as needed.
• Wrong sort order — Custom field sort requires field:{key} syntax and a populated field.