.. _intrface_themes:

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

Темы
----
Основной источник данных: **uiserv/theme**

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

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

 .. image:: _static/themes/theme_1.png
       :width: 700
       :align: center

При загрузке через интерфейс тема формируется 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** - логотип в левом свернутом меню
 
На данный момент сервер никак не обрабатывает стили. Т.е. в архиве желательно грузить сразу минифицированные стили.

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

Журнал с темами можно найти в системных журналах, также данный журнал доступен по прямой ссылке ``http://<Server FQDN>/v2/journals?journalId=ecos-theme``

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

Через интерфейс на данный момент не предусмотрена настройка темы (только через скачивание, изменение и загрузку обратно).
Для хранения текущей темы используется конфигурация в uiserv **active-theme**

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

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

Для изменения текущей темы::

 let rec = Citeck.Records.get('uiserv/config@active-theme');
 rec.att("value", "green-theme");
 rec.save();

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

 {
    "id": "active-theme",
    "title": "Active theme",
    "value": "green-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 Citeck.Records.get('uiserv/meta@').load('attributes.theme-cache-key')