Каждый кто работает с коробочной версией битрикс24 хочет предоставлять пользователям как можно больше родных интерфейсов и как можно меньше писать самому кода (лениво, да и тратить время на ерунду не хочется). Я работаю с битриксом вот уже больше 5 лет и каждый раз сталкиваясь с определенным набором недокументированных возможностей я очень расстраиваюсь отсутствием документации. Не так давно я получил интересный вопрос: как добавить в верхнее меню свой счетчик и понял что данные механики не описаны решил исправить этот пробел.
Счетчики это довольно простой механизм оповещения пользователя о количестве чего-либо требующего реакции пользователя. Количество лидов на ответственном, запущенных бизнес-процессов (требующих реакции пользователя), количество горящих тикетов в системе и многие другие механики отлично покрываются счетчиками.
API
Перед началом работы освежим (или приобретем) знания по работе со счетчиками. За работу счетчиков отвечает класс CUserCounter из модуля main, то есть они всегда доступны в системе.
Счетчик характеризуется следующими аттрибутами:
- user_id - счетчик персональный. Для каждого пользователя он свой
- code - код счетчика (уникальный для счетчика, но для всех пользователей он должен быть один)
- value / cnt - значение счетчика
- site_id - идентфикатор сайта для которого ведется счетчик
Это не единственные параметры которые есть у счетчика. В наличии так же имеются:
- tag - технический тег (по большей части рудимент, обычно не используется, но удобно использовать в рамках модуля)
- last_date - последняя дата 'касания' счетчика
- timestamp_x - дата создания счетчика (по больше части не используется)
- sent (1 если отправлен через push-сервер клиенту, 0 - нет)
Теперь когда мы рассмотрели модель счетчика, перейдем к рассмотрению методов по работе с ними. Хорошая новость: так как счетчик не предполагает наличия сущности, создавать отдельно его не нужно.
Установка счетчика
Одним из основных методов по работе со счетчиками является статический метод Set.
CUserCounter::Set($user_id, $code, $value, $site_id = SITE_ID, $tag = '', $sendPull = true)
Метод задает (создает, если нет, редактирует, если есть) количество элементов для счетчика. Дополнительно есть инкременты и декременты счетчиков.
CUserCounter::Increment($user_id, $code, $site_id = SITE_ID, $sendPull = true, $increment = 1)
CUserCounter::Decrement($user_id, $code, $site_id = SITE_ID, $sendPull = true, $decrement = 1)
Примечание: инкременты/декременты очень удобно при подписках на событиях update/add/delete.
Получение значений
Создать счетчик недостаточно для предоставления бизнес-ценности, без возможности его получения. Для такого случая существует и метод
CUserCounter::GetValue($user_id, $code, $site_id = SITE_ID)
Результатом такой операции является число (по умолчанию 0).
Существуют и другие методы получения значений счетчика, однако это самый удобный: он является оберткой над сложным GetValues и более низкоуровневым чем GetValueByUserID. Если вам потребовались дополнительные методы, вы можете изучить их по коду в ядре продукта.
Очистка и удаление счетчиков
Иногда возникает необходимость провести дополнительные манипуляции: удалить счетчик (например при удалении модуля) или обнулить его значение и платформа предоставляет эти возможности.
Для удаления:
CUserCounter::DeleteByCode($code)
Для очистки:
CUserCounter::Clear($user_id, $code, $site_id = SITE_ID, $sendPull = true, $bMultiple = false)
CUserCounter::ClearByTag($tag, $code, $site_id = SITE_ID, $sendPull = true)
CUserCounter::ClearByUser($user_id, $site_id = SITE_ID, $code = self::ALL_SITES, $bMultiple = false, $sendPull = true)
Лично я не рекомендую использовать очистку счетчиков, так как пользователи могут получить некоторые "лаги" в визуальном интерфейсе. Я рекомендую использовать агент с пересчетом функцией Set.
Пункт меню
Когда мы разобрались с тем что же из себя представляют счетчики и как с ними работать, мы можем приступить к интерфейсу. Нас интересует добавление пункта меню в верхнее горизонтальное меню с указанием количества чего-либо.
Как вы знаете из курсов Bitrix Framework каждое меню характеризуется 4 параметрами:
- название пункта меню
- ссылка
- доп. ссылки для подсветки
- параметры
- ограничения (строковая eval-конструкция возвращающее true, если пункт меню доступен пользователю)
Для простого отображения количества у пункта меню можно передать в параметр специальный ключ counter_num со значением счетчика.
Для большинства задач этого все-таки будет достаточно, т.е. пункт меню
Array(
'Название пункта',
"/menu_link/",
Array(),
Array(
'counter_num' => 7,
),
""
),
Примечание: цифра 7 здесь для обозначения. В реальном же примере я бы рекомендовал сделать класс-прослойку с методом для полчения значения счетчика текущего пользователя, где бы использовал возможности CUserCounter::GetValue
Как уже писал выше - для большинства случаев это будет достаточно, но что делать с желанием обновлять счетчики через push-сервис. Всем же хочется увидеть изменении циферок в реальном времени, а не при обновлении страницы. К сожалению в коробке, по-умолчанию не передаются параметры для автообновления счетчика, но имеется возможность модифицировать код таким образом, чтобы минимальными усилиями получить максимальный результат.
Нам потребуется изменить всего одно действие: в шаблоне компонента меню (/bitrix/templates/bitrix24/components/bitrix/menu/top_horizontal/template.php) нужно перед кодом:
$items[] = $newItem;
добавить:
if ( isset($item["PARAMS"]["counter_id"]) )
{
$newItem['COUNTER_ID'] = $item["PARAMS"]["counter_id"];
}
Тогда мы сможем прописать код нашего счетчика в параметр counter_id и изменение счетчиков через методы, описанные выше, будут автоматически обновляться на страницах пользователей. Полный код пункта меню будет выглядеть так:
Array(
'Название пункта',
"/menu_link/",
Array(),
Array(
"counter_id" => "test-counter-menu",
'counter_num' => 7,
),
""
),
где test-counter-menu - название вашего счетчика (code)
Спасибо за внимание :)
Задавайте интересующие вас вопросы и подкидывайте новые темы для исследования!
