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

Темы

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

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

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

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

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

Действие Применить тему доступно для неактивных тем, для текущей темы действие не отображается.

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

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

root:
  theme:
  image:
    apple-touch-icon.png
    apple-touch-icon-precomposed.png
    favicon.ico
    login-logo.png
    logo.png
    menu-left-logo-large.png
    menu-left-logo-small.png
  meta.json
  main.css

где:

  • root - корень архива

  • theme - идентификатор темы

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

  • meta.json - метаданные темы

  • main.css - главный файл со стилями

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

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

  • name - имя темы. Справочная информация;

  • images - ссылки на изображения:

    • favicon - значок для сайта. Поддерживается только ICO формат

    • logo - логотип темы. Будет использоваться при выборе темы

    • login-logo - логотип на странице логина

    • menu-left-logo-large - логотип в левом развернутом меню

    • menu-left-logo-small - логотип в левом свернутом меню

    • apple-touch-icon - логотип, используемый iOS для закладок и сайтов «на домашнем экране»

    • apple-touch-icon-precomposed - логотип, используемый в ранних версиях iOS для закладок и сайтов «на домашнем экране»

Поддерживаемые форматы логотипов: 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 (v2/admin?journalId=ecos-configs&type=JOURNAL) в 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} могут быть:

  1. Реальный идентификатор темы

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

Кэш

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

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

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