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

Тема интерфейса — набор логотипов, favicon и CSS-стилей для визуальной кастомизации Citeck под фирменный стиль организации. Тема представляет собой zip-архив, который загружается через интерфейс или API и применяется ко всему приложению.

Статья описывает формат и структуру архива темы, порядок загрузки и применения, API для работы со стилями и изображениями, механизм кэширования, а также примеры CSS-настроек.

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

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

Журнал доступен по адресу: /v2/journals?journalId=ecos-theme&viewMode=table&ws=admin$workspace

Доступные операции с темами: загрузка новой темы (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/journals?journalId=ecos-configs&viewMode=table&ws=admin$workspace) в 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');

Стили 

В активную тему можно добавить кастомный css. Для этого:

Скачайте артефакт готовой темы:

Распакуйте архив:

Откройте main.css

.body {
}

Внесите в него изменения.
Упакуйте в архив (с такой же структурой как был выгружен) и загрузите на стенд:

Обновите страницу.

Настройка ширины выпадающего списка у кнопки Создать 

Например, для настройки ширины выпадающего списка у кнопки Создать:

.body {
}

.ecos-dropdown__menu_new, .ecos-dropdown__menu_new ul {
    max-width: unset !important;
}

Результат: перейдите к кнопке Создать, ширина выпадающего списка будет подстраиваться под длину текста:

Изменение цветовой гаммы темы 

:root {
  --main-bg-color: #fafafa; /*основной фон страницы*/
  --header-bg-color: #002F6C; /*основной фон хедера страницы*/
  --header-component-color: #1e4272dd; /*цвет элементов хедера*/

  --primary-color: #002F6C; /*основной цвет темы*/
  --dark-primary-color: #002350; /*производная от основного цвета*/
  --light-primary-color: #D8E5F8; /*производная от основного цвета*/
}

body {
}

.ecos-sidebar {
  background: #f8fafc; /*фон боковой панели*/
}

.ecos-journal_new .ecos-grid__row_new:not(.ecos-grid__tr_selected):nth-child(odd) {
  background-color: #d8e5f86b !important;  /*чередование строк в таблице*/
}

Результат:

Базовая тема:
Обновленная тема:

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

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

API

Кэш

Стили

Настройка ширины выпадающего списка у кнопки Создать

Изменение цветовой гаммы темы