Разработка:modlibs/templater
Содержание
- 1 Экспорт документов
- 2 Структура плагина templater
- 3 content.xml
- 4 Структура папок внешнего плагина
- 5 Структура классов
- 6 Список стандартных методов классов
- 7 Стандарт именования классов:
- 8 Реализация функционала классов
- 9 Структура вызова классов
- 10 Структура наследования классов форматирования отдельных документов
- 11 Структура наследования классов форматирования групп документов
- 12 Ссылки
Экспорт документов
Модуль реализуется как библиотека modlib, которая называется templater. Модуль предназначен для организации экспорта данных в различные форматы (odt,csv,версии для печати и т.д.). Данные для экспорта представляются в виде структурированного объекта (класс object()), в котором одиночные поля представляются скалярами, записи - объектами, а таблицы - массивами объектов. Структура данного объекта, по возможности, должна совпадать со структурой соответствующего объекта, используемого в storage.
Структура плагина templater
- templater - папка плагина;
- formats - папка, в которой лежат файлы, преобразующие данные в файл определенного типа.
- odf папка, содержащая все файлы, которые понадобятся для преобразования данных в один из форматов odt, ods и т.д.
- init.php - файл, содержащий класс dof_modlib_templater_format_odf для преобразования в конкретный формат
- csv - папка, содержащая все файлы, которые понадобятся для преобразования данных в формат csv.
- init.php - файл, содержащий класс dof_modlib_templater_format_csv для преобразования в конкретный формат
- odf папка, содержащая все файлы, которые понадобятся для преобразования данных в один из форматов odt, ods и т.д.
- init.php - обязательный файл плагина, содержит класс dof_modlib_templater, который вызывает собственный или внешний обработчик форматирования и экспорта
- format.php - файл, содержащий класс dof_modlib_templater_format - содержит базовый класс для остальных классов форматирования.
- package.php - файл, содержащий класс dof_modlib_templater_package, который вызывает собственный обработчик форматирования и экспорта
- formats - папка, в которой лежат файлы, преобразующие данные в файл определенного типа.
Назначение классов:
- dof_modlib_templater_format - абстрактный класс. Является родительским, для классов, реализующих преобразование данных в файл конкретного типа. Определяет минимальный обязательный набор методов для дочерних классов.
- dof_modlib_templater_format_odf - возвращает odf-файл как строку.
- dof_modlib_templater_package - стандартный обработчик экспорта. Получает необработанные данные, обрабатывает их и посылает клиенту.
- dof_modlib_templater - проверяет наличие у внешнего плагина своего обработчика экспорта. Если он есть, возвращает его, если нет - возвращает стандартный обработчик.
Как это работает:
- dof_modlib_templater вызывает стандартный обработчик экспорта dof_modlib_templater_package. В будущем, планируется возможность переопределять обработчик во внешнем шаблоне, в классе dof_типплагина_имяплагина_templater_имяшаблона.
- _templater_package вызывает стандартный преобразователь данных в файл нужного типа (например, odf) dof_modlib_templater_format_odf. В будущем планируется возможность переопределять преобразователь данных во внешнем плагине в классе с именем dof_типплагина_имяплагина_имяшаблона_odf;
- _format_odf ищет шаблон оформления документа в файле типплагина/имяплагина/templater/имяшаблона/odf/content.xml, читает его, и размещает переданные данные как указано в этом файле.
- Получившийся поток данных возвращается в _templater_package, который посылает его клиенту.
content.xml
Напомним, что файл должен быть размечен тэгами шаблонизатора PEAR::HTMLTemlateSigma.
Структура файла и правила оформления тегов
- Отдельное поле помечается фигурными скобками {}.
- Внутри скобок указывается имя поля. Например, {lastname} - поле, вместо которого должна подставляться фамилия.
- Если есть блок полей, например таблица оценок, то начало блока помечается тегом ‹!-- BEGIN grades_table --›.
- Окончание блока помечается тэгом ‹!-- END grades_table --›. Здесь grades_table - имя блока, все остальное - обязательная служебная конструкция. Между этими тегами можно размещать поля блока.
Структура объекта данных для экспорта
- Имя поля в файле-шаблоне должно совпадать с именем свойства в объекте данных.
- Если в файле есть блок полей, то имя блока в файле совпадает с именем свойства в объекте данных, а содержание блока - это массив объектов, каждая строка которого - это объект, свойства которого совпадают с именами полей блока.
Например надо получить такой файл:
Тогда файл шаблона выглядит так:
А объект данных для экспорта так:
Структура папок внешнего плагина
В плагине 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 и на основании которого выбирается расширение
- Ппака имяшаблона (например order)
- templater - в этой папке хранятся все шаблоны, принадлежащие этому плагину
Пример: в модуле типа 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_format_формат - стандартный класс экспорта в заданный формат
Список стандартных методов классов
dof_modlib_templater:
- template($plugintype, $pluginname, $templatename) — получить класс для экспорта в указанном плагине, с указанным названием. Возвращает объект класса dof_modlib_templater_packet или dof_типплагина_имяплагина_templater_кодшаблона
- template_path($plugintype, $pluginname, $templatenam,$adds=null) - путь к шаблону (корню или внутренней папке)
$plugintype - тип плагина (im, storage, modlib и т. д.) $pluginname - имя плагина $templatenam - имя шаблона форматирования $adds - дополнительный путь после папки шаблона
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) - путь к шаблону (работает через класс dof_modlib_templater)
- $adds - дополнительный путь, присоединяемый к возвращаемому функцией template_path в классе dof_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) - путь к папке данного формата (работает через класс package)
- $adds - дополнительный путь, присоединяемый к возвращаемому функцией template_path в классе dof_modlib_templater_package:
Стандарт именования классов:
Переопределенный класс парсера всего шаблона, который ищется при наличии init.php в корне шаблона: dof_типплагина_имяплагина_templater_кодшаблона
Переопределенный класс парсера шаблона для формата odf, который ищется при наличии файла init.php в шаблоне dof_типплагина_имяплагина_templater_кодшаблона_odf
Пример: Стандартный класс для парсера ODF dof_modlib_templater_format_odf
Реализация функционала классов
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.
- Файл есть - проверяем наличие класса с именем dof_типплагина_имяплагина_templater_кодшаблона.
- $templatename не указано. Возвращаем базовый плагин dof_modlib_templater_package.
function template_path($plugintype, $pluginname, $templatename=null, $adds=null) - путь к шаблону (корню или внутренней папке)
- Получаем путь к корню плагина.
- $templatename=null. Не включаем имя папки шаблона в путь.
- $templatename<>null. Обращаемся к внешнему плагину. Включаем имя папки шаблона в путь: /templater/$templatename.
- $adds=null. Включаем в путь дополнительные фрагменты пути.
- $adds<>null. Не включаем в путь дополнительные фрагменты пути.
- Возвращаем получившийся путь.
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.
- Файл есть. Проверяем наличие в нем класса dof_modlib_templater_format_$type.
- $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)
- возвращает строку и путь к шаблону, который в текущий момент.
Загрузка данных из объекта в файл шаблона
- Подключаем сигму. require_once 'HTML/Template/Sigma.php';
- Создаем объект от нее. $tpl =& new HTML_Template_Sigma('.');
- Загружаем файл шаблона.
- Файл есть: $tpl->loadTemplateFile('table.html');
- Файла нет: Что делаем?
- Получаем данные.
- Данные есть: Продолжаем обработку.
- Данных нет: Что делаем?
- Вставляем их в шаблон.
- Вставить поле set_field: $tpl->setVariable(fieldname, value);
- Вставить блок set_block:
- блок есть:
- Перебираем в цикле переменные блока и вызываем set_field;
- Применить вставку блока $tpl->parse('имяблока');
- блока нет: пропускаем ввод?
- блок есть:
- Возвращаем файл с данными. $tpl->show();
Структура вызова классов
Структура наследования классов форматирования отдельных документов
Структура наследования классов форматирования групп документов