В рамках Bitrix Framework, вы уже знаете что за дизайн портала отвечает шаблон, но дополнительное в Битрикс24 существует понятие “Тема” - это набор стилей который применяется к порталу и вносит визуальные изменения не меняя при этом поведение самого портала. В данный момент применение тем является доступным только в разрезе шаблона “Битрикс24: Социальный интранет” (bitrix24), однако технически данный механизм может быть адаптирован и под другие шаблоны.
Table of Contents
Что такое и как работает тема
Тема представляет собой набор css стилей, которые выводятся на страницу после основных стилей портала, таким образом явно получая наибольший приоритет при рендеринге.
В системе существует 2 типа тем:
- Системные (доступные изначально)
- Пользовательские (созданные пользователем)
Пользовательские темы имеют значительные ограничения в кастомизации: допустимо выбрать только базовый цвет текста (светлый/темный), цвет фона и подложку, если необходимо.
Для подложки используйте изображения (jpg, png) и гифки (gif) размером не более 20 Мб и разрешением не больше 5000х5000. Если вы загружаете картинку с пониженной прозрачностью, то также укажите и Цвет фона, который будет видно за загружаемым изображением.
Помимо классификацией по типам существует классификация по месту применения: есть персонализированные темы для конкретных сотрудников, а есть для рабочих групп. У каждого места применения свои особенности: персонализированная тема для сотрудника открывается у любого пользователя который открывает его профиль, а тема для рабочих групп открывается лишь при просмотре группы в слайдере.
Помните что темы зависят от сайта, поэтому работа с ними осуществляется двумя путями:
- Для работы с конфигурацией через объект класса
ThemePicker
. Например, для получения списка тем определенного сайта. - Для работы с текущим сайтом через singleton-класса
ThemePicker
.
Класс из пространства имен \Bitrix\Intranet\Integration\Templates\Bitrix24\
.
Выполняя примеры мы будем предполагать что вы выполнили следующие условия:
- Убедились, что подключили модуль Интранет (
intranet
). - Получили объект класса любым из перечисленным методом.
- Добавили в use-раздел namespace:
use \Bitrix\Intranet\Integration\Templates\Bitrix24;
В шаблоне bitrix24
(шаблон по-умолчанию) механизм тем представляет собой слоеный пирог, состоящий из:
- Базовой группы (
baseTheme
) - Тема (
subTheme
)
В стандартной поставке существует 3 базовых группы: default
, light
, black
. Однако default
является группой с одной темой, так как является базовой для всего шаблона. Все остальные темы могут быть либо light
либо black
, которые различаются цветом шрифта и иконок. В light
цвет будет белым.
В данный момент существует техническое ограничение на количество пользовательских тем - 40. В это число не входят темы которые, поставляются вендором в стандартной поставке, а только создаваемые пользователями. В будущем число может измениться. Актуальное для вашей версии число можно проверить в константе
MAX_CUSTOM_THEMES
класса темы.
API Reference
Ниже мы приведен краткий список php методов класса, которые могут быть полезны при работе с темами.
Получение объекта
Для работы с текущим сайтом можно воспользоваться статическим методом getInstance()
класса ThemePicker
.
/**
* Default type: Bitrix24\ThemePicker::ENTITY_TYPE_USER
* also accepted: Bitrix24\ThemePicker::ENTITY_TYPE_SONET_GROUP
* @var string
*/
$themeType = Bitrix24\ThemePicker::ENTITY_TYPE_USER;
/**
* Get theme picker instance by type
* @param string|null $themeType Theme type, if null - Bitrix24\ThemePicker::ENTITY_TYPE_USER
* @var Bitrix24\ThemePicker
*/
$themePicker = Bitrix24\ThemePicker::getInstance($themeType);
Альтернативный вариант - создание объекта класса через конструктор __construct($templateId, $siteId = false, $userId = 0, $entityType = self::ENTITY_TYPE_USER, $entityId = 0, $params = [])
.
Параметры:
Параметр | Значение |
---|---|
$templateId |
идентификатор шаблона сайта. По-умолчанию в Битрикс24 используется шаблон bitrix24 |
$siteId |
идентификатор сайта. По-умолчанию используется из константы SITE_ID |
$userId |
идентификатор пользователя чьи настройки используем |
$entityType |
тип сущности, над которой выполняется работа Bitrix24\ThemePicker::ENTITY_TYPE_USER или Bitrix24\ThemePicker::ENTITY_TYPE_SONET_GROUP |
$entityId |
идентификатор изменяемого элемента (применимо только к группе) |
$params |
дополнительные параметры |
Пример альтернативного варианта получения объекта темы через конструктор:
/**
* Get theme object for sonet group with id:24
* @var Bitrix24\ThemePicker
*/
$themePicker = new Bitrix24\ThemePicker(
'bitrix24',
's1',
0,
Bitrix24\ThemePicker::ENTITY_TYPE_SONET_GROUP,
24
);
Получение списка доступных тем
Для получения списка тем нужно воспользоваться нестатическим методом getList()
.
$themePicker = Bitrix24\ThemePicker::getInstance();
$themes = $themePicker->getList();
Метод является нестатическим, потому что зависит от идентификатора сайта и шаблона, которые являются частью Bitrix Framework.
Установка темы
Для установки темы используется нестатический метод setCurrentThemeId($themeId, $currentUserId = 0): bool
, который в случае с пользователем меняет его тему, а в случае с группой производит изменение темы (не путать с тематикой) группы (без проверки прав).
Параметр | Значение |
---|---|
$themeId |
идентификатор устанавливаемой темы |
$currentUserId |
если ThemePicker создан для сотрудника записывает его как установившего тему, для группы игнорируется |
Например, если мы заходим для пользователя ID:3
в шаблоне bitrix24
сайта s1
установить тему light:tulips
, то мы можем использовать следующий код:
use \Bitrix\Intranet\Integration\Templates\Bitrix24;
$themePicker = new Bitrix24\ThemePicker(
'bitrix24',
's1',
0,
Bitrix24\ThemePicker::ENTITY_TYPE_USER,
3
);
if ( $themePicker->setCurrentThemeId('light:tulips', 3) )
{
echo "Ok";
}
else
{
echo "Bad";
}
При этом false
в результате может получиться в нескольких ситуациях:
-
entityId
параметр не определен - Передан идентификатор несуществующей темы
Получить текущие настройки
Получить ID текущей темы можно через нестатический метод getCurrentThemeId()
.
Например, выполнив в контексте страницы следующий код, можно получить идентификатор текущей темы.
$themePicker = Bitrix24\ThemePicker::getInstance();
echo $themePicker->getCurrentThemeId(); // echo "light:tulips";
Получить конфигурацию текущей темы можно через нестатический метод getCurrentTheme()
.
Например, если выполнить в контексте страницы этот метод для сотрудника ID:3 с ранее установленной темой “Тюльпаны”, то можно получить следующую информацию:
$themePicker = Bitrix24\ThemePicker::getInstance();
var_dump($themePicker->getCurrentThemeId());
/*
Display:
array(9) {
["title"]=>
string(16) "Тюльпаны"
["prefetchImages"]=>
array(1) {
[0]=>
string(57) "/bitrix/templates/bitrix24/themes/light/tulips/tulips.jpg"
}
["previewImage"]=>
string(65) "/bitrix/templates/bitrix24/themes/light/tulips/tulips-preview.jpg"
["width"]=>
int(1920)
["height"]=>
int(1080)
["resizable"]=>
bool(true)
["id"]=>
string(12) "light:tulips"
["removable"]=>
bool(false)
["css"]=>
array(3) {
[0]=>
string(64) "/bitrix/templates/bitrix24/themes/light/main.css?161623183441092"
[1]=>
string(63) "/bitrix/templates/bitrix24/themes/light/menu.css?16162318346915"
[2]=>
string(69) "/bitrix/templates/bitrix24/themes/light/tulips/style.css?160466563191"
}
}
*/
Обратите внимание, что в ключе css
массива описывающего темы можно увидеть несколько путей к css-файлам.
Часть файлов (light/main.css
, light/menu.css
) относятся к базовой группе, а часть (light/tulips/style.css
) к самой теме.
Получить идентификаторы базовой группы и темы установленных в данный момент можно через нестатические методы getCurrentBaseThemeId()
и getCurrentSubThemeId()
соответственно
Создание пользовательской темы
За создание отвечает нестатический метод create(array $fields)
.
Обратите внимание: метод бросает исключение \Bitrix\Main\SystemException
, поэтому необходимо обрабатывать вызов через try-catch конструкцию.
Структура параметра $fields
:
Ключ | Значение |
---|---|
bgColor |
hex-код цвета (#ffffff или #fff) |
bgImage |
структура из \CFile::MakeFileArray() |
textColor |
цвет текста (доступно только dark и light ) |
Пример создания темы с красным фоном:
try
{
$themePicker = Bitrix24\ThemePicker::getInstance();
$newThemeId = $themePicker->create([
'bgColor' => '#ffffff',
'textColor' => 'light'
]);
// Result example $newThemeId = "bitrix24:custom_123454789"
}
catch( \Bitrix\Main\SystemException $e )
{
echo $e->getMessage();
}
Удаление пользовательской темы
Подобно созданию темы существует механизм удаления пользовательских тем, осуществляемый нестатическим методом remove($themeId)
.
Возвращается значение типа boolean
: false
в случае попытки удаления не пользовательской темы и true
во всех остальных случаях.
Пример удаление пользовательской темы:
$themePicker = Bitrix24\ThemePicker::getInstance();
$themePicker->remove('"bitrix24:custom_123454789"');
Права
Бывают ситуации, когда перед работой определенного механизма необходимо проверять права на совершаемую операцию. Механизм тем так же снабжен данной возможность и позволяет проверить одно право: наличие возможности устанавливать тему по-умолчанию. За это отвечает статический метод canSetDefaultTheme()
, его действие вы можете рассмотреть на примере:
/**
* True if current user can set default theme
* @var boolean
*/
$canSetDefaultTheme = Bitrix24\ThemePicker::canSetDefaultTheme();