imagecms/ImageCMS

#Template Manager 

##Общая информация по структуре шаблона 
Кроме дерева js-, css- и tpl-файлов, шаблон должен содержать такие файлы и каталоги:
* params.xml - содержит основную информацию о шаблоне, а также данные, которые необходимы для инсталляции шаблона; 
* components (необязательно) - может содержать компоненты шаблона.

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

Каждая отдельная зависимость определяется тегом dependency, который имеет такие атрибуты:
* **entityName** - обработчик зависимости. Определяет класс, который обрабатывает данные каждого вида зависимости. Доступные значения на данный момент: module и widget;
* **name** - название модуля или виджета;
* **type** - тип зависимости. Всего есть три типа зависимостей: 
    * **required** - зависимость требуется, и если не будет установлена в системе, то появится ошибка при установке шаблона;
    * **wishful** - зависимость является желательной. Шаблон будет установлен, но с сообщением о том, что желательно установить зависимость (например модуль или виджет);
    * **add** - добавление зависимости в систему. Например, модуля или виджета.
Для зависимости виджета есть несколько дополнительных атрибутов: 
    * **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, Group2).
            Дочерние теги **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.