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

← [К разделу «Модули»](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(/* строки колокольчика */),
    'search' => array(
        'provider' => array(GlobalSearchProvider::class, 'search'),
        'permission' => 'view_example',
        'priority' => 60,
        'limit' => 8,
    ),
),
```

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

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

## Результаты в глобальном поиске

Провайдер `search($query, $limit)` подключает сущности модуля к палитре
`Ctrl+K`. Он возвращает список:

```php
return array(array(
    'type' => 'example',
    'group' => 'Примеры',
    'title' => 'Запись #15',
    'subtitle' => 'Дополнительная информация',
    'url' => '/example/15/edit',
    'icon' => 'ti ti-box',
    'score' => 100,
));
```

Нужно обязательно заполнить `title` и локальный `url`. Адрес начинается с `/`
и указывается без имени папки панели: AVE.cms добавит его самостоятельно.
`group` объединяет строки под заголовком, `subtitle` помогает отличить похожие
записи, `icon` принимает класс Tabler Icons, а `score` поднимает точные
совпадения внутри группы.

Поиск вызывается во время набора текста, поэтому используйте индекс или один
короткий SQL-запрос с жёстким `LIMIT`. Право проверяется до запуска provider.
Выключенный или удалённый модуль ничего не добавляет. Ошибка одного модуля не
ломает общую палитру.

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

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