Queries

A view may have a .yml file beside it with the same name. Each key in it becomes a prop on the page; each value is a query Nibble runs before rendering.

A view never fetches anything itself. That is not a style preference: because Nibble runs the queries, it knows exactly what a page depended on, so it can cache the page and clear it precisely when any of that content changes.

# views/guides/index.yml
params: [page]
guides:
  from: entries:guides
  where:
    region: { in: $entry.regions }
  not:
    id: $entry.id
  sort: published_at:desc
  paginate: { per_page: 12 }

The view then receives a guides prop, and page is available as a URL parameter.

The keys

from is required; everything else is optional.

Key	What it does
from	the source: entries:<collection>, terms:<taxonomy>, search, form:<handle>
where	conditions a record must match
not	conditions that exclude a record
q	the search term, for a search source
locale	restrict to one locale
sort	field:asc or field:desc
paginate	{ per_page:, param: } — capped at 100 per page
limit / offset	a fixed slice, when you do not want pagination
include	related records to load alongside
fields	only the fields the view actually uses

Conditions

Conditions take eq, ne, in, lt, lte, gt, gte, null and prefix. Relationship fields also take all and none.

where:
  featured: { eq: true }
  published_at: { lt: now }
  topics: { all: [design, typography] }

Referring to the page being rendered

$entry.<field> is the record the page is about. This is what makes a “related guides” query possible without writing any code:

related:
  from: entries:guides
  where:
    region: { in: $entry.regions }
  not:
    id: $entry.id
  limit: 3

Read aloud: other guides in any of this guide’s regions, but not this one, at most three.

Pagination

A paginated prop arrives as { data, pagination } — the records, and everything needed to draw the links. @nibble’s Pagination component takes the second half and renders them.

Declare the parameter in params so Nibble knows it belongs in the URL and in the cache key.

Mistakes are caught, not ignored

An unknown key is an error rather than a silent no-op, and bin/rails nibble:check reports it with the file it is in. A misspelled sort will fail your check run rather than quietly sorting by nothing in production.