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

.. _interface_themes:

Темы
----

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

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

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

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

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

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

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

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

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

.. code-block::

 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**:

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