Skip to content

Annotations Overlay

Submodule of Annotations. Surfaces annotation content to users while they work — field-level "?" triggers on entity forms and view pages, modal dialogs with server-rendered content, and annotation text on entity type chooser pages (when "Show overviews on entity select screens" is enabled in module Settings, defaults to On).

Requirements

  • annotations (core Annotations module)

Installation

ddev drush en annotations_overlay
ddev drush cr

What it does

  • Field-level "?" modal triggers on entity edit and add forms. Clicking opens a <dialog> with annotation content for that field. A bundle-level (overview) trigger appears at the top when an overview annotation exists — this is the target's bundle-level slot, covering the entity type as a whole rather than any specific field.
  • View page overlays on entity view pages (e.g. /node/1). Same "?" UX as forms. Opt-in per view mode via Manage Display.
  • Bundle chooser descriptions on entity type chooser pages (e.g. /node/add, /media/add). Bundle-level annotation text appears alongside each content type. Requires "Show overviews on entity select screens" enabled in module settings.
  • Inline paragraph subform overlays inside Paragraphs widget fields. Dialogs are placed inside the Paragraphs field wrapper to survive AJAX replacement when paragraphs are added.
  • Layout Paragraphs component overlays inside component edit dialogs (Mercury Editor / layout_paragraphs widget).
  • "Add {type} annotation" create links inside each dialog, for in-scope types the slot is missing and the viewer may edit. Requires the annotations_ui module; if absent, no links appear.
  • Empty-field "+" triggers on form fields that are in scope but have no annotations yet. Gated by the Show add triggers on targets that have no annotations setting (default off).

Permissions

Permission Notes
view annotations form overlay Seeing "?" triggers and panels on entity edit/add forms and bundle chooser pages. Grant to editor roles.
view annotations view overlay Seeing "?" triggers and panels on entity view pages. Grant to learner/consumer roles.

Per-type consume {type} annotations permissions filter which annotation types appear inside panels.

Opt-in for view page overlays

View page overlays require explicit opt-in per view mode. Go to Manage Display for the content type and drag the Annotations overlay field into a visible region. The Annotation view mode formatter setting controls which annotation view mode is used inside dialogs (default: overlay).

The Annotations overlay field only appears in Manage Display for entity types that have at least one annotation_target configured. If the field is not yet visible after creating a new target, run drush cr.

The Annotation view mode setting defaults to overlay. If no custom display settings exist for that view mode on a given annotation type, Drupal falls back to the default display — annotations will still render. To control exactly which fields appear in dialogs, go to Structure > Annotation types > [type] > Manage Display, enable Use custom display settings for Overlay, and configure it there.

Form overlays are automatic — no Manage Display setup required.

See DEVELOPING.md for template hooks, JS architecture, Claro/Gin bundle chooser quirk, paragraph support internals, the field_group limitation, and parked work.