Перейти к содержимому
BXWiki

Свой гаджет рабочего стола - файлы, параметры, вывод

Добавляем свой блок на рабочий стол административного раздела: состав файлов, описание, параметры, персональные настройки и аккуратный вывод данных.

Что нужно знать заранее

Гаджет - это блок на стартовой странице административного раздела. Сотрудник сам добавляет его на свой рабочий стол, двигает и настраивает, а разработчик готовит только содержимое блока.

Гаджет описывается набором файлов в своей папке, а не вызовом на странице. Отдельного шаблона у него нет: разметка живёт прямо в исполняемом файле рядом с кодом выборки данных.

У параметров гаджета два уровня: общие и персональные настройки. Общие одинаковы для всех, а персональные каждый сотрудник задаёт себе, и это главное отличие гаджета от обычного компонента.

Шаги

  1. Придумать, какие данные сотрудник хочет видеть сразу после входа в админку.
  2. Создать папку гаджета в каталоге гаджетов, имя папки только строчными буквами.
  3. Описать гаджет и его параметры двумя служебными файлами внутри этой папки.
  4. Написать вывод в исполняемом файле и обязательно обернуть выборку данных кэшем.
  5. Добавить гаджет на рабочий стол и проверить его персональные настройки у сотрудника.

Решение

Раскладываем файлы гаджета:

/bitrix/gadgets/vendor.orders/     ← имя папки строго строчными буквами
├── .description.php               ← название, описание, значок, группа
├── .parameters.php                ← общие и персональные параметры
├── index.php                      ← код и разметка блока, шаблона нет
└── lang/ru/.description.php       ← переводы названий и подписей

Своя папка живёт рядом со штатными гаджетами, но не внутри них. Системные гаджеты не правят: обновление продукта возвращает их файлы в исходное состояние вместе с вашими изменениями.

Описываем гаджет:

.description.php
$arDescription = [
    'NAME' => GetMessage('VENDOR_ORDERS_NAME'),
    'DESCRIPTION' => GetMessage('VENDOR_ORDERS_DESC'),
    'ICON' => '/bitrix/gadgets/vendor.orders/icon.gif',
    'GROUP' => ['ID' => 'sale'],      // раздел, в котором гаджет виден при добавлении
];

Описание - это то, что сотрудник видит при добавлении блока. Понятное название и верная группа экономят время: в списке гаджетов легко потеряться даже на пустом проекте.

Объявляем параметры двух уровней:

.parameters.php
$arParameters = [
    'PARAMETERS' => [
        'PERIOD' => ['NAME' => 'Период, дней', 'TYPE' => 'STRING', 'DEFAULT' => '1'],
    ],
    'USER_PARAMETERS' => [
        'SHOW_SUM' => ['NAME' => 'Показывать сумму', 'TYPE' => 'CHECKBOX', 'DEFAULT' => 'Y'],
    ],
];

Общий параметр задаёт администратор для всех, персональный - каждый сотрудник для себя. Разделение полезное: период считают одинаковым, а показ денег менеджеру и кладовщику нужен разный.

Пишем вывод и бережём скорость:

// index.php - разметка и код в одном файле
$cache = \Bitrix\Main\Data\Cache::createInstance();
if ($cache->initCache(300, 'gadget_orders_' . $arGadgetParams['PERIOD'], '/gadgets')) {
    ['count' => $count, 'sum' => $sum] = $cache->getVars();
} elseif ($cache->startDataCache()) {
    [$count, $sum] = countOrdersForPeriod((int)$arGadgetParams['PERIOD']);
    $cache->endDataCache(['count' => $count, 'sum' => $sum]);
}
echo '<div class="vendor-orders">Заказов: ' . (int)$count . '</div>';

Рабочий стол собирается при каждом входе в административный раздел. Тяжёлый запрос в гаджете растягивает вход для всех сотрудников сразу, поэтому выборку кэшируют на несколько минут.

Кладём гаджет в репозиторий проекта:

Окно терминала
git add -f bitrix/gadgets/vendor.orders
# каталог платформы обычно не версионируется, а свой гаджет потерять легко

Свой гаджет живёт в каталоге платформы и легко теряется при переносе. Его либо добавляют в репозиторий принудительно, либо переносят вместе со списком своих доработок проекта.

Типичные проблемы

Гаджет не появляется в списке добавления.

Имя папки содержит заглавные буквы либо в ней отсутствует файл описания. Папку называют строчными буквами, а описание кладут рядом с исполняемым файлом.

Вход в админку стал заметно медленнее.

Гаджет выполняет тяжёлую выборку при каждой сборке рабочего стола админки. Данные кэшируют на несколько минут прямо внутри кода гаджета.

После обновления продукта гаджет исчез.

Файлы лежали в каталоге платформы и не попали в репозиторий проекта. Свои гаджеты добавляют в репозиторий принудительно и переносят вместе с кодом.

Настройка сотрудника меняется у всех сразу.

Параметр объявлен общим вместо персонального набора настроек. Персональные параметры описывают отдельным набором в файле настроек гаджета.

Правки штатного гаджета откатились после обновления.

Изменялись файлы системных гаджетов платформы, а не своя копия. Свой гаджет делают копией в отдельной папке, а системные не трогают.

Частые вопросы

Чем гаджет отличается от компонента?

У гаджета нет шаблона, разметка лежит в исполняемом файле, и он помнит персональные настройки сотрудника. Компонент ставят на страницу, гаджет - на рабочий стол админки.

Можно ли показать гаджет не всем?

Да, права проверяют внутри самого гаджета и выводят пустой блок или сообщение. Список гаджетов при добавлении общий для всех администраторов.

Что разумно выводить в гаджете?

Короткие числа и списки: новые заказы, остатки на исходе, ошибки обмена. Большие таблицы и отчёты делают отдельной страницей.

Как обновить содержимое без перезагрузки страницы?

Запросом к своему адресу из кода гаджета по таймеру. Делают это редко: рабочий стол не предназначен для монитора в реальном времени.

Работают ли гаджеты в младших редакциях?

Сам механизм рабочего стола есть, а отдельные штатные гаджеты зависят от установленных модулей. Свой гаджет работает там, где есть его данные.

Смежное

Первоисточник