Разработка:modlibs/templater — различия между версиями
Ilya (обсуждение | вклад) (→Назначение классов: детализовано описание классов.) |
K-krsnv (обсуждение | вклад) (→Дополнительные методы Sigma) |
||
(не показано 127 промежуточных версий 3 участников) | |||
Строка 4: | Строка 4: | ||
}} | }} | ||
− | == | + | == Принципы работы == |
+ | Плагин templater обеспечивает все действия по экспорту данных и создание любых электронных документов (отчетов, приказов, графиков и т. п.) | ||
=== Общие сведения === | === Общие сведения === | ||
− | + | Все документы формируются следующим образом: | |
* на основе требуемого документа создается файл шаблона документа; | * на основе требуемого документа создается файл шаблона документа; | ||
* собираются данные для вставки в шаблон | * собираются данные для вставки в шаблон | ||
* формируется экспортируемый документ - производится вставка данных в шаблон; | * формируется экспортируемый документ - производится вставка данных в шаблон; | ||
* сформированный документ посылается клиенту по http-протоколу. | * сформированный документ посылается клиенту по http-протоколу. | ||
− | Шаблон документа формируется из документа по специальным правилам, а затем размещается в оговоренном месте плагина, из которого производится экспорт. Затем по аналогичным правилам производится вставка данных. Сбор и подготовка данных для экспорта производятся тем же плагином. В настоящее время формирование шаблона производится | + | Шаблон документа формируется из документа по специальным правилам, а затем размещается в оговоренном месте плагина, из которого производится экспорт. Затем по аналогичным правилам производится вставка данных. Сбор и подготовка данных для экспорта производятся тем же плагином. В настоящее время формирование шаблона производится вручную. Описываемый модуль получает путь к каталогу документа, данные для вставки и формат документа. На основе этих данных он формирует документ и посылает его клиенту. |
− | + | === Формат исходных данных === | |
+ | Данные, предназначенные для экспорта должны соответствовать следующим стандартам: | ||
+ | * Исходные данные всегда представлены в виде объекта класса stdClass (стандартный объект PHP). | ||
+ | * Поля объекта могут содержать строки, числа и массивы объектов (массивы строк или чисел не допускаются). Данные других типов не обрабатываются. | ||
+ | * Строки и числа подставляются в шаблон документа "как есть". | ||
+ | * Данные для экспорта представляются в виде структурированного объекта (класс object()), в котором одиночные поля представляются скалярами, записи - объектами, а таблицы - массивами объектов. | ||
+ | Желательно для создания объекта данных для экспорта создавать отдельный класс, который решает эту задачу. | ||
+ | === Пример исходных данных === | ||
+ | В этом примере мы построим объект для экспорта оценок учеников двух классов. У каждого класса есть название, предмет, и дата, за которую выставлялись оценки. В каждом классе есть несколько учеников, которые эти оценки получили. Таким образом, если мы хотим получить такую таблицу: | ||
+ | {|border="1" | ||
+ | |№ | ||
+ | |ФИО ученика | ||
+ | |оценка | ||
+ | |- | ||
+ | |colspan="3" |З<sup>б</sup> класс, Математика, 21.01.09 | ||
+ | |- | ||
+ | |1 | ||
+ | |Замеладский Алексей | ||
+ | |5 | ||
+ | |- | ||
+ | |2 | ||
+ | |Гусева Татьяна | ||
+ | |4 | ||
+ | |- | ||
+ | |colspan="3" |5<sup>б</sup> класс, Русский язык, 27.01.09 | ||
+ | |- | ||
+ | |1 | ||
+ | |Коньков Сергей | ||
+ | |5 | ||
+ | |- | ||
+ | |2 | ||
+ | |Захаров Александр | ||
+ | |3 | ||
+ | |} | ||
+ | |||
+ | Данные для экспорта будут выглядеть следующим образом: | ||
+ | <code 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 | ||
+ | ) | ||
+ | </code php> | ||
+ | === Реализация экспорта === | ||
==== Подготовка к экспорту ==== | ==== Подготовка к экспорту ==== | ||
Для начала надо убедиться, что на месте вспомогательные средства. Т.е. установлен описываемый плагин '''templater''', и плагин обеспечивающий превращения шаблона документа в документ - '''pear'''. Поэтому убедитесь, что у вас | Для начала надо убедиться, что на месте вспомогательные средства. Т.е. установлен описываемый плагин '''templater''', и плагин обеспечивающий превращения шаблона документа в документ - '''pear'''. Поэтому убедитесь, что у вас | ||
− | * установлен плагин '''pear'''. | + | * установлен плагин '''pear'''. Удостоверьтесь, что на странице списка установленных плагинов, напротив модуля pear написано "Удалить, а не " "Установить". |
* в нем есть библиотека '''HTML_Template_Sigma'''. Проверьте наличие файла '''.../modlibs/pear/libs/HTML_Template_Sigma/Sigma.php'''. | * в нем есть библиотека '''HTML_Template_Sigma'''. Проверьте наличие файла '''.../modlibs/pear/libs/HTML_Template_Sigma/Sigma.php'''. | ||
* установлен описываемый модуль - '''templater'''. Проверьте так же как и '''pear'''. | * установлен описываемый модуль - '''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 | ||
− | + | Внутри этих папок следует разместить шаблоны документов для экспорта. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | [[ | + | Правила подготовки шаблона описаны в разделе [[Разработка:modlibs/templater#Подготовка шаблона документа|Подготовка шаблона документа]]. |
− | + | Теперь, когда шаблон есть, можно переходить к следующему этапу - сбору данных для экспорта. Объект экспорта должен соответствовать структуре объекта, описанной в разделах [[Разработка:modlibs/templater#Формат исходных данных|Формат исходных данных]] и [[Разработка:modlibs/templater#Пример исходных данных|Пример исходных данных]]. | |
− | + | Теперь все необходимые приготовления выполнены и можно переходить непосредственно к экспорту. | |
− | + | ==== Экспорт документа ==== | |
− | + | Собственно экспорт осуществляется в два этапа. Создание объекта экспорта и инициализация экспорта. Поясним оба этапа на примере. Предположим, мы хотим экспортировать ведомость оценок '''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); | ||
+ | Имя файла надо указывать без расширения. | ||
− | === | + | === Подготовка шаблона документа === |
− | В | + | Если вам нужно создать новый документ, то нужно создать и новый шаблон документа. |
+ | Файл шаблона должен быть размечен тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma PEAR::HTMLTemlateSigma]. | ||
+ | В нем оформляются места для вставки данных - поля и блоки. | ||
+ | *Отдельное поле помечается фигурными скобками '''{}'''. | ||
+ | *Внутри скобок указывается имя поля. Например, '''{lastname}''' - поле, вместо которого должна подставляться фамилия. | ||
+ | *Если есть блок полей, то начало блока помечается тегом '''‹!-- BEGIN block_name --›'''. | ||
+ | *Окончание блока помечается тегом '''‹!-- END block_name --›'''. Здесь block_name - имя блока, все остальное - обязательная служебная конструкция. Между этими тегами нужно размещать поля блока и другие блоки. | ||
+ | Например надо таблицу ведомости оценок (см. [[Разработка:modlibs/templater#Пример исходных данных|Пример исходных данных]]) | ||
− | + | {|border="1" | |
− | + | |№ | |
− | + | |ФИО ученика | |
− | + | |оценка | |
− | + | |- | |
− | + | |colspan="3" |З<sup>б</sup> класс, Математика, 21.01.09 | |
− | + | |- | |
− | + | |1 | |
− | + | |Замеладский Алексей | |
− | + | |5 | |
− | + | |- | |
− | + | |2 | |
+ | |Гусева Татьяна | ||
+ | |4 | ||
+ | |- | ||
+ | |colspan="3" |5<sup>б</sup> класс, Русский язык, 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-документа описана [[Разработка:modlibs/templater#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'' можно найти в разделе [[Разработка:modlibs/templater#dof_modlib_templater_format|API]]. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | === | + | === Альтернативный способ экспорта === |
− | + | Если работа стандартного контейнера экспорта [[Разработка:modlibs/templater#dof_modlib_templater_package|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 - данные для экспорта, структурированные как указано [[Разработка:modlibs/templater#Формат исходных данных|выше]]. | ||
+ | ** $templatename - имя документа; здесь указывается имя папки, в которой лежат шаблоны для формирования документа в разных форматах. В рассмотренных выше примерах это '''grages_list''', '''teachers_list''' или '''students_list'''. | ||
− | + | *'''template_path'''($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - возвращает путь внутри плагина. | |
− | + | ** $plugintype - тип плагина | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | *''' | ||
− | ** $plugintype - тип плагина | ||
** $pluginname - имя плагина | ** $pluginname - имя плагина | ||
− | ** $templatename - имя | + | ** $templatename - имя документа (см. предыдущую функцию) |
− | + | ** $adds - дополнительный путь внутри плагина | |
− | + | ** $fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Ее возможные значения: | |
− | + | *** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем во внутреннем | |
− | |||
− | **$adds - дополнительный путь | ||
− | **$fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Ее возможные значения: | ||
− | *** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
*** true - искать только во внешнем планине | *** true - искать только во внешнем планине | ||
*** false - искать только в modlib/templater | *** false - искать только в modlib/templater | ||
− | + | Таблица, описывающая работу этой функции: | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | Таблица, | ||
− | |||
{| border=1 | {| border=1 | ||
|'''№''' | |'''№''' | ||
Строка 317: | Строка 317: | ||
|} | |} | ||
− | ===dof_modlib_templater_package=== | + | ====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|$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) - Форматирует системную дату/время. Равносилен стандартной функции РНР [http://ru2.php.net/manual/ru/function.strftime.php strftime]. |
− | + | *'''mb_substr'''($value,$start = 0,$length = 1) - Получает часть строки. Равносилен стандартной функции РНР [http://ru2.php.net/manual/ru/function.mb-substr.php 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. | ||
+ | Этот формат используется документами [http://openoffice.ru OpenOffice]. В этом формате можно создавать как обычные текстовые документы (odt), так и электронные таблицы (ods). Для подготовки документа нужно разметить его тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma Sigma]. Создание текстового документа и электронной таблицы происходит одинаково - разница только в расширении файла: odt - для текстового документа, и ods для электронной таблицы. | ||
− | ''' | + | Экспорт в формат odf реализуется стандартным образом. Отдельных слов, в силу особенностей структуры документа, заслуживает только подготовка шаблона. |
+ | Все файлы формата odf представляют собой zip-архивы определенной структуры. У '''odt''' или '''ods''' документов собственно текст находится в файле '''content.xml''', который лежит в корне архива. Для того, чтобы правильно разметить документ - воспользуйтесь разделом [[Разработка:modlibs/templater#Подготовка шаблона документа|Подготовка шаблона документа]]. | ||
− | + | В плагине, из которого планируется реализовать экспорт в 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 | ||
+ | Ниже представлена схема структуры папок, с пояснением, для чего какие файлы и директории нужны. | ||
+ | [[Изображение:folders5.jpeg]] | ||
− | ''' | + | Пример реализации экспорта в '''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'''. О том, как правильно его разметить можно прочитать в разделе [[Разработка:modlibs/templater#Подготовка шаблона документа|Подготовка шаблона документа]]. | ||
+ | Пример кода: | ||
+ | $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'); | ||
== Ссылки == | == Ссылки == | ||
*[http://pear.php.net/package/HTML_Template_Sigma Шаблонизатор HTMLTemplateSigma] | *[http://pear.php.net/package/HTML_Template_Sigma Шаблонизатор HTMLTemplateSigma] | ||
*[http://pear.php.net/manual/en/package.html.html-template-sigma.intro-syntax.php Справка по синтаксису шаблонизатора Sigma] | *[http://pear.php.net/manual/en/package.html.html-template-sigma.intro-syntax.php Справка по синтаксису шаблонизатора Sigma] |
Текущая версия на 16:59, 5 апреля 2013
Плагин | |
Название | 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');