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

Плагин
Название	templater
Тип	modlibs

Принципы работы

Плагин templater обеспечивает все действия по экспорту данных и создание любых электронных документов (отчетов, приказов, графиков и т. п.)

Общие сведения

Все документы формируются следующим образом:

• на основе требуемого документа создается файл шаблона документа;
• собираются данные для вставки в шаблон
• формируется экспортируемый документ - производится вставка данных в шаблон;
• сформированный документ посылается клиенту по http-протоколу.

Шаблон документа формируется из документа по специальным правилам, а затем размещается в оговоренном месте плагина, из которого производится экспорт. Затем по аналогичным правилам производится вставка данных. Сбор и подготовка данных для экспорта производятся тем же плагином. В настоящее время формирование шаблона производится вручную. Описываемый модуль получает путь к каталогу документа, данные для вставки и формат документа. На основе этих данных он формирует документ и посылает его клиенту.

Формат исходных данных

Данные, предназначенные для экспорта должны соответствовать следующим стандартам:

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

Желательно для создания объекта данных для экспорта создавать отдельный класс, который решает эту задачу.

Пример исходных данных

В этом примере мы построим объект для экспорта оценок учеников двух классов. У каждого класса есть название, предмет, и дата, за которую выставлялись оценки. В каждом классе есть несколько учеников, которые эти оценки получили. Таким образом, если мы хотим получить такую таблицу:

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

Данные для экспорта будут выглядеть следующим образом:

   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
   )

Реализация экспорта

Подготовка к экспорту

Для начала надо убедиться, что на месте вспомогательные средства. Т.е. установлен описываемый плагин 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

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

Правила подготовки шаблона описаны в разделе Подготовка шаблона документа.

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

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

Экспорт документа

Собственно экспорт осуществляется в два этапа. Создание объекта экспорта и инициализация экспорта. Поясним оба этапа на примере. Предположим, мы хотим экспортировать ведомость оценок 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);

Имя файла надо указывать без расширения.

Подготовка шаблона документа

Если вам нужно создать новый документ, то нужно создать и новый шаблон документа. Файл шаблона должен быть размечен тегами шаблонизатора PEAR::HTMLTemlateSigma. В нем оформляются места для вставки данных - поля и блоки.

• Отдельное поле помечается фигурными скобками {}.
• Внутри скобок указывается имя поля. Например, {lastname} - поле, вместо которого должна подставляться фамилия.
• Если есть блок полей, то начало блока помечается тегом ‹!-- BEGIN block_name --›.
• Окончание блока помечается тегом ‹!-- END block_name --›. Здесь block_name - имя блока, все остальное - обязательная служебная конструкция. Между этими тегами нужно размещать поля блока и другие блоки.

Например надо таблицу ведомости оценок (см. Пример исходных данных)

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

получить в виде html-файла. Тогда в шаблоне документа надо вставить поля и блоки примерно так:

   <html>
   ....
   ‹table›
      ‹tr›
         ‹td›№‹/td›
         ‹td›ФИО ученика‹/td›
         ‹td›Оценка‹/td›
      ‹/tr›
      ‹!-- BEGIN classes --›
      ‹tr›
         ‹td›{name} класс, {subject}, {date}‹/td›
      ‹/tr›
      ‹!-- BEGIN students --›
      ‹tr›
         ‹td›{number}‹/td›
         ‹td›{fio}‹/td›
         ‹td›‹grade>‹/td>
      ‹/tr›
      ‹!-- END students --›
      ‹!-- END classes --›
   ‹/table›
   ....
   ‹/html›

Каждый файл шаблона должен иметь имя template.тип_файла экспорта. К примеру template.html. Из этого правила есть несколько исключений. В частности, odf-формат имеет сложную структуру, поэтому и его шаблон должен быть устроен соответственно. Структура папок шаблона 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 можно найти в разделе API.

Альтернативный способ экспорта

Если работа стандартного контейнера экспорта 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 - данные для экспорта, структурированные как указано выше.
  • $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

Таблица, описывающая работу этой функции:

№	$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
  • $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) - Форматирует системную дату/время. Равносилен стандартной функции РНР strftime.
• mb_substr($value,$start = 0,$length = 1) - Получает часть строки. Равносилен стандартной функции РНР 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. Этот формат используется документами OpenOffice. В этом формате можно создавать как обычные текстовые документы (odt), так и электронные таблицы (ods). Для подготовки документа нужно разметить его тегами шаблонизатора Sigma. Создание текстового документа и электронной таблицы происходит одинаково - разница только в расширении файла: odt - для текстового документа, и ods для электронной таблицы.

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

В плагине, из которого планируется реализовать экспорт в 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

Ниже представлена схема структуры папок, с пояснением, для чего какие файлы и директории нужны.

Пример реализации экспорта в 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. О том, как правильно его разметить можно прочитать в разделе Подготовка шаблона документа. Пример кода:

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

Ссылки

• Шаблонизатор HTMLTemplateSigma
• Справка по синтаксису шаблонизатора Sigma