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

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

Содержание

1 Принципы работы
2 Использование
3 API плагина
4 Форматы экспорта
5 Ссылки

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

Плагин 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
   )

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

Каждый формат экспорта по-своему обрабатывает данные, указанные в типе документа. Тем не менее, какой бы формат экспорта не был выбран (например 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

Дополнительные методы Sigma

date($fofmat,$value = null) - Форматирует системную дату/время. Равносилен стандартной функции РНР date.
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. Создание текстового документа и электронной таблицы происходит одинаково - разница только в расширении файла: odf - для текстового документа, и ods для электронной таблицы.

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

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

Сбор данных описан выше. Следующие этапы необходимо рассмотреть более подробно.

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

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

В папке odf, должна лежать папка с именем content, в которой должны лежать каталоги и файлы распакованные из этого архива. Собственно текст документа sample.odt хранится в файле content.xml. Поэтому именно этот файл должен быть размечен как шаблон документа. Остальные файлы и папки можно оставить без изменения. В итоге мы должны увидеть что-то подобное:

   .../im/exampleim/templater/sample/odf/content/Configurations2/
   .../im/exampleim/templater/sample/odf/content/META-INF/
   .../im/exampleim/templater/sample/odf/content/Thumbnails/
   .../im/exampleim/templater/sample/odf/content/content.xml
   .../im/exampleim/templater/sample/odf/content/meta.xml
   .../im/exampleim/templater/sample/odf/content/mimetype
   .../im/exampleim/templater/sample/odf/content/settings.xml

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

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

Обращение к методам плагина происходит стандартным образом, описанным в разделе Указание формата и типа документа.

Пример кода

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

CSV

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

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

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

Поскольку csv-файлы имеют достаточно простую структуру - шаблоны для их построения не используются. Данные поступают в объект, в них вставляются текстовые разделители, после чего обработанные данные отсылаются клиенту.

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

Обращение к методам плагина происходит стандартным образом, описанным в разделе Указание формата и типа документа.

Пример кода

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

HTML

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

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

Подготовка шаблона документа для html-файла похожа на подготовку шаблона для формата odf. Для начала нужно создать все необходимые папки. Для формата html структура папок будет выглядеть так:

   .../im/exampleim/templater/<тип_документа>/html/

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

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

Обращение к методам плагина происходит стандартным образом, описанным в разделе Указание формата и типа документа.

Пример кода

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

Ссылки

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

Содержание

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

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

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

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

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

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

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

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

Сбор данных

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

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

Простое

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

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

Сбор данных

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

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

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

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

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

API плагина

Внешний

dof_modlib_templater:

dof_modlib_templater_package:

Внутренний

dof_modlib_templater_package:

dof_modlib_templater_format

Дополнительные методы Sigma

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

ODF

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

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

Пример кода

CSV

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

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

Пример кода

HTML

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

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

Пример кода

Ссылки

Навигация

Поиск