Настройка темы интерфейса

Темы

Основной источник данных: uiserv/theme

Тема интерфейса - набор ссылок на изображения и стили для визуальной кастомизации Citeck.

Просмотр существующих тем и их редактирования, загрузка новых осуществляется в журнале Темы (Раздел администратора - Конфигурация UI).

Журнал доступен по адресу: http://host/v2/admin?journalId=ecos-theme&type=JOURNAL

Доступные операции с темами: загрузка новой темы, скачивание, удаление существующей.

Через интерфейс на данный момент не предусмотрена настройка темы (только через скачивание, изменение и загрузку обратно).

При загрузке через интерфейс тема формируется zip-архивом и загружается в uiserv.

Структура архива:

root:
       ecos:
          image:
             favicon.ico
             login-logo.png
             logo.png
             menu-left-logo-large.png
             menu-left-logo-small.png
          meta.json
          main.css

где:

root - корень архива
ecos - идентификатор темы
meta.json - метаданные темы
main.css - главный файл со стилями
image - произвольная папка для изображений. Связь между реальным файлом и его идентификатором осуществляется в meta.json

Общий вид meta.json:

{
 "name": {
   "ru": "Тема ECOS",
   "en": "ECOS theme"
 },
 "images": {
   "favicon": "/image/favicon.ico",
   "logo": "/image/logo.png",
   "login-logo": "/image/login-logo.png",
   "menu-left-logo-large": "/image/menu-left-logo-large.png",
   "menu-left-logo-small": "/image/menu-left-logo-small.png"
 }
}

name - имя темы. Справочная информация;
images - ссылки на изображения:
- favicon - значок для сайта. Поддерживается только ICO формат
- logo - логотип темы. Будет использоваться при выборе темы
- login-logo - логотип на странице логина
- menu-left-logo-large - логотип в левом развернутом меню
- menu-left-logo-small - логотип в левом свернутом меню

Поддерживаемые форматы логотипов: jpeg, ico, png (в предстоящем релизе добавлен svg). Размер логотипа не лимитирован.

Кроме логотипов можно менять стили в файле main.css. Через этот файл можно изменить практически любую часть UI, но в общем случае предполагается, что автор изменений хорошо знает как работать со стилями в браузере.

На данный момент сервер никак не обрабатывает стили. Т.е. в архиве желательно грузить сразу минифицированные стили.

Помимо main.css могут быть и другие стили и к ним можно получить доступ по API. В будущем если файл main.css будет отсутствовать, то сервер сгенерирует его из всех css файлов в теме.

Конфигурация active-theme

Для хранения текущей темы используется конфигурация в uiserv active-theme

Для получения текущей темы:

await Records.get('uiserv/config@active-theme').load('value');

Информация об активной теме доступна в журнале Конфигурация ECOS (Раздел администратора - Управление системой) в active-theme:

Для изменения темы укажите ее новое значение в настройке и сохраните:

API

Получение основного файла стилей для темы:

/gateway/uiserv/api/theme/{themeId}/style/main.css

Расширение .css можно не указывать. Вместо main.css могут быть и другие стили, которые есть в теме (учитывается только имя файла без пути до него). Получение изображений:

/gateway/uiserv/api/theme/{themeId}/image/logo

Вместо logo должен быть идентификатор изображения из meta.json темы (images) Вместо {themeId} могут быть:

Реальный идентификатор темы
Константа “active“, с которой идентификатор темы загружается из конфига “active-theme”

Кэш

Все запросы за стилями и изображениями возвращают заголовки кэширования с временем жизни ~4 часа.

Чтобы избежать проблем с кэшем (темы могут меняться “на лету”) нужно добавлять в запросы ключ кэширования, который загружается по следующему API:

await Records.get('uiserv/meta@').load('attributes.theme-cache-key');