Модуль Интранет > Темы > Основное

Редактор GitHub

В рамках Bitrix Framework, вы уже знаете что за дизайн портала отвечает шаблон, но дополнительное в Битрикс24 существует понятие “Тема” - это набор стилей который применяется к порталу и вносит визуальные изменения не меняя при этом поведение самого портала. В данный момент применение тем является доступным только в разрезе шаблона “Битрикс24: Социальный интранет” (bitrix24), однако технически данный механизм может быть адаптирован и под другие шаблоны.

Table of Contents

Что такое и как работает тема

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

В системе существует 2 типа тем:

  • Системные (доступные изначально)
  • Пользовательские (созданные пользователем)

Пользовательские темы имеют значительные ограничения в кастомизации: допустимо выбрать только базовый цвет текста (светлый/темный), цвет фона и подложку, если необходимо.

Для подложки используйте изображения (jpg, png) и гифки (gif) размером не более 20 Мб и разрешением не больше 5000х5000. Если вы загружаете картинку с пониженной прозрачностью, то также укажите и Цвет фона, который будет видно за загружаемым изображением.

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

Помните что темы зависят от сайта, поэтому работа с ними осуществляется двумя путями:

  • Для работы с конфигурацией через объект класса ThemePicker. Например, для получения списка тем определенного сайта.
  • Для работы с текущим сайтом через singleton-класса ThemePicker.

Класс из пространства имен \Bitrix\Intranet\Integration\Templates\Bitrix24\. Выполняя примеры мы будем предполагать что вы выполнили следующие условия:

  1. Убедились, что подключили модуль Интранет (intranet).
  2. Получили объект класса любым из перечисленным методом.
  3. Добавили в use-раздел namespace:
use \Bitrix\Intranet\Integration\Templates\Bitrix24;

В шаблоне bitrix24 (шаблон по-умолчанию) механизм тем представляет собой слоеный пирог, состоящий из:

  1. Базовой группы (baseTheme)
  2. Тема (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 в результате может получиться в нескольких ситуациях:

  1. entityId параметр не определен
  2. Передан идентификатор несуществующей темы

Получить текущие настройки

Получить 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();