Skip to main content

Module reference_index

Module reference_index 

Source
Expand description

Generic reference index — "what links here".

Tracks every inbound reference: page→page links, snippet→page embeds, page→media renditions. Feeds two surfaces:

  1. A "References" panel on the page + snippet editor showing every object that points at the current row.
  2. Cascade-delete warnings ("deleting this snippet will break 12 pages") on the delete confirmation.

Index updater runs from page + snippet save handlers. Reference extraction is a simple scanner over the rendered HTML / persisted JSON shape — looks for known patterns:

  • `href="/some/path"` → page reference (resolved via url_path lookup).
  • `{{ cms_snippet(slug="X") }}` → snippet reference.
  • /__media__/<spec>/<id> → media reference.
  • StreamField block values with `media_id` / `page_id` keys.

Structs§

Reference
One scanned reference (target identity only; the source identity is supplied by the caller).
ReferenceIndex
Referrer
One inbound referrer to a target, aggregated across every field in which it references the target. The title resolves to the referrer’s display name (page / snippet title) for a clickable “used in N places” view; falls back to kind#id.

Constants§

KIND_MEDIA
KIND_PAGE
Resource kind identifiers used in from_kind / to_kind. Strings not enums so plugin types can join the index without code changes.
KIND_SNIPPET

Functions§

aggregate_referrers
Group raw inbound rows by (from_kind, from_id), collecting the distinct field paths in first-seen order. Pure — titles are filled in by usage_summary. The returned length is the aggregate “used in N places” count.
inbound
Every inbound reference to (kind, id). Used by the page + snippet editor’s References panel.
reindex_source
Replace every (from_kind, from_id) row in the index with refs, writing only the difference: rows no longer referenced are deleted, new references inserted, and an unchanged set writes nothing.
scan
Walk haystack looking for media / page / snippet references. Pure: no DB access. Caller resolves `href="/path"` URLs via a follow-up Page lookup if needed.
usage_summary
Aggregated, title-resolved inbound usage for any target (to_kind, to_id) — reused across pages / snippets / media / documents. Page + snippet referrers get their real title resolved in one batched query each; other kinds keep the kind#id fallback.