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

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

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

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

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

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

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

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

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

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

• Исходные данные всегда представлены в виде объекта класса stdClass (стандартный объект 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
   )

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

Тип документа

Каждый экспортируемый документ должен относиться к какому-либо типу. Тип документа зависти от его назначения (оценки за четверть, приказ о переводе в следующий класс, и т. д.). Внутри типа документа всегда содержатся экспортируемые данные. Каждый документ определенного типа можно экспортировать в несколько разных форматов.

Форматы экспорта

Каждый формат экспорта по-своему обрабатывает данные, указанные в типе документа. Тем не менее, какой бы формат экспорта не был выбран (например csv, odf, pdf), данные всегда используются одни и те же.

Использование

В этом разделе будет описано, как использовать плагин templater, будут приведены примеры кода.

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

Для начала надо убедиться, что на месте вспомогательные средства. Т.е. установлен описываемый плагин templater, и плагин обеспечивающий превращения шаблона документа в документ - pear. Поэтому убедитесь, что у вас

• установлен плагин pear. Убедитесь, что на странице списка установленных плагинов, напротив модуля pear написано "Удалить, а не " "Установить".
• в нем есть библиотека HTML_Template_Sigma. Проверьте наличие файла .../modlibs/pear/libs/HTML_Template_Sigma/Sigma.php.
• установлен описываемый модуль - templater. Проверьте так же как и pear.

Использование готового документа

Самый простой способ экспортировать данные. Использование этого способа предполагает, что кто-то уже создал шаблон документа для экспорта, определил его тип и разметил его соответствующим образом. Вам остается сделать всего 2 действия:

• собрать данные
• указать какой документ в какой формат вы желаете экспортировать.

Сбор данных

Данные извлекаются из базы данных, или из форм, а затем преобразуются в нужный для экспорта формат. О том, какой формат должны иметь данные для экспорта описано в разделе Формат исходных данных. Рекомендуется выделять для сбора и упаковки данных отдельный класс, особенно если процесс сбора данных достаточно сложен.

Указание формата и типа документа

После того, как были собраны все необходимые данные можно приступать непосредственно к процессу экспорта. Нужно сначала получить объект для для экспорта, затем передать ему данные, и получить готовый файл.

Пример

• Обращаемся к плагину templater чтобы получить нужный объект.

   $export = $DOF->modlib('templater')->template('im', 'genedu', $data, 'gradeslist');

Здесь:

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

genedu - имя плагина,

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

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

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

• Получив объект, обращаемся к нему выбираем формат, в который мы собираемся произвести экспорт.

   $file = $export->get_file('odf');

В переменной $file будет содержаться файл нужного формата. Если вам нужно отправить файл немедленно вместе с заголовками, то воспользуйтесь методом send_file. Обратите внимание, что объект $export уже хранит в себе все необходимые данные. Если вы хотите еще раз экспортировать данные, но уже в другой формат - не нужно заново создавать объект, достаточно обратиться к нему еще раз.

Создание типа документа

В случае, когда нужно создать новый шаблон для документа требуются дополнительные операции. При работе над экспортом этот вариант будет использоваться наиболее часто.

Простое

В случае простого создания типа документа вам не потребуется писать какой-либо дополнительный код для обработки данных.

Для простого создания типа документа нужно:

• Создать все необходимые файлы и папки
• Подготовить шаблон документа
• Собрать данные
• Указать какой документ в какой формат вы желаете экспортировать.

Создание файлов и папок

Надо в корневом каталоге плагина, из которого производится экспорт, создать папку с именем templater. В ней, для каждого из документов, которые предполагается экспортировать, надо создать папку с именем типа документа. В них надо создать директории, с названиями форматов экспорта. Например, в плагине интерфейса exampleim планируется экспортировать документ с именем "тип_документа" в различные форматы. Тогда структура папок плагина должна быть такой:

   .../im/exampleim/templater/<тип_документа>/<имя_формата1>/
   .../im/exampleim/templater/<тип_документа>/<имя_формата2>/

Здесь:

• тип_документа - имя типа документа
• имя_формата - формат, в который нужно экспортировать файл

В свою очередь, внутри папки с именем формата должен лежать шаблон результирующего документа.

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

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

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

Например надо получить такой файл:

.

Тогда поля и блоки надо вставлять в файл шаблона так:

.

Изнутри файл, размеченный тегами Sigma будет выглядеть следующим образом:

   Отчет об индивидуальной успеваемости.
   Ученик {name}.
   Предмет, Оценка
   ‹!-- BEGIN grades_table --›
   {course}, {grade}
   ‹!-- END grades_table --›
                       {autor}.

Таким образом, объект данных для экспорта приведенной выше таблицы должен выглядеть так:

Сбор данных

Сбор данных при создании своего типа документа аналогичен сбору данных при использовании готового документа.

Указание формата и типа документа

Указание формата и типа документа происходит так же как и при использовании готового документа.

Возможности по настройке поведения

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

Создание формата

Если есть необходимость произвести экспорт в формат, который пока еще не предусмотрен плагином templater - у вас есть возможность самостоятельно дополнить список форматов, в которые возможен экспорт. Также в этом разделе будет описана возможность переопределения поведения существующего формата.

Все созданные форматы должны соответствовать определенным требованиям:

• располагаться в специальной папке,
  • внутри modlib\templater\formats\ если вы создаете новый формат
  • или внутри <тип_плагина>\<имя_плагина>\templater\<тип_документа>\
• наследовать базовый класс dof_modlib_templater_format и реализовывать все его базовые методы.

Расположение файлов

Для создания нового формата Структура папок:

• modlib - папка всех плагинов типа modlib
  • templater - папка плагина templater
    • formats - папка в которой лежат все форматы
      • <имя_формата> - имя созданного вами формата. Всегда задается как стандартное расширение файла указанного формата.
      • init.php - файл в котором будет содержаться новый класс формата
      • template.<имя_формата> - файл шаблона документа.

Для изменения поведения существующего формата

• <тип_плагина> - тип плагина, в котором нужно переопределить класс экспорта, например im
  • <имя_плагина> - имя плагина, в котором нужно переопределить класс экспорта, например genedu
    • templater - папка в которой хранятся все типы документов
      • <тип_документа> - папка с типом документа
        • <имя_формата> - формат, в который вы хотите сделать возможным экспорт. Всегда задается как стандартное расширение файла указанного формата (например pdf).
        • init.php - файл, в котором содержится переопределенный класс для формата.
        • template.<имя_формата> - файл шаблона документа. Более подробно о том, как должен называться файл шаблона - см. раздел "Форматы экспорта".

Создание класса

Стандарт именования классов

• Для создания нового формата dof_modlib_templater_format_имяформата
• Для изменения логики работы существующего формата dof_типплагина_имяплагина_templater_кодшаблона_имяформата

Для всех новых форматов экспорта в плагине templater существует абстрактный базовый класс dof_modlib_templater_format. Класс, который вы создаете должен наследоваться от него. В случае, если вы хотите изменить логику работы уже существующего формата, то класс можно наследовать непосредственно от него.

При создании нового формата обязательно нужно реализовать следующие методы:

• get_file($options) - получить файл в виде строки. Главная функция, производящая все преобразования над данными.
• get_filename($options) - получить имя файла вместе с расширением одной строкой.
• get_mimetype($options) - получить MIME-тип для подстановки его в HTTP-заголовок.

Пример:

   header('Content-Type: '.$format->get_mimetype().'charset=utf8');

Дальнейшее использование созданного вами формата аналогично использованию готового формата.

Более подробную информацию о методах и свойствах класса dof_modlib_templater_format можно найти в разделе API.

API плагина

В этом разделе описаны все функции интерфейса плагина templater.

Внешний

dof_modlib_templater:

• template($plugintype, $pluginname, $templatename, $data) — получить класс для экспорта в указанном плагине, с указанным названием. Возвращает объект класса dof_modlib_templater_package или dof_типплагина_имяплагина_templater_кодшаблона
  • $plugintype - Тип плагина
  • $pluginname - имя плагина
  • $templatename - имя шаблона для экспорта
  • $data - данные для экспорта
• template_path($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - путь к шаблону (корню или внутренней папке)
  • $plugintype - тип плагина (im, storage, modlib и т. д.)
  • $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 — в какой формат экспортировать,
  • $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

Форматы экспорта

DBG

Название формата происходит от слова "debug". Это тестовый формат, можете поэкспериментировать с ним, для того чтобы наглядно ознакомиться с работой плагина templater. Результат экспорта в этот формат представляет собой обычный текстовый файл.

ODF

Open Document Format. Этот формат используется документами OpenOffice. В этом формате можно создавать как обычные текстовые документы (odt), так и электронные таблицы (ods). Для подготовки документа нужно разметить его тегами шаблонизатора Sigma. Создание текстового документа и электронной таблицы происходит одинаково - разница только в расширении файла: odf - для текстового документа, и ods для электронной таблицы.

CSV

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

HTML

Экспорт в этот формат пригодиться в случае, если вам нужно сохранить данные из какого-либо документа как web-страницу.

Ссылки

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