Content Relationships
The question worth answering precisely: can an editor pick “these 3 cocktails” to showcase on a Product page, or otherwise reference specific other documents on the same site, without hand-authoring the same content twice?
Revised finding. An earlier version of this page said this was entirely unsupported. That was incomplete. “List every document of a given Template” turns out to be native, confirmed via Data Sources & Queries, auto-generated with zero custom code. What’s genuinely still missing is narrower: an editor curating a specific, hand-picked subset.
This is a P1 platform gap, not a Brown-Forman-specific one. Filed here at the top level alongside Site Search and Managing the Header & Footer. Evidence gathered from Brown-Forman’s Products/Cocktails work, approach applicable to any P1 site.
Confirmed: no document-picker field, no cross-document transclusion
Every Puck component instance’s data lives inside the content[] array of the
specific page document that contains it. There’s no P1 concept of a standalone,
referenceable content entity that multiple pages transclude, and no document-picker
field type shipped anywhere in the SDK. This is the same investigation behind
Cocktails Template
(Products/Cocktails cross-linking) and
Form Builder
(reusing one form definition across pages), both hit the identical wall.
What’s actually native: listing everything of a Template
See Data Sources & Queries for the full mechanism.
Short version: creating a Template auto-generates a queryable datasource returning
every document built from it, sorted and paginated, with no custom code. Bind it
into a Grid or List block with {{ }} tokens and it’s live: “show the most recent
6 cocktails” or “show every product in this collection” is solved today, natively.
The gap is filtering, not listing. The auto-generated query’s API
(getResults()) only accepts limit, offset, includeMetadata,
includeSnapshot. No filter parameter. It can give you every Cocktail, sorted; it
cannot give you a specific, arbitrary subset matching some condition, and it
cannot give you the 3 specific documents an editor hand-picked for one page.
The building block for custom, filtered lists: user-authored Data Sources
Also confirmed native (see Data Sources & Queries): an editor or developer can create a custom HTTP JSON datasource directly in the editor’s own “Data sources” panel, scoped globally or to one page, with a template-token URL. Combined with a project’s own filtered API endpoint, this covers “show cocktails matching X” without touching Puck component code, as long as something (a custom API route this project builds) can answer that filtered query over HTTP.
What’s genuinely still missing: editor-curated, hand-picked subsets
The real remaining gap: a searchable, visual “pick specific documents from this
site” field inside the Puck sidebar. Nothing in the SDK or Puck’s own field-type
system gives you a document-picker UI for free. Closing it means building a custom
Puck field type (similar in spirit to what p1-media’s rich mode does for images)
that queries this site’s own documents and renders a picker, real, scoped, buildable
custom-field work, not a config flag.
Once that field exists, the actual list of chosen IDs still needs somewhere to live (as field data on the referencing page) and something to resolve those IDs back into full records at render time, most naturally a user-authored Data Source scoped to that page, parameterized by the chosen IDs.
Recommendation
For “show N of the most recent/all items of type X” (a cocktails index, a recent-products grid): use the native auto-generated Template query now. No new build required.
For “an editor hand-picks these specific N related items” (a curated “Best With” list on a Product page, matching what Cocktails Template actually needs): the honest-effort estimate is real custom field UI work, not a quick win. Scope it as its own small project (a document-picker Puck field type), not something that falls out of Data Sources for free.
Confirmed, not open anymore: neither the auto-generated query nor
documents.list() supports filtering by field or a custom ID set anywhere in the
current API surface. See
Data Sources & Queries
for the full evidence. A custom, project-built API endpoint is genuinely required
for anything beyond sort/pagination, not a config we’re missing.
Open questions for this page now live on Outstanding Questions, tracked centrally across all pages rather than repeated per page.