SIGNALS Docs

Plugin notification templates

Template fields, merge-field validation and notification seeding.

Declare templates

A notification can declare templates[]; each entry is a ManifestNotificationTemplate. These are communication templates seeded by the plugin lifecycle for warehouses.

Field Type and default Requirement
channel String, email A core logical channel or an installed plugin channel slug
subject String, empty Non-empty
body String, empty Non-empty text or JSON with merge fields
output_type String, text text or json; JSON merge fields belong inside string values
eyebrow Nullable string, null Optional email chrome
footer_context Nullable string, null Optional email chrome
preheader Nullable string, null Optional email chrome
attachments String list, empty Document-template slugs, not numeric IDs

Template logical channels differ from transport names such as mail and database in a notification's channels[]. Attachment slugs resolve to document-template IDs for each warehouse during seeding; a missing slug is not an arbitrary file attachment.

notifications:
  - key: acme.review.completed
    label: Review completed
    channels: [mail, database]
    data_schema:
      groups:
        - label: Review
          fields:
            - path: reference
              label: Review reference
              type: string
    templates:
      - channel: email
        subject: 'Review {{ reference }} completed'
        body: 'Hello {{ user.name }}, your review is ready.'
        eyebrow: '{{ company.name }}'
        attachments: []

Merge fields and validation

Declare payload merge paths as data_schema.groups[].fields[].path, with the ambient paths company.name, user.name and user.email always available. Subject, body and optional chrome are checked. The syntax supports {{ path }} merge fields; it is not Blade. Blade directives, raw {!! !!} output and PHP open tags are rejected.

The six template content rule keys are listed below. The manifest reference lists every rule and its generated validation messages, including these six rows. Invalid declaration shapes also produce {section}.malformed diagnostics with the exact field path; unknown fields produce {section}.unknown_fields. Fix shape errors before debugging template content.

Rule Meaning
notifications.templates.parent Templates need a declared notification key
notifications.templates.channel Logical channel is not supported
notifications.templates.malformed Subject or body is empty
notifications.templates.blade Blade/PHP syntax appears in content or chrome
notifications.templates.attachments Attachments are not a list of non-empty slug strings
notifications.templates.merge_fields A merge path is undeclared and is not ambient

Installation and update seed templates; enable and disable align their active state with the plugin. Uninstall removes plugin communication templates. Send through PluginContext::notify() using the declared notification key and payload; delivery also follows notification channel settings and user preferences.