Разработка:modlibs/templater

2013-04-05T13:59:32Z

K-krsnv: /* Дополнительные методы Sigma */

{{Infobox_Plugin
| name = templater
| type = modlibs
}}

== Принципы работы ==
Плагин templater обеспечивает все действия по экспорту данных и создание любых электронных документов (отчетов, приказов, графиков и т. п.)
=== Общие сведения ===
Все документы формируются следующим образом:
* на основе требуемого документа создается файл шаблона документа;
* собираются данные для вставки в шаблон
* формируется экспортируемый документ - производится вставка данных в шаблон;
* сформированный документ посылается клиенту по http-протоколу.
Шаблон документа формируется из документа по специальным правилам, а затем размещается в оговоренном месте плагина, из которого производится экспорт. Затем по аналогичным правилам производится вставка данных. Сбор и подготовка данных для экспорта производятся тем же плагином. В настоящее время формирование шаблона производится вручную. Описываемый модуль получает путь к каталогу документа, данные для вставки и формат документа. На основе этих данных он формирует документ и посылает его клиенту.

=== Формат исходных данных ===
Данные, предназначенные для экспорта должны соответствовать следующим стандартам:
* Исходные данные всегда представлены в виде объекта класса stdClass (стандартный объект PHP).
* Поля объекта могут содержать строки, числа и массивы объектов (массивы строк или чисел не допускаются). Данные других типов не обрабатываются.
* Строки и числа подставляются в шаблон документа "как есть".
* Данные для экспорта представляются в виде структурированного объекта (класс object()), в котором одиночные поля представляются скалярами, записи - объектами, а таблицы - массивами объектов.
Желательно для создания объекта данных для экспорта создавать отдельный класс, который решает эту задачу.

=== Пример исходных данных ===
В этом примере мы построим объект для экспорта оценок учеников двух классов. У каждого класса есть название, предмет, и дата, за которую выставлялись оценки. В каждом классе есть несколько учеников, которые эти оценки получили. Таким образом, если мы хотим получить такую таблицу:
{|border="1"
|№
|ФИО ученика
|оценка
|-
|colspan="3" |Зб класс, Математика, 21.01.09
|-
|1
|Замеладский Алексей
|5
|-
|2
|Гусева Татьяна
|4
|-
|colspan="3" |5б класс, Русский язык, 27.01.09
|-
|1
|Коньков Сергей
|5
|-
|2
|Захаров Александр
|3
|}

Данные для экспорта будут выглядеть следующим образом:
<code php>
stdClass Object
(
[classes] => Array

[0] => stdClass Object // данные о первом классе
[name] => 3 "б"
[date] => 21.01.09
[subject] => Математика
[students] => Array

[0] => stdClass Object // здесь хранятся данные первого ученика из 3-го "Б"
[number] => 1
[fio] => Замеладский Алексей
[grade] => 5
[1] => stdClass Object
[number] => 2
[fio] => Гусева Татьяна
[grade] => 4

[1] => stdClass Object // данные о втором классе
[name] => 5 "б"
[date] => 21.01.09
[subject] => Русский язык
[students] => Array

[0] => stdClass Object // здесь хранятся данные первого ученика из 5-го "Б"
[number] => 1
[fio] => Коньков Сергей
[grade] => 5
[1] => stdClass Object
[number] => 2
[fio] => Захаров Александр
[grade] => 3
)
</code php>
=== Реализация экспорта ===
==== Подготовка к экспорту ====
Для начала надо убедиться, что на месте вспомогательные средства. Т.е. установлен описываемый плагин '''templater''', и плагин обеспечивающий превращения шаблона документа в документ - '''pear'''. Поэтому убедитесь, что у вас
* установлен плагин '''pear'''. Удостоверьтесь, что на странице списка установленных плагинов, напротив модуля pear написано "Удалить, а не " "Установить".
* в нем есть библиотека '''HTML_Template_Sigma'''. Проверьте наличие файла '''.../modlibs/pear/libs/HTML_Template_Sigma/Sigma.php'''.
* установлен описываемый модуль - '''templater'''. Проверьте так же как и '''pear'''.
Теперь надо подготовить плагин. В нем надо создать структуру папок. Для реализации экспорта надо создать в корневой папке плагина директорию '''templater'''. В ней нужно создать каталоги для каждого документа, который вы собираетесь экспортировать. В каждой из них нужно создать папки, названия которых - это типы файлов, в которые вы собираетесь экспортировать каждый документ. Внутри этих папок должны лежать файлы шаблонов для экспорта.
Например, у нас есть плагин '''reports''', типа '''im'''. Из него планируется экспортировать отчеты: список оценок - '''grades_list''', список учеников - '''students_list''', список учителей - '''teachers_list'''. Список оценок будет экспортироваться в форматы odf, csv, html. Список учителей в форматы odf и html. Список студентов в csv и html. Тогда надо создать такую структуру папок:
.../im/reports/templater/grades_list/odf
.../im/reports/templater/grades_list/csv
.../im/reports/templater/grades_list/html
.../im/reports/templater/students_list/csv
.../im/reports/templater/students_list/html
.../im/reports/templater/teachers_list/odf
.../im/reports/templater/teachers_list/html

Внутри этих папок следует разместить шаблоны документов для экспорта.

Правила подготовки шаблона описаны в разделе [[Разработка:modlibs/templater#Подготовка шаблона документа|Подготовка шаблона документа]].

Теперь, когда шаблон есть, можно переходить к следующему этапу - сбору данных для экспорта. Объект экспорта должен соответствовать структуре объекта, описанной в разделах [[Разработка:modlibs/templater#Формат исходных данных|Формат исходных данных]] и [[Разработка:modlibs/templater#Пример исходных данных|Пример исходных данных]].

Теперь все необходимые приготовления выполнены и можно переходить непосредственно к экспорту.

==== Экспорт документа ====
Собственно экспорт осуществляется в два этапа. Создание объекта экспорта и инициализация экспорта. Поясним оба этапа на примере. Предположим, мы хотим экспортировать ведомость оценок '''grades_list''' из плагина '''reports''' в формат '''odf'''. Тогда

* Получаем нужный объект:
$exporter = $DOF->modlib('templater')->template('im', 'reports', $dataforexport, 'grades_list');
Здесь:

''im'' - тип плагина,

''reports'' - имя плагина,

''grades_list'' - директория, в которой лежит шаблон документа, который будет экспортирован.

''$exporter'' - объект, который будет производить все необходимые операции.

''$dataforexport'' - собранные на предыдущем этапе данные.

* Получив объект, инициализируем отправку файла:
$exporter->send_file('odf');
die;
Функция die здесь использована для того, чтобы больше ничего в файл экспорта не попало.

Обратите внимание, что объект $exporter уже хранит в себе все необходимые данные. Если вы хотите еще раз экспортировать данные, но уже в другой формат - не нужно заново создавать объект, достаточно обратиться к нему еще раз, например:
$exporter = $DOF->modlib('templater')->template('im', 'reports', $dataforexport, 'grades_list');
switch ($type)
{
case 'odf': $exporter->send_file('odf');break;
case 'csv': $exporter->send_file('csv');break;
}
die;
По умолчанию имя посылаемого файла формируется из собственно имени файла (которое по умолчанию равно '''export'''), и расширения, в качестве которого используется тип файла, указанный при инициализации экспорта. Но можно задать и другое имя. Для этого надо использовать второй необязательный параметр функции '''send_file''':
$options = new object;
$options->filename = 'new_export_file_name';
$exporter->send_file('odf', $options);
Имя файла надо указывать без расширения.

=== Подготовка шаблона документа ===
Если вам нужно создать новый документ, то нужно создать и новый шаблон документа.
Файл шаблона должен быть размечен тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma PEAR::HTMLTemlateSigma].
В нем оформляются места для вставки данных - поля и блоки.
*Отдельное поле помечается фигурными скобками '''{}'''.
*Внутри скобок указывается имя поля. Например, '''{lastname}''' - поле, вместо которого должна подставляться фамилия.
*Если есть блок полей, то начало блока помечается тегом '''&lsaquo;!-- BEGIN block_name --&rsaquo;'''.
*Окончание блока помечается тегом '''&lsaquo;!-- END block_name --&rsaquo;'''. Здесь block_name - имя блока, все остальное - обязательная служебная конструкция. Между этими тегами нужно размещать поля блока и другие блоки.
Например надо таблицу ведомости оценок (см. [[Разработка:modlibs/templater#Пример исходных данных|Пример исходных данных]])

{|border="1"
|№
|ФИО ученика
|оценка
|-
|colspan="3" |Зб класс, Математика, 21.01.09
|-
|1
|Замеладский Алексей
|5
|-
|2
|Гусева Татьяна
|4
|-
|colspan="3" |5б класс, Русский язык, 27.01.09
|-
|1
|Коньков Сергей
|5
|-
|2
|Захаров Александр
|3
|}

получить в виде html-файла. Тогда в шаблоне документа надо вставить поля и блоки примерно так:
<html>
....
&lsaquo;table&rsaquo;
&lsaquo;tr&rsaquo;
&lsaquo;td&rsaquo;№&lsaquo;/td&rsaquo;
&lsaquo;td&rsaquo;ФИО ученика&lsaquo;/td&rsaquo;
&lsaquo;td&rsaquo;Оценка&lsaquo;/td&rsaquo;
&lsaquo;/tr&rsaquo;
&lsaquo;!-- BEGIN classes --&rsaquo;
&lsaquo;tr&rsaquo;
&lsaquo;td&rsaquo;{name} класс, {subject}, {date}&lsaquo;/td&rsaquo;
&lsaquo;/tr&rsaquo;
&lsaquo;!-- BEGIN students --&rsaquo;
&lsaquo;tr&rsaquo;
&lsaquo;td&rsaquo;{number}&lsaquo;/td&rsaquo;
&lsaquo;td&rsaquo;{fio}&lsaquo;/td&rsaquo;
&lsaquo;td&rsaquo;&lsaquo;grade>&lsaquo;/td>
&lsaquo;/tr&rsaquo;
&lsaquo;!-- END students --&rsaquo;
&lsaquo;!-- END classes --&rsaquo;
&lsaquo;/table&rsaquo;
....
&lsaquo;/html&rsaquo;

Каждый файл шаблона должен иметь имя template.тип_файла экспорта. К примеру '''template.html'''. Из этого правила есть несколько исключений. В частности, odf-формат имеет сложную структуру, поэтому и его шаблон должен быть устроен соответственно. Структура папок шаблона odf-документа описана [[Разработка:modlibs/templater#ODF|тут]]. В ряде случаев шаблон документа вообще не нужен. Так например, формат dbg - это тестовый вариант вывода данных. В этом случае неформатированные данные экспорта выводятся на экран. Другой случай - экспорт в формат '''csv'''. Файл в этом формате представляет собой набор строк, в которых данные разделены запятыми. Для него шаблон также не нужен.

=== Альтернативный способ формирования документа ===
Можно изменить способ формирования документа в существующий формат. Для этого надо, в своем плагине, в папке с названием типа файла экспорта создать файл '''init.php'''. Т.е. если мы хотим изменить формирование списка оценок в файл '''html''', то должна получиться такая структура папок
.../templater/reports/grades_list/html/init.php
.../templater/reports/grades_list/html/template.html
Внутри этого файла, должен быть определен класс, который и создает документ из шаблона. Теперь, во время экспорта, формирование документа будет производить не встроенный в '''templater''' класс, а альтернативный.

Если возникла необходимость экспортировать данные в файл, тип которого не поддерживает плагин '''templater''', можно самостоятельно реализовать и это. Для этого надо добавить папку ''тип_файла_экспорта'' в плагин '''templater''':
.../modlib/templater/formats/тип_файла_экспорта
А внутрь нее положить файл '''init.php''', с аналогичным классом. Например, надо реализовать экспорт в excell. Тогда в плагине '''templater''' должен появиться файл '''init.php''' по такому адресу:
.../modlib/templater/formats/xls/init.php

Общий принцип формирования имен классов:
* Для создания нового формата ''dof_modlib_templater_format''_'''тип-файла-экспорта'''.
* Для изменения логики работы существующего формата ''dof''_'''типплагина_имяплагина'''_''templater''_'''название-папки-документа'''_'''тип-файла-экспорта'''.
Таким образом, для выше приведенных примеров имена классов будут такими:
* Новый класс экспорта в excell: '''dof_moblib_templater_format_xls'''.
* Альтернативный класс экспорта в '''html''': '''dof_im_reports_templater_grades_list_html'''.

В плагине '''templater''' существует абстрактный базовый класс '''dof_modlib_templater_format'''. Каждый класс, который вы создаете, должен наследоваться от него.
При создании нового формата обязательно нужно реализовать следующие методы:
* '''get_file'''($options) - получить файл в виде строки. Главная функция, производящая все преобразования над данными.
* '''get_filename'''($options) - получить имя файла вместе с расширением одной строкой.
* '''get_mimetype'''($options) - получить MIME-тип для подстановки его в HTTP-заголовок.

Дальнейшее использование созданного вами формата аналогично использованию готового формата. Более подробную информацию о методах и свойствах класса ''dof_modlib_templater_format'' можно найти в разделе [[Разработка:modlibs/templater#dof_modlib_templater_format|API]].

=== Альтернативный способ экспорта ===
Если работа стандартного контейнера экспорта [[Разработка:modlibs/templater#dof_modlib_templater_package|dof_modlib_templater_package]] вас не устраивает, то вы можете создать свой. Для этого надо создать свой класс и реализовать в нем необходимые методы. Этот класс надо поместить в файл '''init.php''', а файл положить в папку того документа, для экспорта которого, вы этот контейнер создавали. Теперь при создании объекта экспорта будет создан не стандартный объект, а тот, который вы написали в файле. К примеру, вы хотите производить экспорт оценок через собственный контейнер. Тогда должна получиться такая структура папок:
.../im/reports/templater/grades_list/odf/
.../im/reports/templater/grades_list/csv/
.../im/reports/templater/grades_list/html/
.../im/reports/templater/grades_list/init.php
Класс контейнера должен именоваться так: dof_тип-плагина_имя-плагина_templater_название-папки-документа. В нашем случае это '''dof_im_reports_templater_grades_list'''.

== API плагина ==
В этом разделе описаны все функции интерфейса плагина templater.
=== Внешний ===
====dof_modlib_templater:====
*'''template'''($plugintype, $pluginname, $data, $templatename) — возвращает класс экспорта документа из указанного плагина. Возвращает объект класса dof_modlib_templater_package или dof_тип-плагина_имя-плагина_templater_имя-документа
** $plugintype - тип плагина
** $pluginname - имя плагина
** $data - данные для экспорта, структурированные как указано [[Разработка:modlibs/templater#Формат исходных данных|выше]].
** $templatename - имя документа; здесь указывается имя папки, в которой лежат шаблоны для формирования документа в разных форматах. В рассмотренных выше примерах это '''grages_list''', '''teachers_list''' или '''students_list'''.

*'''template_path'''($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - возвращает путь внутри плагина.
** $plugintype - тип плагина
** $pluginname - имя плагина
** $templatename - имя документа (см. предыдущую функцию)
** $adds - дополнительный путь внутри плагина
** $fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Ее возможные значения:
*** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем во внутреннем
*** true - искать только во внешнем планине
*** false - искать только в modlib/templater
Таблица, описывающая работу этой функции:
{| border=1
|'''№'''
|'''$templatename'''
|'''$fromplugin'''
|'''Результат'''
|-
|1
|null
|null
|Путь внутри modlib/templater
|-
|2
|null
|true
|false
|-
|3
|null
|fasle
|Путь внутри modlib/templater
|-
|4
|Существующее
|null
|Путь из внешнего плагина
|-
|5
|Существующее
|true
|Путь из внешнего плагина
|-
|6
|Существующее
|false
|Путь внутри modlib/templater
|-
|7
|Ошибочное
|null
|false
|-
|8
|Ошибочное
|true
|false
|-
|9
|Ошибочное
|false
|false
|-
|}

====dof_modlib_templater_package====
*'''get_file'''($type, $options) - получить отформатированные данные, пригодные для обработки функцией file_put_contents().
**$type — в какой формат экспортировать. Должно совпадать с названием папок в ...'''/modlibs/templater/formats/''' - '''dbg''' или '''csv''', или '''odf''' и др. А также с именем папки во внешнем плагине, в котором лежит шаблон экспорта в файлы такого типа.
**$options — дополнительные параметры.
*'''send_file'''($type, $options) — инициализировать передачу файла клиенту через браузер.
**$type — в какой формат экспортировать,
**$options — дополнительные параметры.
*'''get_formats'''() - список доступных для указанного документа типов файлов экспорта.
*'''template_path'''($adds=null, $fromplugin) - путь к шаблону (работает через класс dof_modlib_templater)
**$adds - дополнительный путь, присоединяемый к возвращаемому функцией template_path в классе '''dof_modlib_templater''':
**$fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Возможные значения:
*** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем в
*** true - искать только во внешнем планине
*** false - искать только в modlib/templater

=== Внутренний ===
Этот раздел понадобится вам в случае если вам будет нужно написать собственный формат или тип документа.

====dof_modlib_templater_package:====
*'''__construct'''($dof, $plugintype, $pluginname, $templatename)
**$dof - стандартный объект $DOF
**$plugintype - тип плагина (im, storage, modlib и т. д.)
**$pluginname - имя плагина
**$templatename - имя шаблона форматирования, для которого вызывается обьект '''dof_modlib_templater_package''':
*'''set_data'''($obj) — загрузить необработанные данные в объект.
** $obj - объект с необработанными данными
*'''get_data'''() - внутренний метод. Получить необработанный объект с данными.

====dof_modlib_templater_format====
*'''__construct'''($dof, $plugintype, $pluginname, $templatename) - конструктор класса. Вызывается автоматически объектом dof_modlib_templater_package.
** $dof - объект [[Разработка:DOF|$DOF]]
** $plugintype - Тип плагина
** $pluginname - имя плагина
** $templatename - имя шаблона для экспорта
*'''get_file'''($options)
** $options - произвольные дополнительные параметры
*'''set_data'''($data)
** $data - объект с заранее подготовленными данными
*'''get_filename'''($options)
** $options - произвольные дополнительные параметры
*'''get_mimetype'''($options)
** $options - произвольные дополнительные параметры
*'''template_path'''($adds=null, $fromplugin) - путь к папке данного формата (работает через класс package)
** $adds - дополнительный путь, присоединяемый к возвращаемому функцией template_path в классе '''dof_modlib_templater_package''':
** $fromplugin - какой путь нужно вернуть: из внутреннего плагина или из modlib/templater. Возможные значения:
*** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем в
*** true - искать только во внешнем планине
*** false - искать только в modlib/templater

=== Дополнительные методы Sigma ===
*'''date'''($fofmat,$value = null) - Форматирует системную дату/время. Равносилен стандартной функции РНР [http://ru2.php.net/manual/ru/function.strftime.php strftime].
*'''mb_substr'''($value,$start = 0,$length = 1) - Получает часть строки. Равносилен стандартной функции РНР [http://ru2.php.net/manual/ru/function.mb-substr.php mb_substr]. Используемая кодировка 'utf-8'.
*'''get_value'''($id,$field,$code) - Возвращает значение поля в записи с указанным id.
** $id - id записи в таблице
** $field - поле в таблице
** $code - имя плагина справочника
*'''get_string'''($identifier, $pluginname = NULL, $a = NULL, $plugintype = 'im') - Возвращает строку перевода из файла локализации. Равносилен стандартному методу деканата '''get_string'''.

== Форматы экспорта ==
В этом разделе будут рассмотрены все поддерживаемые плагином templater форматы экспорта.

=== ODF ===
Open Document Format.
Этот формат используется документами [http://openoffice.ru OpenOffice]. В этом формате можно создавать как обычные текстовые документы (odt), так и электронные таблицы (ods). Для подготовки документа нужно разметить его тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma Sigma]. Создание текстового документа и электронной таблицы происходит одинаково - разница только в расширении файла: odt - для текстового документа, и ods для электронной таблицы.

Экспорт в формат odf реализуется стандартным образом. Отдельных слов, в силу особенностей структуры документа, заслуживает только подготовка шаблона.
Все файлы формата odf представляют собой zip-архивы определенной структуры. У '''odt''' или '''ods''' документов собственно текст находится в файле '''content.xml''', который лежит в корне архива. Для того, чтобы правильно разметить документ - воспользуйтесь разделом [[Разработка:modlibs/templater#Подготовка шаблона документа|Подготовка шаблона документа]].

В плагине, из которого планируется реализовать экспорт в odf, папке odf, должна лежать папка с именем '''content''', в которой должны лежать каталоги и файлы распакованные из этого архива. Собственно текст документа хранится в файле '''content.xml'''. Поэтому именно этот файл должен быть размечен как шаблон документа. Остальные файлы и папки можно оставить без изменения. В итоге мы должны увидеть что-то подобное:
.../im/reports/templater/grades_list/odf/content/Configurations2/
.../im/reports/templater/grades_list/odf/content/META-INF/
.../im/reports/templater/grades_list/odf/content/Thumbnails/
.../im/reports/templater/grades_list/odf/content/content.xml
.../im/reports/templater/grades_list/odf/content/meta.xml
.../im/reports/templater/grades_list/odf/content/mimetype
.../im/reports/templater/grades_list/odf/content/settings.xml
Ниже представлена схема структуры папок, с пояснением, для чего какие файлы и директории нужны.
[[Изображение:folders5.jpeg]]

Пример реализации экспорта в '''odf''':
$template = $DOF->modlib('templater')->template('im', 'reports', $data, 'grades_list');
$template->send_file('odf');
die;

=== CSV ===
Comma Separated Value - значения разделенные запятыми. Файлы этого формата - это набор строк, данные в которых отделяются друг от друга специальными текстовыми разделителями. Обычно запятой, точкой с запятой или символом таблуляции.

Экспорт в этот формат имеет свои особенности.

По умолчанию экспорт документов в этот формат происходит следующим образом:
* из входных данных берется самый первый массив объектов;
* названия свойств (названия, а не значения!) первого объекта становятся строкой заголовков, остальные поля - строками данных;
* при формировании строк данных в них попадают только данные, которые хранятся в свойствах объекта, одноименных со свойствами объекта, из которого сформирована строка заголовка. Лишние данные отбрасываются, недостающие заменяются пробелами;
* все остальные элементы входных данных игнорируются.

Поскольку csv-файлы имеют стандартную и неизменную структуру, шаблоны для их построения не требуются. Из объекта данных формируется последовательность строк, после чего обработанные данные отсылаются клиенту:
$template = $DOF->modlib('templater')->template('im', 'reports', $data, 'teachers_list');
$template->send_file('csv');
die;

По умолчанию строка заголовка вставляется в конечный файл. Но можно это отключить:
$template = $DOF->modlib('templater')->template('im', 'reports', $data, 'teachers_list');
$options = new object;
$options->title = false;
$template->send_file('csv', $options);
die;

=== HTML ===
Экспорт в этот формат пригодиться в случае, если вам нужно сохранить данные из какого-либо документа как web-страницу.
Как обычно, надо создать файл шаблона, разметить его, положить в установленное место и назвать '''template.html'''. О том, как правильно его разметить можно прочитать в разделе [[Разработка:modlibs/templater#Подготовка шаблона документа|Подготовка шаблона документа]].
Пример кода:
$template = $DOF->modlib('templater')->template('im', 'reports', $data, 'grades_list');
$template->send_file('html');
=== DBG ===
Это тестовый вариант экспорта. На экран выводятся входные данные в том виде как они переданы. Это может помочь разобраться с их структурой и проверить работоспособность классов. Для этого варианта экспорта не требуется никакого шаблона. Все остальное - как обычно.
Пример кода:
$template = $DOF->modlib('templater')->template('im', 'reports', $data, 'grades_list');
$template->send_file('dbg');

== Ссылки ==
*[http://pear.php.net/package/HTML_Template_Sigma Шаблонизатор HTMLTemplateSigma]
*[http://pear.php.net/manual/en/package.html.html-template-sigma.intro-syntax.php Справка по синтаксису шаблонизатора Sigma]

DOF - Вклад участника [ru]

Разработка:modlibs/templater