Link entries to other entries with the entry_refs field type.
Overview
Entry links (reference) fields (entry_refs) let you link one or many published entries—products, authors, locations, related articles—without custom plugins. Values are stored as a JSON array of entry IDs in display order, e.g. [12,34].
Prerequisites
Ensure migration 036_cms_content_fields_entry_refs.sql has been applied (composer migrate) so entry_refs is allowed in cms_content_fields.field_type.
Adding an entry_refs field
- Go to Content → Content types.
- Edit the type and open Fields.
- Add a field; choose type Entry links (reference) (
entry_refs). - Configure settings (see table below).
- Save the type.
Field settings
| Setting | Meaning |
|---|---|
| Target content type | Restrict picks to one type, or any type with a public URL |
| Maximum links | 1 = single reference; up to 100 for multi-select lists |
| Require public targets | When publishing, each linked entry must already be publicly visible |
Admin picker UX
On the entry editor:
- Locate the Entry links field.
- Type in the search box to find entries by title, slug, or ID.
- Click a result to add it to the selected list.
- Selected items appear in order; remove with ×.
- Drag to reorder when multiple links are allowed.
Validation rules
On save, Struxa validates:
- Self-links — An entry cannot reference itself
- Wrong type — Targets must match the configured content type (when restricted)
- Missing entries — Deleted or invalid IDs are rejected
- Unpublished targets — Blocked when Require public targets is enabled and you attempt to publish
Public site rendering
Default entry detail templates render linked titles as a <ul> list. Themes can customize with Twig (below).
Twig: entry_refs_resolve()
{% for ref in entry_refs_resolve(field_value) %}
<a href="{{ ref.public_url }}">{{ ref.title }}</a>
{% endfor %}Pass the raw field value (JSON array string or decoded array). Each ref includes title, slug, public_url, is_public, and related metadata.
REST API
GET /api/v1/content-types/{slug}/entries/{slug} includes referenced_entries on entry_refs fields with title, slug, public_url, is_public, etc.—so headless clients need not resolve IDs manually.
Storage format
Values persist as ordered JSON arrays of integer entry IDs in the field value store, e.g. [12,34,89]. Order in the admin picker is preserved on the storefront.
Troubleshooting
- Cannot publish: unpublished target — Publish linked entries first or disable require-public-targets.
- Search returns no results — Target type filter may exclude the entry; verify type and status.
- Empty list on API — Referenced entry may be draft or lack public route.