.. _intrface_themes:

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

Темы
----

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

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

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

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

 .. 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** - логотип в левом свернутом меню

Поддерживаемые форматы логотипов: **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** (:ref:`Раздел администратора<admin>` - Управление системой) в **active-theme**:

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

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

 .. image:: _static/themes/theme_3.png
       :width: 400
       :align: center

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');