ave-cms/help/modules/contributions.md

Вклады модуля в интерфейс

← К разделу «Модули»

Установленный и включённый модуль может декларативно добавить пункт меню, действие в шапку, виджет дашборда и строки в общий колокольчик уведомлений. Все вклады принадлежат admin_extension в module.php:

'admin_extension' => array(
    'url' => '/notes',
    'icon' => 'ti ti-notes',
    'feature' => 'Личные заметки',
    'menu' => array(array(
        'code' => 'modules_example', 'label' => 'Пример', 'url' => '/example',
        'permission' => 'view_example', 'parent' => 'modules',
    )),
    'header' => array(/* действие в шапке */),
    'dashboard' => array(/* виджет главной */),
    'notifications' => array(/* строки колокольчика */),
),

Подробные руководства

Вклад	Руководство
Дашборд	Разработка виджета
Шапка	Кнопка, dropdown и модальное действие
Колокольчик	Поставщик уведомлений
Левое меню	Descriptor module.php

Общее описание вклада

header, dashboard и notifications принимают одно описание или список описаний. Общие свойства:

Ключ	Назначение
code	Стабильный код вклада внутри модуля. Особенно важен для порядка виджетов.
provider	Поставщик данных: callable без аргументов, возвращающий массив.
data	Статический массив вместо поставщика данных.
permission	Право, без которого вклад и provider не выполняются.
visible	Необязательный callable без аргументов для дополнительной видимости.
sort_order	Начальный порядок; меньшее значение располагается раньше.
label, description, icon	Представление вклада в настройках интерфейса.

Поставщик вызывается только после проверки права и visible. Его исключение не ломает панель управления, но вклад получит пустые данные. Не рассматривайте это как обработку ошибок: ожидаемые сбои обрабатывайте в provider и журналируйте без секретов.

Доступность и управление

• Деинсталлированный или выключенный модуль не добавляет UI-вклады.
• permission проверяется для текущего системного пользователя.
• На странице Система → Модули администратор может отдельно отключить действие модуля в шапке и его виджет.
• В Основные настройки → Интерфейс можно менять порядок и видимость элементов дашборда.
• Уведомления показываются только при положительном count; отдельного общего переключателя размещения для них нет.

Assets

CSS/JS для шапки и дашборда должны регистрироваться в descriptor модуля: эти элементы появляются вне собственного маршрута модуля.

'assets' => array(
    'styles' => array(
        array('url' => ADMINX_BASE . '/modules/Notes/assets/notes.css', 'priority' => 46),
    ),
    'scripts' => array(
        array('url' => ADMINX_BASE . '/modules/Notes/assets/notes.js', 'priority' => 46),
    ),
),

Стили остаются в assets/<module>.less, JavaScript — в файле модуля под пространстве Adminx.<Module>. Общие примитивы (btn, dropdown, section-header, icon-tile, Adminx.Ajax, Adminx.Toast, Adminx.Confirm) переиспользуйте из UI-кита, не создавая параллельные компоненты.