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

← [К разделу «Модули»](README.md)

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

```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(/* строки колокольчика */),
),
```

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

| Вклад | Руководство |
| --- | --- |
| Дашборд | [Разработка виджета](dashboard-widgets.md) |
| Шапка | [Кнопка, dropdown и модальное действие](header-actions.md) |
| Колокольчик | [Поставщик уведомлений](notifications.md) |
| Левое меню | [Descriptor `module.php`](files.md) |

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

`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 модуля: эти
элементы появляются вне собственного маршрута модуля.

```php
'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-кита, не создавая параллельные компоненты.