imagecms/ImageCMS

#Template Manager 

##Загальна інформація по структурі шаблону 
Крім дерева js-, css- та tpl-файлів  шаблон повинен містити такі файли та каталоги
* params.xml - містить основну інформацію про шаблон, а також дані що потрібні для інсталяції шаблону. 
* tlicense.key - ключ ліцензії. Повинен містити кожен шаблон (платний і безплатний). Ліцензія прив’язується до домену на якому розташований сайт. Ключ формується автоматично при скачуванні шаблону із магазину доповнень imagecms.net/addons по домену що був вказаний в замовленні. 
* components (необов’язково) - може містити компоненти шаблону

## Опис файлу param.xml ([Приклад  файла params.xml](https://github.com/imagecms/ImageCMS/blob/template_manager/templates/newLevel_TM/params.xml))
* Дані про шаблон: 
    * атрибут **label** кореневого тегу - назва шаблону для відображення 
    * атрибут **type** кореневого тегу - тип шаблону (shop|corporate)
    * атрибут **version** кореневого тегу - версія шаблону 
    * тег **description** повинен містити повний опис шаблону
    * тег **screenshots** вказує ша шляхи до скріншотів шаблону, що будуть відображатись при його перегляді. Атрибутом main="1" можна вказати обкладинку шаблону (головне зображення що буде відображатись в списку)
* Залежності: 
Тег **dependencies** може містити інформацію про модулі та віджети що повинні бути встановлені для правильного відображення шалону. Деякі віджети (із типом HTML) можуть бути встановлені із інформації у файлі параметрів. 

Кожна окрема залежність визначається тегом dependency, що має такі атрибути:
* **entityName** - обробник залежності. Визначає клас що обробляє дані кожного виду залежності. Доступні значення: module та widget
* **name** - назва модуля або віджета 
* **type** - тип залежності. Всього є три типи залежностей: 
    * **required** - залежність вимагається, та якщо не буде встановлена в системі, то викинеться помилка при встановленні шаблону
    * **wishful** - залежність є бажаною. Шаблон у буде встановлений, але із повідомленням про те що бажано встановити залежність
    * **add** - добавлення залежності в систему. Наприклад модуля, або віджета (наразі тільки для віджетів типу HTML)
Для залежності віджет є кілька додаткових атрибутів: 
    * **description** - опис віджета
    * **widgetType** - ти віджета: module або html
    * **module** - назва модуля для модульного віджета(**widgetType** - module)
    * **method** - назва метода модуля для модульного віджета(**widgetType** - module).

Віджети можуть містити настройки. Дочірній тег **settings** міститиме настройки віджета. Імя дочірніх тегів  в **settings** буде являтись іменем настройки, а вмістиме цих тегів їх значеннями. Настройки в свою чергу можуть мати свої настройки. Для цього їм також потрібно містити дочірнім елементом тег **settings** з вкладеними дочірніми тегами настройок. Якщо потрібно щоб імена настройок були цифрами(для цілочисельного масиву) імя настройки повинно бути таким **number№** (де № - це число).
     
Віджет типу html(**widgetType** - html) має містити дочірній тег **widget_i18n**, який містить переклад віжета. Атрибут **locale** тега **widget_i18n** містить назву локалі мови.
Тег **widget_i18n** містить дочірній тег **data** який містить html код віджета. HTML не повинен містити спецсимволів типу & nbsp; їх потрібно заміняти аналогами в десятковому форматі(наприклад & #0160;).


* Дані компонентів
Тег **components** визначає початкові дані залежностей що будуть встановлені по замовчуванню. Структура тегів даних кожного компонента може відрізнятись. Вона залежить від структури даних самого компонента. Кожен компонент "сам знає" як ці дані пропарсити. Потім ці початкові значення можна буде змінити в налаштуваннях відповідного компонента в модулі Template Manager.
Обовязковий атрибут **handler** повинен містити назву класу компонента.

* Демо дані шаблону
Вмістиме тега **demodata** визначає демо дані які вставлятимуться в базу при установці шаблона. Є можливість розміщати в демо данних назви шаблонів для категорій по рівнях, банери, додаткові поля і меню. 
    * Назви шаблонів категорій розміщуються в тезі **categoriestemplates**. Дочірні теги **level_№** означають номер рівня категорії(де № - номер рівня(1,2,3 ...)), вони містять єдиний атрибут **template_name** - значенням якого є назва шаблону категорії.
    * Дані банерів розміщуються в середині тега **banners**. 
    Дочірні теги:
        * Тег **banner** містить інформацію про один банер.
        Атрибути:
            * **where_show** - де показувати банер. Допустимі значення: default, main, product, shop_category, brand, category, page.
            * **position**  - номер позиції банера.
            * **active** - активність банера(1- активний, 0 - не активний).
            * **group** - група або грпи до якої належить банер(Якщо декільки пишуться через кому: Group1, Group
            Дочірні теги **banner_i18n** - містять інформацію про переклад банера.
            Атрибути: 
                * **name** - імя банера.
                * **description** - опис банера.
                * **url** - ссилка банера.
                * **locale** - локаль мови(ru, en...).
                * **photo** - шлях до фото банера(саме зображення повинно міститися в папці uploads шаблона).
        * Тег **groups** містить групи банерів.
        Дочірні теги:
            * **group** - тег який представляє окрему групу банера і містить його назву в атрибуті **name**.
**При установці банерів з демо даних всі решта банери стають неактивними!**
    * Додаткові поля розміщуюються в тезі **customfields**, в якому дочірні елементи **field** означають конкретне додаткове поле. 
    Атрибути тега **field**:
        * **type** - тип додаткового поля. Значення: text, textarea, file.
        * **name** - назва додаткового поля латиницею без пробілів.
        * **required** - мітка обовязковості поля. Значення: TRUE - обовязкове, FALSE - необовязкове.
        * **active** - мітка активності поля. Значення: TRUE - активне, FALSE - неактивне.
        * **private** - мітка приватності поля. Значення: TRUE - приватне, FALSE - не приватне.
        * **validators** - мыстить валідатори для поля.
        * **classes** - містить назву класу для поля.
        * **entity** - тип поля. Значення: user, order, product, user_order.
            Дочірній тег **field_i18n**  - містять інформацію про переклад додаткового поля.
            Атрибути: 
            * **label** - назва додатково поля.
            * **description** - опис додаткового поля.
            * **locale** - локаль мови(ru, en...).
    * Меню розміщується в тезі **menus**, дочірні теги **menu** містять дані конкретного меню.
    Атрибути тега **menu**:
        * **name** - назва меню латиницею без пробілів.
        * **main_title** - заголовок меню.
        * **tpl_folder** - каталог шаблону для меню.
        * **expand_level** - номер рівня меню до якого воно буде розкриватися.
        * **description** - опис меню.
    Дочірні теги **item** - містять інформацію про пункт меню. Якщо пункт містить підпункт він повинен містити дочірній тег **item**.
    Атрибути тега **item**:
        * **image** - шлях до зображення пункта меню. Сам файл зображення повинен міститися в папці uploads шаблана.
        * **title** - назва пункта меню.
        * **description** - опис пункта меню.
        * **url** - ссилка на яку вказуэ пункт меню.
    Дочірні теги **menu_i18n** - містять переклад пункта меню.
    Атрибути тега **menu_i18n**:
        * **title** - назва пункта меню.
        * **locale** - назва локалы мови(ru, en ...).
    
                


## Компоненти шаблону
Інколи шаблон може містити окремий функціонал який має більш складну логіку ніж та що є tpl-файлах (виведення списків через foreach, умови...). Цей функціонал було вирішено не прив’язувати до CMS, так як він може бути специфічним для кожного шаблону, а забезпечити можливість його структурування та організації. Компоненти шаблону це свого роду модулі для шаблону. Будь-який більш складнінший функціонал, що містить дані в БД може бути організований у вигляді компоненту. 

Компоненти можуть бути розміщені в самому модулі template_manager/components, або в шаблоні назва_шаблону/components. Важливо: якщо у шаблоні буде міститись компонент із такою самою назвою що і в системі, то перевагу буде мати компонент шаблону, тобто компоненти шаблону мають більший пріоритет.

### Структура компонентів
Кожен компонент повинен містити головний клас що розширює TComponent. Наслідуваний клас має перезавантажити наступні методи:
* setParamsXml($nodes) - парсить початкові налаштування компоненту.
* renderAdmin() - повертає інтерфейс адмін-частини для налаштування даного компоненту
* getLabel() - назва компоненту для відображення в адмін-панелі (по замовчуванню повертає назву класу)

Далі організація коду залежить від самого розробника. Для кращого розуміння влаштування компонентів можна подивитись на існуючі компоненти, та "скелет" /template\_manager/component\_pattern.

Щоб скоротити код при звертанні до методів компонента, для більшої читабельності tpl-файлів, можна скористатись класом TComponentShortcut, створити хелпер (див. нижче) на часто вживаний метод компоненту. Для використання TComponentShortcut, щоб наприклад дістатись що методу getColorScheme() компонента TColorScheme: $tcs->TColorScheme->getColorScheme(). Назву TColorScheme можна скоротити вказавши тільки великі літери: $tsc->TCS->getColorScheme().  

#### "Хелпери"
У шаблоні може бути папка helpers, яка є схожою за призначенням що механізм хелперів Codeigniter. В ній можна розмістити php файли із функціями, які будуть автоматично включені. 





# Зміни в шаблонах для нового template_manager

Новий менеджер шаблонів не має конфліктів (в теорії, ще не було нормального тестування) із старими шаблонами та 
модулем new_level. 

## Нові файли та папки
* файл **params.xml** - файл із інформацією про шаблон та його конфігурацією.
* папка **components** - все те що було раніше в модулі new_level тепер поділено на окремі компоненти (повинні бути описані в файлі *params.xml*, інакше модуль їх "не буде бачити")
* папка **screenshots** - містить скріншоти шаблону, що будуть відображатись в адмінці (також повинні бути описані в файлі *params.xml*, інакше в адмінці їх не буде)
* папка **license_agreement** (необов’язково) - з неї підтягуються ліцензії. Ліцензія на російській мові, наприклад, повинна бути в файлі *ru.txt*


## Зміни по компонентах

### TColorScheme
Цей компонент прозначений для вибору кольорової схеми шаблона.
Метод компонента **getColorSheme()** повертає назву кольорової схеми.

### TMenuColumn
Компонент вибору колонок для меню категорій. Кількість колонок обмежена до десяти.
Метод компонента **getCategoryColumns($category_id)** приймає ідентифікатор категорії і повертає номер колонки до якої вона підвязана(1,2,3... або 0 - по замовчуванню).
Метод компонента **getOpenLevels()** повертає кількість рівнів категорій яким можна вказати номер колонки і які будуть відкриватися при наведенні на категорію в меню. Значення: all - всі будуть відкритими, 2 - буде відкритим тільки другий рівень.

### TOpi
Компонент призначений для відображення шаблону одного продукта.
Метод компонента **getOPI($model, $data, $tpl)**  - відображає шаблон продукта. 
* Параметри: 
    * **$model** - модель продукта або набора продуктів.
    * **$data** - масив змінних які будуть доступні в шаблоні.
    * **$tpl** - назва файла шаблону для продукта.

### TProperties
Компонент для смарт фільра шаблона. Призначений для присвоєння властивостям товарів класу, взалежності від якого змінюватиметься її вигляд на фільтрі.
Метод **getPropertyTypes($property_id)** - приймаючи ідентифікатр властивості повертає назву класу.

Всі ці методи компонент представнені хелперними одноіменними функціями доступними в шаблоні.

# Повні демо дані шаблону
Повні демо дані шаблону дозволяють розмістити всі необхідні зміни для бази і для папки uploads.
Для йього потрібно в папці шаблона створити каталог з назвою **demodata** який міститиме всі необхідні демо дані.
* Вмістиме каталогу **demodata**:
    * архів **uploads.zip** - повинен містити файли для папки uploads сайту. Може містити каталог з назвою **uploads** і з вмістимим або всі необхідні файли для **uploads** в корені архіву.
    * файл **database.sql** - містить запити до бази даних.
Коли повні демодані встановляться колишня папка uploads перейменується на uploads_backup.
База данних сайта копіюється в папку ./application/backups/backup_template_manager.sql.