Cockpit Form Notify

🇬🇧 English | 🇷🇺 Русский

---

English

Cockpit Form Notify

An addon for Cockpit CMS that sends email notifications whenever an item is saved in a Content collection or tree model.

---

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
  • Notification Rules
  • SMTP Settings
  • Placeholders
• Permissions
• License

---

Features

• Email notifications on content save: Automatically send an email whenever a new item is created (or updated) in any Content collection or tree model.
• Flexible notification rules: Create multiple independent rules — each rule targets a specific collection and sends email to one or more recipients.
• New items only: Optionally skip notifications when an existing item is updated, sending emails only when a new item is created.
• Customisable subject and HTML body: Use {{field_name}} placeholders to include any field value from the saved item directly in the subject line and message body.
• Auto-generate HTML template: One-click generation of a ready-made HTML table template from the model's fields.
• Multiple recipients: Specify several comma-separated email addresses per rule.
• Enable / Disable rules: Pause any rule without deleting it.
• SMTP or PHP mail(): Choose between a full SMTP configuration (with authentication, TLS/SSL) or the built-in PHP mail() function.
• Test SMTP connection: Verify that your SMTP credentials are correct without sending a real notification.
• Send test email: Send a test message directly from any rule card to confirm end-to-end delivery.

---

Requirements

• Cockpit CMS: v2.x
• PHP: 8.3+
• At least one Content model of type collection or tree

---

Installation

1. Copy the FormNotify folder to <cockpit_root>/addons/:

   <project_root>/
   └── cockpit/
       └── addons/
           └── FormNotify/
               ├── Controller/
               ├── views/
               ├── admin.php
               ├── bootstrap.php
               ├── icon.svg
               └── info.json
   

2. Optionally copy the translation file to <cockpit_root>/config/i18n/ru/FormNotify.php for Russian localisation.
3. Log in to the Cockpit admin panel.
4. Go to Settings → Form Notify.

---

Configuration

All configuration is done through the Cockpit admin panel (Settings → Form Notify).

SMTP Settings (tab "SMTP Settings")

Field	Description
Method	smtp (recommended) or mail (PHP built-in)
SMTP Host	Hostname of the SMTP server
Port	Typically 587 (TLS) or 465 (SSL)
Encryption	tls, ssl, or none
SMTP Authentication	Enable when the server requires a login and password
SMTP Username / Password	Credentials for the SMTP server
From Email	Sender address that appears in the "From" field
From Name	Sender display name

After filling in the fields, use "Test connection" to verify the SMTP settings, then click "Save settings".

---

Usage

Notification Rules

1. Go to Settings → Form Notify, open the "Notification Rules" tab.
2. Click "Add rule" to create a new rule.
3. Configure the rule:
   • Collection — select the Content model to watch.
   • Notify email(s) — one or more recipient addresses, separated by commas.
   • Email subject — the subject line; supports {{field_name}} placeholders.
   • Email body (HTML template) — the message body; supports {{field_name}} placeholders. Use the "Generate" button to auto-create a table from the model's fields.
   • New items only — when enabled, notifications are sent only when a new item is created, not when existing items are updated.
   • Enabled\Disabled — toggle to enable or disable the rule without deleting it.
4. Click "Save rules" to persist your changes.

Sending a test email

Each rule card has a "Send test email" button. It sends a message using the rule's current subject and template (with placeholder values filled with dummy text) to the rule's configured recipient addresses, letting you verify delivery without touching real data.

Placeholders

Use {{placeholder}} syntax in both the subject and the body template.

Field placeholders — any field defined in the collection model:

{{field_name}}

Meta placeholders — automatically available for every item:

Placeholder	Description
{{_model}}	Name of the collection
{{_created}}	Item creation date/time (dd.mm.yyyy hh:mm:ss)
{{_modified}}	Item last-modified date/time (dd.mm.yyyy hh:mm:ss)

Array field values are serialised as a formatted JSON string.

---

Permissions

The addon registers two permissions under the FormNotify group:

Permission	Description
formnotify/manage	View the addon page, manage notification rules
formnotify/smtp	View and edit SMTP settings, test SMTP connection

Users without formnotify/smtp will not see the SMTP tab and cannot read or modify mail credentials.

---

License

The addon is distributed under the GNU Affero General Public License v3 (AGPLv3).

---

Contacts

Author: Yuriy Plotnikov
Website: https://yuriyplotnikovv.ru
GitHub: https://github.com/YuriyPlotnikovv/cockpit-form-notify/

---

Русский

Cockpit Form Notify

Аддон для Cockpit CMS, который отправляет email-уведомления при каждом сохранении записи в коллекции или дереве Content-модуля.

---

Содержание

• Возможности
• Требования
• Установка
• Конфигурация
• Использование
  • Правила уведомлений
  • Настройки SMTP
  • Плейсхолдеры
• Права доступа
• Лицензия

---

Возможности

• Уведомления при сохранении контента: автоматически отправляет email при создании (или изменении) записи в любой коллекции или дереве Content-модуля.
• Гибкие правила уведомлений: создавайте несколько независимых правил — каждое правило отслеживает отдельную коллекцию и отправляет письмо одному или нескольким получателям.
• Только новые записи: опционально можно отключить уведомления при обновлении существующих записей, получая письма только при создании новых.
• Настраиваемые тема и HTML-тело письма: используйте плейсхолдеры {{field_name}} для подстановки значений полей из сохранённой записи прямо в тему и тело письма.
• Автогенерация HTML-шаблона: одним нажатием создаётся готовая HTML-таблица из полей выбранной коллекции.
• Несколько получателей: можно указать несколько адресов через запятую на одно правило.
• Включение / Отключение правил: приостановите любое правило, не удаляя его.
• SMTP или PHP mail(): выберите полноценную SMTP-конфигурацию (с аутентификацией, TLS/SSL) или встроенную функцию PHP mail().
• Проверка SMTP-соединения: убедитесь в корректности настроек SMTP без отправки реального уведомления.
• Тестовое письмо: отправьте тестовое сообщение прямо с карточки правила, чтобы убедиться в работоспособности всей цепочки доставки.

---

Требования

• Cockpit CMS: v2.x
• PHP: 8.3+
• Хотя бы одна Content-модель типа collection или tree

---

Установка

1. Скопируйте папку FormNotify в директорию <корень_cockpit>/addons/:

   <корень_проекта>/
   └── cockpit/
       └── addons/
           └── FormNotify/
               ├── Controller/
               ├── views/
               ├── admin.php
               ├── bootstrap.php
               ├── icon.svg
               └── info.json
   

2. При необходимости скопируйте файл перевода в <корень_cockpit>/config/i18n/ru/FormNotify.php.
3. Войдите в админ-панель Cockpit.
4. Перейдите в Настройки → Form Notify.

---

Конфигурация

Вся конфигурация выполняется через административную панель Cockpit (Настройки → Form Notify).

Настройки SMTP (вкладка «Настройки SMTP»)

Поле	Описание
Метод	smtp (рекомендуется) или mail (встроенный PHP)
SMTP-хост	Адрес SMTP-сервера
Порт	Обычно 587 (TLS) или 465 (SSL)
Шифрование	tls, ssl или без шифрования
Аутентификация SMTP	Включите, если сервер требует логин и пароль
Пользователь / Пароль SMTP	Учётные данные для SMTP-сервера
Email отправителя	Адрес, который будет отображаться в поле «От»
Имя отправителя	Отображаемое имя отправителя

После заполнения полей используйте «Проверить соединение», чтобы убедиться в корректности настроек, затем нажмите «Сохранить настройки».

---

Использование

Правила уведомлений

1. Перейдите в Настройки → Form Notify, откройте вкладку «Правила уведомлений».
2. Нажмите «Добавить правило» для создания нового правила.
3. Настройте правило:
   • Коллекция — выберите Content-модель, за которой нужно следить.
   • Email получателя(ей) — один или несколько адресов через запятую.
   • Тема письма — строка темы; поддерживает плейсхолдеры {{field_name}}.
   • Тело письма (HTML-шаблон) — тело сообщения; поддерживает плейсхолдеры {{field_name}}. Используйте кнопку «Генерировать» для автоматического создания таблицы из полей коллекции.
   • Только новые записи — если включено, уведомления отправляются только при создании новых записей, но не при редактировании существующих.
   • Включено/выключено — переключатель для включения/отключения правила без его удаления.
4. Нажмите «Сохранить правила», чтобы сохранить изменения.

Отправка тестового письма

На каждой карточке правила есть кнопка «Отправить тестовое письмо». Она отправляет сообщение с использованием текущей темы и шаблона правила (с плейсхолдерами, заполненными тестовыми данными) на адреса, указанные в правиле, позволяя проверить доставку без использования реальных данных.

Плейсхолдеры

Используйте синтаксис {{placeholder}} в теме и шаблоне тела письма.

Плейсхолдеры полей — любое поле из модели коллекции:

{{field_name}}

Мета-плейсхолдеры — автоматически доступны для каждой записи:

Плейсхолдер	Описание
{{_model}}	Название коллекции
{{_created}}	Дата и время создания записи (дд.мм.гггг чч:мм:сс)
{{_modified}}	Дата и время последнего изменения записи (дд.мм.гггг чч:мм:сс)

Значения полей-массивов сериализуются в форматированную JSON-строку.

---

Права доступа

Аддон регистрирует два права доступа в группе FormNotify:

Право	Описание
formnotify/manage	Просмотр страницы аддона, управление правилами уведомлений
formnotify/smtp	Просмотр и редактирование настроек SMTP, проверка соединения

Пользователи без права formnotify/smtp не увидят вкладку SMTP и не смогут читать или изменять параметры почтовых учётных данных.

---

Лицензия

Аддон распространяется под лицензией GNU Affero General Public License v3 (AGPLv3).

---

Контакты

Автор: Yuriy Plotnikov
Сайт: https://yuriyplotnikovv.ru
GitHub: https://github.com/YuriyPlotnikovv/cockpit-form-notify/