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

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

Как-то на семинаре для партнёров услышал вопрос к Сергею Рыжикову из разряда "а когда можно будет использовать компоненты 2.0 в админке сайта". И действительно, это было бы удобнее и привычнее для разработчиков и т.д. Сергей ответил, что "рассматривается такой вариант" и на этом вопрос вроде как закончился. Хотя откуда возник такой вопрос у разработчика и почему Сергей ему не возразил, мне так и не стало понятно. А теперь по сути темы.

Мне достаточно часто приходится создавать страницы для админки и, честно говоря, не видел проблем с подключением самого компонента на странице. Другой вопрос, что это не совсем безопасно, так как функционал компонента другой разработчик может задействовать на публичной части сайта. Да и шаблон компонента надо будет копировать из инстала в папочку с компонентами (при установке модуля, например). Приходилось делать шаблон ".admin", чтобы все понимали, что это шаблон административного раздела. Хорошим тоном у нас считается проверить константу ADMIN_SECTION, чтобы точно знать, что компонент (шаблон) запущен в админке. И не забывать, что константа SITE_ID содержит совсем другой смысловой характер в административном разделе.

Самым большим неудобством в таком "нестандартном" использовании компонентов - постоянное ощущение неуверенности, что кто-либо из разработчиков не задействует случайно его (компонент) в публичке. Вот и получалось, что один компонент с шаблоном ".admin" использовался только раз и только на одной странице. А страниц таких уже с десяток и компоненты эти вперемешку с остальными. В общем некрасиво, "не по книжке" это как-то.

Совсем другой вопрос с гаджетами, которые все почему-то забыли и оставили как бесполезную фичу от разработчиков БУС-а. В принципе, если честно, и сами гаджеты - это не что иное, как вывод компонента bitrix:desktop внутри админки или в соцсетях. Документации по ним не было, на форуме редко кто отвечает. Кое-какое описание есть про сам рабочий стол, но оно для версии 8.5, а уже 12.0.6 во всю крутится. Что же это за зверь такой и как он выглядит с точки зрения разработчика, мало кто знает.

Вот я и решил чуток подразобраться и попробовать использовать этот механизм вместо привычных компонент.


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

Концепция, предложенная разработчиками БУС-а, достаточно проста. Всё тот же контейнер в виде папки в разделе /bitrix/gadgets/_namespace_/, где _namespace_ - ваша коллекция гаджетов. Всё те же файлы .parameters.php и .description.php. При чём они очень напоминают аналогичные файлы в компонентах 2.0 с небольшими дополнениями и нюансами.

Файл index.php выполняет роль скрипта вывода данных (в гаджетах нету раздельных шаблонов вывода и соответственно файлов template.php, result_modifier.php, component_epilog.php). Предполагается, что данных будет немного и весь файл займёт 500-1000 строк, поэтому можно встретить гаджеты в стандартной поставке, которые собирают данные, кэшируют их и тут же выводят. Как, например, гаджет admin_products (/bitrix/gadgets/bitrix/admin_products/).

Файл .parameters.php - параметры гаджета.
Параметры в гаджете - самый важный и интересный для разработчика набор данных. Он, в последствии, снимет кучу головной боли от просьб пользователей что-то показать, убрать, подсветить, поднастроить.....

Содержание файла не сильно отличается от аналогичного файла в компонентах, вряд ли что названия переменных другие. В файле должен быть определён массив всех параметров в переменной $arParameters. Доступны текущие параметры, если заданы, в переменной $arAllCurrentValues.

Структура массива:

$arParameters = Array(
   "PARAMETERS"=> Array(
       "PARAMETER" => array(
           "NAME" => "PARAMETER",          //GetMessage("LANG_PARAMETER"),
           "TYPE" => "LIST",               // LIST, STRING, CHECKBOX
           "VALUES" => array("V1", "V2"),  // array, only for type LIST
           "DEFAULT" => array("V1"),       // string, array
           "MULTIPLE" => "Y",              // N, Y
           "COLS" => 25,                   //numeric
           "ADDITIONAL_VALUES" => "N",     // N, Y
           "REFRESH" => "Y",               // N, Y
           "HIDDEN" => "N",                // N, Y
       ),
   ),
   "USER_PARAMETERS"=> Array(
       "USER_PARAMETER" => Array(
           "NAME" => "USER_PARAMETER",     //GetMessage("LANG_USER_PARAMETER"),
           "TYPE" => "LIST",               // LIST, STRING, CHECKBOX
           "VALUES" => array("V1", "V2"),  // array, only for type LIST
           "DEFAULT" => array("V1"),       // string, array
           "MULTIPLE" => "Y",              // N, Y
           "COLS" => 25,                   //numeric
           "ADDITIONAL_VALUES" => "N",     // N, Y
           "REFRESH" => "Y",               // N, Y
           "HIDDEN" => "N",                // N, Y
       )
   )
);

Поля HIDDEN и COLS еще не успел проверить, но о них речь и не идёт. Главное в массиве разделить поля для параметров гаджета (PARAMETERS) и пользовательские параметры (USER_PARAMETERS). Разница в том, что первые пользователь поменять не может и на странице настроек не видит их. В остальном гаджет работает с параметрами так же, как компонент.

Файл .descrtiption.php - описание гаджета.
Файл описания совсем малюсенький и имеет примерно такой вид:

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();
$arDescription = Array(      
   "LANG_ONLY" => "ru", //ограничение для языка панели
   "NAME" =>GetMessage("MY_GADGET_NAME"),
   "DESCRIPTION" =>GetMessage(" MY_GADGET_ DESC"),
   "ICON" =>"", //полный путь к иконке или название файла иконки в папке гаджета
   "GROUP" => Array("ID"=>"admin_store"),
   "TITLE_ICON_CLASS" => "bx-gadgets-no-padding", //дополнительный CSS-класс для вывода содержимого    
   "AI_ONLY" => true //только в админке
);?>

Тут вроде как всё ясно, кроме группы "GROUP". Дело в том, что можно использовать только определённые заранее группы, свою группу мне так и не удалось создать (выводится надпись "undefined" в меню подключения гаджета). Полный список групп можно подсмотреть в файле "bitrix/components/bitrix/desktop/component.php" в массиве $arGroups.

Можно также передать параметр, чтобы отключить заголовок гаджета, как в гаджетах монитора производительности и резервного копирования.

Файл index.php - вывод данных.
Файл вывода данных содержит всю логику гаджета. Заменяет собой шаблон вывода (по аналогии с template.php в компонентах), подключает скрипты и файлы стилей по необходимости. Особенностью работы скрипта в файле является то, что вывод происходит в буфер, который потом подставляется в определённую ячейку рабочего стола. Это больше связано с реализацией компонента bitrix:desktop и не вызывало особых трудностей (в компонентах 2.0 вывод происходит в буфер глобальной переменной $APPLICATION и сброс можно сделать через $APPLICATION->RestartBuffer(), поэтому в гаджетах может немного изменится код для вывода, например, в AJAX-режиме).

Внутри скрипта доступны две переменные: $arGadgetParams и $arParams. Тут первая переменная будет содержать актуальные параметры гаджета (с установленными пользовательскими парамертами), а $arParams - служебные параметры гаджета.

Для того чтобы реализовать кэширование, достаточно воспользоваться внутренним классом CPHPCache из API, как, например, в гаджете admin_products:

$obCache = new CPHPCache;
$cache_id = "admin_products_".md5(serialize($arFilter))."_".$arGadgetParams["LIMIT"];
if($obCache->InitCache($cache_time, $cache_id, "/"))
{
$arResult = $obCache->GetVars();
}
else
{
   /* Вызов функций, обращение к БД. */
}

if($obCache->StartDataCache())
{
$obCache->EndDataCache($arResult);
}

/** Вывод данных **/

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

Ну во-первых, мой гаджет уже будет доступен на рабочем столе админ панели. Можно также подключить свой гаджет на странице редактирования некой сущности, чтобы создать более удобный интерфейс для оператора. Например, у меня есть гаджет для вывода профайла пользователя (user_profile) и гаджет для зачисления или перевода бонусов (user_bonus). Тогда админстраница выглядела бы вот так:

/**** Заголовок страницы, проверка уровней прав доступа и т.д. *****/
?>

<?$APPLICATION->IncludeComponent(
"bitrix:desktop",
"admin",
Array(
"MODE" => "AI",
"ID" => "my_page_id", //ID собственной страницы админ панели
"MULTIPLE" => "Y",    //разрешено использовать несколько рабочих столов
"CAN_EDIT" => "Y",    //пользователю разрешено изменять параметры, менять местами и т.д.
"COLUMNS" => "2",    //количество колонок на странице
"COLUMN_WIDTH_0" => "50%", //ширина первой калонки в % или в px
"COLUMN_WIDTH_1" => "50%",
"GADGETS" => Array("USER_PROFILE", "USER_BONUS"),  //список разрешенных гаджетов на странице или "ALL" для всех
"G_USER_PROFILE_USER_ID" => $MY_USER_ID,
           "GU_USER_PROFILE_FIELDS" => Array("FULL_NAME", "LOGIN", "EMAIL"),
           "G_USER_BONUS_USER_ID" => $MY_USER_ID,
           "G_USER_BONUS_PAY_SYSTEM" => Array("WEBMONEY", "RBK", ...),  
),
false,
array(
"HIDE_ICONS" => "Y"
)
);?>

/**** Завершение страницы, вывод списка данных или полей для редактирования, или табы другой формы и т.п. *****/


Подключение компонента приведено для версии 12.0.6.

Некоторые замечания и пояснения, которые могут пригодиться.
1. Ключ "MODE" указывает режим подключения и ограничивает список гаджетов. Например, подключены будут только те, у которых в .description.php указано "AI_ONLY"=>true.

2. В массиве с ключом "GADGETS" можно перечислить все допустимые гаджеты (будет наложено ограничение из пункта 1). Или указать Array("ALL"), чтобы подключить все.

3. В ключах по шаблону G_#GADET_ID#_#PARAM# можно указать свои параметры. Например, для гаджетов user_profile и user_bonus в параметре USER_ID я указал переменную $MY_USER_ID, а для гаджета user_bonus в переменной PAY_SYSTEM я указал список доступных платёжных систем. Пользователь не сможет поменять эти настройки, что позволяет ограничивать им действия (в данном примере, платёжные системы) и передавать уже вычисленные данные.

4. Также можно передавать предварительно и пользовательские параметры по шаблону GU_#GADET_ID#_#PARAM#, где #GADGET_ID# - название гаджета в верхнем регистре, #PARAM# - параметр гаджета. Например, я задал заранее список полей, которые будут отображены оператору, и которые он сможет дополнить или поменять.

5. Особым плюсом является возможность определить ID рабочего стола (в моём примере это my_page_id). Это позволяет создавать кастомизированные страницы управления с возможностью настройки рабочего стола пользователем. Двигает куда хочет, включает, выключает. В общем, если операторы и админы часто работают в админке и им постоянно приходится видеть списки каких-либо данных, а разработчику дополнять вывод служебной информацией, то гаджеты тут незаменимы (каждый оператор создаст под себя рабочий стол, настроит поля, а если надо добавит заготовки для быстрого переключения).

Одно плохо. На 25.12.2012 параметр ID рабочего стола в компоненте bitrix:desktop при сохранении постоянно равен admin_index. Думаю, разработчики скоро это поправят (я исправил минут за 15 у себя на дев-сервере). Так что будем подождать чуток.

Назад в раздел