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

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

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

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

Модуль предназначен для организации экспорта данных в документы различных форматов (odt,csv,версии для печати и т.д.). Принцип работы таков:

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

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

Модуль реализуется как библиотека modlib, которая называется templater.

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

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

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

Создаем файлы и папки

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

   .../im/exampleim/templater/sample/csv/
   .../im/exampleim/templater/sample/odf/

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

   .../im/exampleim/templater/sample/csv/sample.csv
   .../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

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

Подготовка шаблона и данных

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

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

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

.

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

.

Файл формата csv представляет собой набор строк, в которых данные разделены запятыми. Поэтому для этого примера файл шаблона grades_table.csv будет выглядеть примерно так:

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

Файл content.xml имеет большое количество тегов разметки. поэтому увидеть его можно здесь. Данные для экспорта представляются в виде структурированного объекта (класс object()), в котором одиночные поля представляются скалярами, записи - объектами, а таблицы - массивами объектов. Структура данного объекта, по возможности, должна совпадать со структурой соответствующего объекта, используемого в storage.

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

Теперь, когда у нас готов шаблон и готовы данные, мы можем посылать файл.

Отправка файла

В нужном файле вы создаете (например) кнопку "Экспорт в csv". А в ее обработчик вставляете такой код:

• $tp = $DOF->modlib('templater')->template('im', 'exampleim', $obj, 'sample');. Здесь мы создаем объект экспорта, которому указываем
  • тип модуля, из которого надо произвести экспорт - im;
  • код модуля, из которого надо произвести экспорт - exampleim;
  • объект данных для экспорта - $obj;
  • директорию документа, который надо экспортировать - sample.
• $tp->send_file('csv');. Здесь мы инициализируем отправку файла клиенту, указывая в каком формате надо отправить файл.

Экспорт в формат odf производится аналогично.

Назначение классов

• dof_modlib_templater - Самый верхний уровень экспорта. Проверяет наличие у внешнего плагина своего обработчика экспорта. Если он есть, возвращает его, если нет - возвращает стандартный обработчик.
• dof_modlib_templater_package - Уровень ниже. Вызывается предыдущим классом (dof_modlib_templater). Представляет собой стандартный, общий для всех форматов, обработчик экспорта. Получает необработанные данные, обрабатывает их и посылает клиенту. Для получения готового файла нужно обращаться к API именно этого класса, предварительно получив его экземпляр из dof_modlib_templater. Список его методов - см. ниже.
• dof_modlib_templater_format_имяформата - Самый низкий уровень экспорта. Этот класс занимается преобразованием переданных данных в файл указанного формата. После преобразования должен вернуть файл как строку. Вся основная работа по преобразованию данных в готовый файл происходит здесь.
• dof_modlib_templater_format - Абстрактный класс. Сам по себе не входит в иехархию экспорта, но является родительским, для всех классов, реализующих преобразование данных в файл конкретного типа. Определяет минимальный обязательный набор методов для дочерних классов (вида dof_modlib_templater_format_имяформата). Все классы, которые будут заниматься преобразованием данных в какой-либо формат должны быть наследованы от него.

Структура вызова классов

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

Пример работы экспорта для формата odf

• dof_modlib_templater вызывает стандартный обработчик экспорта dof_modlib_templater_package. В будущем, планируется возможность переопределять обработчик во внешнем шаблоне, в классе dof_типплагина_имяплагина_templater_имяшаблона.
• dof_modlib_templater_package вызывает стандартный преобразователь данных в файл нужного типа (например, odf) dof_modlib_templater_format_odf. В будущем планируется возможность переопределять преобразователь данных во внешнем плагине в классе с именем dof_типплагина_имяплагина_имяшаблона_odf;
• dof_modlib_templater_format_odf ищет шаблон оформления документа в файле типплагина/имяплагина/templater/имяшаблона/odf/content/content.xml, читает его, и размещает переданные данные как указано в этом файле.
• Получившийся поток данных возвращается в dof_modlib_templater_package, который посылает его клиенту.

Назначение content.xml

Напомним, что файл должен быть размечен тегами шаблонизатора PEAR::HTMLTemlateSigma. В content.xml содержится все основное содержание файла для экспорта.

Структура плагина templater

• templater - папка плагина;
  • init.php - обязательный файл плагина, содержит класс dof_modlib_templater, который вызывает собственный или внешний обработчик форматирования и экспорта
  • format.php - файл, содержащий класс dof_modlib_templater_format - содержит базовый класс для остальных классов форматирования.
  • package.php - файл, содержащий класс dof_modlib_templater_package, который вызывает собственный обработчик форматирования и экспорта
  • lib.php - файл, который содержит класс placeholder. Этот класс используется для замены в шаблоне полей вставки данных самими данными.
  • formats - папка, в которой лежат файлы, преобразующие данные в файл определенного типа.
    • odf - папка, содержащая все файлы, которые понадобятся для преобразования данных в один из форматов odt, ods и т.д.
      • init.php - файл, содержащий класс dof_modlib_templater_format_odf для преобразования в конкретный формат
    • csv - папка, содержащая все файлы, которые понадобятся для преобразования данных в формат csv.
      • init.php - файл, содержащий класс dof_modlib_templater_format_csv для преобразования в конкретный формат

Структура папок внешнего плагина

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

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

• папка плагина, использующего modlib/templater для экспорта документа
  • templater - в этой папке хранятся все шаблоны, принадлежащие этому плагину
    • Ппака имяшаблона (например order)
      • init.php - необязательный файл, переопределяющий класс экспорта
      • Папка типфайла (pdf, csv)
        • init.php - необязательный (для некоторых шаблонов) файл, переопределяющий класс преобразования данных в файл заданного типа;
      • odf - пример шаблона odf (конкретный формат odt,ods задается уже внутри шаблона, поскольку все документы устроены одинаково);
        • init.php (необязательно);
        • content - папка с распакованным документов ODF;
          • content.xml - xml-документ с основным контентом, размеченный тегами шаблонизатора PEAR::HTMLTemlateSigma
          • mimetype - mime-тип документа, который будет использоваться при передаче документа по http и на основании которого выбирается расширение

Пример: в модуле типа im, который называется sample при просмотре расписания необходимо экспортировать все уроки за месяц. Для этого структура папок im должна выглядеть следующим образом:

Каждый синий квадрат обозначает папку, желтый — пояснение, серый — отдельный файл.

В каждой папке с типом экспорта может лежать файл init.php, который содержит класс, наследуемый от класса dof_modlib_templater и переопределяющий его метод format(). Именно он определяет, каким образом будет отформатирован окончательный файл. Для формата odt в папке с названием формата должна находится папка «content», содержащая следующие файлы:

• content.xml - xml-документ с основным содержанием, размеченный тегами шаблонизатора PEAR::HTMLTemlateSigma
• mimetype - mime-тип документа, который будет использоваться при передаче документа по http и на основании которого выбирается расширение

Эти файлы будут определять форматирование будущего документа. Их можно получить, распаковав обычный odt-файл (как zip-архив).

Структура классов

• dof_modlib_templater - класс плагина DOF
• dof_modlib_templater_package - класс шаблона документа
  • dof_типплагина_имяплагина_templater_кодшаблона - переопределенный класс шаблона данного документа
  • dof_im_genedu_templater_order - переопределенный класс шаблона документа order из плагина im/genedu
• dof_modlib_templater_format - базовый (абстрактный) класс формата экспорта
  • dof_modlib_templater_format_формат - стандартный класс экспорта в заданный формат
    • dof_типплагина_имяплагина_templater_кодшаблона_формат - переопределенный класс экспорта заданного шаблона в заданный формат
  • dof_modlib_templater_format_odt - стандартный класс экспорта в формат odt
    • dof_im_genedu_templater_order_odf - переопределенный класс экспорта шаблона order из плагина im/genedu в формат odf

Наследование от dof_modlib_templater_package

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

Наследование от dof_modlib_templater_format

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

Реализация функционала классов

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

dof_modlib_templater

function template($plugintype, $pluginname, $templatename=null) — получить класс для экспорта в указанном плагине, с указанным названием. Возвращает объект класса dof_modlib_templater_package или dof_типплагина_имяплагина_templater_кодшаблона.

• $templatename указано. Это значит, что шаблон переопределен во внешнем плагине. Проверяет наличие плагина ($plugintype,$pluginname).
  • Если его нет - возвращает false.
  • Если он есть, проверяет наличие файла templater\$templatename\init.php.
    • Файл есть - проверяем наличие класса с именем dof_типплагина_имяплагина_templater_кодшаблона.
      • Класс есть - возвращаем объект от него.
      • Класса нет - возвращаем false;
    • Файла нет - возвращаем объект от стандартного класса dof_modlib_templater_package.
• $templatename не указано. Возвращаем базовый плагин dof_modlib_templater_package.

function template_path($plugintype, $pluginname, $templatename=null, $adds=null, $fromplugin=null) - путь к шаблону (корню или внутренней папке)

• Вычисляем как строку путь ко внешнему плагину и путь внутри template/path
• Запоминаем обе строки
• В зависимости от переданных параметров возвращаем внешний или внутренний путь.
  • $templatename==null
    • $fromplugin - null или false - возвращаем путь внутри modlib/templater
    • $fromplugin - true - ошибка
  • $templatename<>null
    • $fromplugin - null - ищем сначала во внешнем плагине, затем в modlib/templater, если нигде не нашлось - возвращаем false
    • $fromplugin - true - ищем только во внешнем плагине. Возвращаем внешний путь или false в случае ошибки.
    • $fromplugin - false - ищем только во внутри modlib/templater. Возвращаем внутренний путь или false в случае ошибки.
• Возвращенная строка гарантированно является строкой директорией, файлом, или символической ссылкой

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

№	$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

Класс шаблона документа

function __construct($dof,$plugintype, $pluginname, $templatename=null)

• Делает переданные переменные свойствами класса.
• Загружает файл format.php, с обстрактным классом.

function set_data($obj) - загрузить необработанные данные в объект.

• Помещает $obj в свойство класса $data;

private function get_data() - Получить необработанный объект с данными.

• Возвращает свойство класса $data;

function get_file($type, $options=null) - получить отформатированные данные, пригодные для обработки функцией file_put_contents().

• Ищем файл $type.php в папке modlib/templater/formats/.
  • Файл есть. Проверяем наличие в нем класса dof_modlib_templater_format_$type.
    • Класс есть. Создаем объект от него.
    • Класса нет - возвращаем false;
  • Файла нет. Возвращаем false.
• $data = $this->get_data();//получаем данные для форматирования.
• Превращаем данные в файл методами из dof_modlib_templater_format_$type.
• Возвращаем файл в виде строки.

function send_file($type, $options) инициализировать передачу файла клиенту через браузер

• Получаем файл в виде строки и отправляем его пользователю.

function get_formats()

• сканируем папку modlibs/templater/formats и получаем список форматов, в которые мы можем экспортировать.
• Если указан шаблон внешнего плагина, то сканируем папку $plugintype/$pluginname/$templatename/.Получаем список форматов.
• Объединяем оба списка.
• Для каждого типа файла проверяем наличие шаблонов для экспорта. Если шаблона нет - исключаем тип из списка форматов.
• Возвращаем массив с перечнем типов файлов, в которые возможен экспорт. Или пустой массив.

function template_path($adds=null) - путь к шаблону (работает через класс dof_modlib_templater).

dof_modlib_templater_format

Сам класс dof_modlib_templater_format является абстрактным для всех форматов, поэтому процесс работы методов будет описываться для его наследников (dof_modlib_templater_format_odf, dof_modlib_templater_format_xls и т. д.)

__construct($dof, $plugintype, $pluginname, $templatename=null)

• Создает объект для указанного плагина, указанного формата.

get_file($options=null)

• Выдает строку отфарматированных данных, пригодных для обработки функцией file_put_contents(). Весь процесс обработки текста происходит именно в этой функции

set_data($data)

• Получает необработанные данные в объекте $data и помещает их в поле $this->data для последующий обработки. При необходимости в эту функцию могут быть добавлены какие-либо проверки.

get_filename($options=null)

• Получить имя файла. Эта функция Просто возвращает имя файла вместе с расширением.

get_mimetype($options=null)

• Получить строку MIMETYPE для указанного файла, которую можно будет послать как HTTP-заголовок. Пример:

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

template_path($adds=null)

• возвращает строку и путь к шаблону, который в текущий момент.

dof_templater_format_odf

Вставка данных из объекта в файл

• Подключаем сигму. require_once 'HTML/Template/Sigma.php';
• Создаем объект от нее. $tpl =& new HTML_Template_Sigma('.');
• Загружаем файл шаблона.
  • Файл есть: $tpl->loadTemplateFile('table.html');
  • Файла нет: возвращаем пустой файл. Он должен лежать у нас.
• Получаем объект с данными. К этому моменту данные точно есть.
  • Вставляем их в шаблон insert_data.
    • Вставить поле set_field: $tpl->setVariable(fieldname, value);
    • Вставить блок set_block:
      • блока нет: переходим к следующему элементу вставки
      • блок есть:
        • Перебираем в цикле переменные блока и вызываем set_field;
        • Применить вставку блока $tpl->parse('имяблока');
• Возвращаем файл с данными. $tpl->get();

Список дополнительных функций

• $tpl. Глобальная переменная - экземпляр от HTML_Template_Sigma.
• insert_content(). Эта функция вставляет переданные данные в файл и возвращает его как строку.
• insert_data($data). Эта функция вставляет поля и блоки из объекта данных в файл.
• set_block($blockname). Вставляет блок данных.
• set_field($name, $value). Вставляет поле.

API

API для использования плагина templater

Здесь описаны классы и их методы, которые необходимо использовать для того, чтобы осуществлять экспорт документов. Их достаточно для большинства задач.

dof_modlib_templater:

• template($plugintype, $pluginname, $templatename) — получить класс для экспорта в указанном плагине, с указанным названием. Возвращает объект класса dof_modlib_templater_packet или dof_типплагина_имяплагина_templater_кодшаблона. В дальнейшем, полученный оюъект будет производить все действия, необходимые для экспорта документов.
  • $plugintype - тип плагина (im, storage, modlib и т. д.)
  • $pluginname - имя плагина
  • $templatename - имя шаблона форматирования
• template_path($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - путь к шаблону (корню или внутренней папке). используется только для получения пути. Если запрошенный путь не существует - вернет false.
  • $plugintype - тип плагина (im, storage, modlib и т. д.)
  • $pluginname - имя плагина
  • $templatename - имя шаблона форматирования
  • $adds - дополнительный путь после папки шаблона
  • $fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Ее возможные значения:
    • null (по умолчанию) - искать путь сначала во внешнем плагине, а затем в modlib/templater
    • true - искать только во внешнем планине
    • false - искать только в modlib/templater

API для разработки собственных модулей к плагину templater

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

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

Переопределенный класс парсера всего шаблона, который ищется при наличии init.php в корне шаблона: dof_типплагина_имяплагина_templater_кодшаблона

Переопределенный класс парсера шаблона для указанного формата, который ищется при наличии файла init.php в шаблоне dof_типплагина_имяплагина_templater_кодшаблона_имяформата

Пример:

Стандартный класс для парсера документов в формате ODF dof_modlib_templater_format_odf

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() - внутренний метод. Получить необработанный объект с данными.
• 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_format

• __construct($dof,$package)
  • $dof
  • $package
• 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

Ссылки

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