Уведомления модуля в шапке

← К обзору UI-вкладов

admin_extension.notifications добавляет элементы в общий колокольчик панели управления AVE.cms. Модуль не рисует ещё одну кнопку: система суммирует все поставщики данных, показывает общий badge и единый список.

Уведомление здесь означает текущее состояние, требующее внимания: новые заказы, непрочитанные обращения, просроченные напоминания. Это не Toast после действия и не постоянный аудит событий.

1. Описание в `module.php`

use App\Adminx\Reminders\Notifications;

'admin_extension' => array(
    'notifications' => array(
        'code' => 'overdue',
        'provider' => array(Notifications::class, 'data'),
        'permission' => 'view_reminders',
        'sort_order' => 30,
    ),
),

Право проверяется до вызова поставщика. Выключенный или деинсталлированный модуль не участвует в общей сводке.

2. Provider

<?php

namespace App\Adminx\Reminders;

defined('BASEPATH') || die('Direct access to this location is not allowed.');

use App\Common\Auth;

class Notifications
{
    public static function data()
    {
        $userId = (int) Auth::id();
        if ($userId < 1) {
            return array();
        }

        $count = Model::overdueCount($userId);
        if ($count < 1) {
            return array();
        }

        return array(array(
            'key' => 'reminders_overdue',
            'title' => 'Просроченные напоминания',
            'text' => 'Срок прошёл — требуют внимания',
            'url' => '/reminders?state=overdue',
            'count' => $count,
            'icon' => 'ti ti-alarm',
            'bg' => 'var(--red-100)',
            'fg' => 'var(--red-600)',
        ));
    }
}

Поставщик может вернуть список напрямую или array('items' => $items). Если элементов нет, возвращайте пустой массив.

3. Формат элемента

Ключ	Назначение
`title`	Обязательный короткий заголовок.
`text`	Пояснение состояния.
`url`	Ссылка. Путь с `/` автоматически получает префикс панели управления.
`count`	Положительное число для общего и строкового badge. `0` скрывает элемент.
`icon`	Класс Tabler-иконки, по умолчанию `ti ti-bell`.
`bg`, `fg`	Фон плитки и цвет иконки.
`key`	Необязательный ключ агрегации в общей summary.

Система автоматически ограничивает визуальный badge значением 99+. Не форматируйте count строкой и не включайте число повторно в title.

Используйте семантический цвет: red для просроченного/критичного, amber для ожидающего действия, blue для нового информационного элемента, green для положительного состояния. Цвет не должен быть единственным носителем смысла.

4. Производительность

Поставщик уведомлений выполняется при построении каждой страницы панели управления. Правильный provider делает один индексируемый COUNT для текущего пользователя или использует краткоживущий кеш.

Нельзя:

загружать все строки только ради count() в PHP;
выполнять внешний HTTP-запрос;
делать отдельный запрос на каждый объект;
бросать исключение при штатно отсутствующей таблице опционального источника;
показывать элементы с count = 0.

Для часто меняющегося счётчика инвалидируйте адресный кеш при изменении сущности, а не очищайте весь кеш системы.

5. Прочитано и скрыто

Общий колокольчик не хранит состояние прочтения. Он каждый раз показывает то, что вернул provider. Переход по ссылке сам по себе не уменьшает count.

Если модулю нужны «прочитано», «отложено» или персональное скрытие, создайте собственную таблицу состояния и учитывайте её в поставщике. POST-действие такого механизма должно проверять CSRF, право и принадлежность записи пользователю.

6. Несколько типов уведомлений

Один provider может вернуть несколько строк, например отдельно критичные и обычные задачи. Можно также объявить список описаний уведомлений с разными правами и поставщиками. Задавайте уникальные code и key, а sort_order используйте для предсказуемого порядка между модулями.

Проверка

без права поставщик не выполняется;
нулевой результат не оставляет пустую строку;
общий badge равен сумме count всех видимых элементов;
относительная ссылка ведёт в текущую панель управления;
поставщик учитывает текущего пользователя и выполняет индексируемый запрос;
отключение модуля убирает его строки и уменьшает общий badge;
ошибки источника не ломают шапку и диагностируются без раскрытия секретов.

6.7 KiB Raw Blame History Unescape Escape