Разработка:modlibs/templater — различия между версиями

Материал из DOF
Перейти к: навигация, поиск
(Назначение классов: детализовано описание классов.)
(Дополнительные методы Sigma)
 
(не показано 127 промежуточных версий 3 участников)
Строка 4: Строка 4:
 
}}
 
}}
  
== Принцип работы ==
+
== Принципы работы ==
 +
Плагин templater обеспечивает все действия по экспорту данных и создание любых электронных документов (отчетов, приказов, графиков и т. п.)
 
=== Общие сведения ===
 
=== Общие сведения ===
Модуль предназначен для организации  экспорта данных в документы различных форматов (odt,csv,версии для печати и т.д.). Принцип работы таков:
+
Все документы формируются следующим образом:
 
* на основе требуемого документа создается файл шаблона документа;
 
* на основе требуемого документа создается файл шаблона документа;
 
* собираются данные для вставки в шаблон
 
* собираются данные для вставки в шаблон
 
* формируется экспортируемый документ - производится вставка данных в шаблон;
 
* формируется экспортируемый документ - производится вставка данных в шаблон;
 
* сформированный документ посылается клиенту по  http-протоколу.
 
* сформированный документ посылается клиенту по  http-протоколу.
Шаблон документа формируется из документа по специальным правилам, а затем размещается в оговоренном месте плагина, из которого производится экспорт. Затем по аналогичным правилам производится вставка данных. Сбор и подготовка данных для экспорта производятся тем же плагином. В настоящее время формирование шаблона производится в ручную.  Описываемый модуль получает путь к каталогу документа, данные для вставки и формат документа. На основе этих данных он формирует документ и посылает его клиенту.
+
Шаблон документа формируется из документа по специальным правилам, а затем размещается в оговоренном месте плагина, из которого производится экспорт. Затем по аналогичным правилам производится вставка данных. Сбор и подготовка данных для экспорта производятся тем же плагином. В настоящее время формирование шаблона производится вручную.  Описываемый модуль получает путь к каталогу документа, данные для вставки и формат документа. На основе этих данных он формирует документ и посылает его клиенту.
  
Модуль реализуется как библиотека modlib, которая называется templater.
+
=== Формат исходных данных ===
 +
Данные, предназначенные для экспорта должны соответствовать следующим стандартам:
 +
* Исходные данные всегда представлены в виде объекта класса 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'''. Удостоверьтесь, что на странице списка установленных плагинов, напротив модуля 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
  
===== Создаем файлы и папки =====
+
Внутри этих папок следует разместить шаблоны документов для экспорта.
Надо в корневом каталоге плагина, из которого производится экспорт, создать папку с именем '''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
 
Теперь надо разметить шаблоны и собрать данные для вставки.
 
===== Подготовка шаблона и данных =====
 
Файл шаблона должен быть размечен тэгами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma].
 
В нем оформляются места для вставки данных - поля и блоки.
 
*Отдельное поле помечается фигурными скобками '''{}'''.
 
*Внутри скобок указывается имя поля. Например, '''{lastname}''' - поле, вместо которого должна подставляться фамилия.
 
*Если есть блок полей, то начало блока помечается тегом '''&lsaquo;!-- BEGIN block_name --&rsaquo;'''.
 
*Окончание блока помечается тэгом '''&lsaquo;!-- END block_name --&rsaquo;'''. Здесь block_name - имя блока, все остальное - обязательная служебная конструкция. Между этими тегами нужно размещать поля блока и другие блоки.
 
Например надо получить такой файл:
 
  
[[Изображение:sample1.jpg]].  
+
Правила подготовки шаблона описаны в разделе [[Разработка:modlibs/templater#Подготовка шаблона документа|Подготовка шаблона документа]].  
  
Тогда поля и блоки надо вставлять в файл шаблона так:
+
Теперь, когда шаблон есть, можно переходить к следующему этапу - сбору данных для экспорта. Объект экспорта должен соответствовать структуре объекта, описанной в разделах [[Разработка:modlibs/templater#Формат исходных данных|Формат исходных данных]] и [[Разработка:modlibs/templater#Пример исходных данных|Пример исходных данных]].
  
[[Изображение:sample2.jpg]].
+
Теперь все необходимые приготовления выполнены и можно переходить непосредственно к экспорту.
  
Файл формата csv представляет собой набор строк, в которых данные разделены запятыми. Поэтому для этого примера файл шаблона grades_table.csv будет выглядеть примерно так:
+
==== Экспорт документа ====
    Отчет об индивидуальной успеваемости.
+
Собственно экспорт осуществляется в два этапа. Создание объекта экспорта и инициализация экспорта. Поясним оба этапа на примере. Предположим, мы хотим экспортировать ведомость оценок '''grades_list''' из плагина '''reports''' в формат '''odf'''. Тогда
    Ученик {name}.
 
    Предмет, Оценка
 
    &lsaquo;!-- BEGIN grades_table --&rsaquo;
 
    {course}, {grade}
 
    &lsaquo;!-- END grades_table --&rsaquo;
 
                        {autor}.
 
Файл '''content.xml''' имеет большое количество тегов разметки. поэтому увидеть его можно '''здесь'''.
 
Данные для экспорта представляются в виде структурированного объекта (класс object()), в котором одиночные поля представляются скалярами, записи - объектами, а таблицы - массивами объектов. Структура данного объекта, по возможности, должна совпадать со структурой соответствующего объекта, используемого в storage.
 
  
Таким образом, объект данных для экспорта приведенной выше таблицы должен выглядеть так:  
+
* Получаем нужный объект:
 +
    $exporter = $DOF->modlib('templater')->template('im', 'reports', $dataforexport, 'grades_list');
 +
Здесь:
  
[[Изображение:sample3.jpg]]
+
''im'' - тип плагина,
  
Теперь, когда у нас готов шаблон и готовы данные, мы можем посылать файл.
+
''reports'' - имя плагина,  
  
===== Отправка файла =====
+
''grades_list'' - директория, в которой лежит шаблон документа, который будет экспортирован.
В нужном файле вы создаете (например) кнопку "Экспорт в csv". А в ее обработчик вставляете такой код:
 
* '''$tp = $DOF->modlib('templater')->template('im', 'exampleim', $obj, 'sample');'''. Здесь мы создаем объект экспорта, которому указываем
 
** тип модуля, из которого надо произвести экспорт - '''im''';
 
** код модуля, из которого надо произвести экспорт - '''exampleim''';
 
** объект данных для экспорта - '''$obj''';
 
** директорию документа, который надо экспортировать - '''sample'''.
 
* '''$tp->send_file('csv');'''. Здесь мы инициализируем отправку файла клиенту, указывая в каком формате надо отправить файл.
 
Экспорт в формат odf производится аналогично.
 
  
==== Назначение классов ====
+
''$exporter'' - объект, который будет производить все необходимые операции.
* '''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 ====
+
''$dataforexport'' - собранные на предыдущем этапе данные.
*'''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 =====
+
* Получив объект, инициализируем отправку файла:
Напомним, что файл должен быть размечен тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma]. В content.xml содержится все основное содержание файла для экспорта.
+
    $exporter->send_file('odf');
 +
    die;
 +
Функция die здесь использована для того, чтобы больше ничего в файл экспорта не попало.  
  
=== Структура плагина templater ===
+
Обратите внимание, что объект $exporter уже хранит в себе все необходимые данные. Если вы хотите еще раз экспортировать данные, но уже в другой формат - не нужно заново создавать объект, достаточно обратиться к нему еще раз, например:
*templater - папка плагина;
+
    $exporter = $DOF->modlib('templater')->template('im', 'reports', $dataforexport, 'grades_list');   
**init.php - обязательный файл плагина, содержит класс dof_modlib_templater, который вызывает собственный или внешний обработчик форматирования и экспорта
+
    switch ($type)
**format.php - файл, содержащий класс dof_modlib_templater_format - содержит базовый класс для остальных классов форматирования.
+
    {
**package.php - файл, содержащий класс dof_modlib_templater_package, который вызывает собственный обработчик форматирования и экспорта
+
        case 'odf': $exporter->send_file('odf');break;
**lib.php - файл, который содержит класс placeholder. Этот класс используется для замены в шаблоне полей вставки данных самими данными.
+
        case 'csv': $exporter->send_file('csv');break;
**formats - папка, в которой лежат файлы, преобразующие данные в файл определенного типа.
+
    }
***odf - папка, содержащая все файлы, которые понадобятся для преобразования данных в один из форматов odt, ods и т.д.
+
    die;
****init.php - файл, содержащий класс dof_modlib_templater_format_'''odf''' для преобразования в конкретный формат
+
По умолчанию имя посылаемого файла формируется из собственно имени файла (которое по умолчанию равно '''export'''), и расширения, в качестве которого используется тип файла, указанный при инициализации экспорта. Но можно задать и другое имя. Для этого надо использовать второй необязательный параметр функции '''send_file''':
***csv - папка, содержащая все файлы, которые понадобятся для преобразования данных в формат csv.
+
    $options = new object;
****init.php - файл, содержащий класс dof_modlib_templater_format_'''csv''' для преобразования в конкретный формат
+
    $options->filename = 'new_export_file_name';
 +
    $exporter->send_file('odf', $options);
 +
Имя файла надо указывать без расширения.
  
=== Структура папок внешнего плагина ===
+
=== Подготовка шаблона документа ===
В плагине modlibs/templater объявляются базовые классы для работы с шаблоном и экспорта в различные форматы. В плагинах, использующих modlibs/templater хранятся шаблоны, а так же есть возможность переопределить базовые классы, для уточнения процедуры экспорта заданного документа в заданный формат.
+
Если вам нужно создать новый документ, то нужно создать и новый шаблон документа.
 +
Файл шаблона должен быть размечен тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma].
 +
В нем оформляются места для вставки данных - поля и блоки.
 +
*Отдельное поле помечается фигурными скобками '''{}'''.
 +
*Внутри скобок указывается имя поля. Например, '''{lastname}''' - поле, вместо которого должна подставляться фамилия.
 +
*Если есть блок полей, то начало блока помечается тегом '''&lsaquo;!-- BEGIN block_name --&rsaquo;'''.
 +
*Окончание блока помечается тегом '''&lsaquo;!-- END block_name --&rsaquo;'''. Здесь block_name - имя блока, все остальное - обязательная служебная конструкция. Между этими тегами нужно размещать поля блока и другие блоки.
 +
Например надо таблицу ведомости оценок (см. [[Разработка:modlibs/templater#Пример исходных данных|Пример исходных данных]])
  
Шаблоны хранятся в плагинах, использующих данную библиотеку по следующей схеме:
+
    {|border="1"
* папка плагина, использующего modlib/templater для экспорта документа
+
      |№
** templater - в этой папке хранятся все шаблоны, принадлежащие этому плагину
+
      |ФИО ученика
*** Ппака имяшаблона (например order)
+
      |оценка
**** init.php - необязательный файл, переопределяющий класс экспорта
+
      |-
**** Папка типфайла (pdf, csv)
+
      |colspan="3" |З<sup>б</sup> класс, Математика, 21.01.09
***** init.php - необязательный (для некоторых шаблонов) файл, переопределяющий класс преобразования данных в файл заданного типа;
+
      |-
**** odf - пример шаблона odf (конкретный формат odt,ods задается уже внутри шаблона, поскольку все документы устроены одинаково);
+
      |1
***** init.php (необязательно);
+
      |Замеладский Алексей
***** content - папка с распакованным документов ODF;
+
      |5
****** content.xml - xml-документ с основным контентом, размеченный тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma]
+
      |-
****** mimetype - mime-тип документа, который будет использоваться при передаче документа по http и на основании которого выбирается расширение
+
      |2
 +
      |Гусева Татьяна
 +
      |4
 +
      |-
 +
      |colspan="3" |5<sup>б</sup> класс, Русский язык, 27.01.09
 +
      |-
 +
      |1
 +
      |Коньков Сергей
 +
      |5
 +
      |-
 +
      |2
 +
      |Захаров Александр
 +
      |3
 +
      |}
  
 +
получить в виде html-файла. Тогда в шаблоне документа надо вставить поля и блоки примерно так:
 +
    <html>
 +
    ....
 +
    &lsaquo;table&rsaquo;
 +
      &lsaquo;tr&rsaquo;
 +
          &lsaquo;td&rsaquo;№&lsaquo;/td&rsaquo;
 +
          &lsaquo;td&rsaquo;ФИО ученика&lsaquo;/td&rsaquo;
 +
          &lsaquo;td&rsaquo;Оценка&lsaquo;/td&rsaquo;
 +
      &lsaquo;/tr&rsaquo;
 +
      &lsaquo;!-- BEGIN classes --&rsaquo;
 +
      &lsaquo;tr&rsaquo;
 +
          &lsaquo;td&rsaquo;{name} класс, {subject}, {date}&lsaquo;/td&rsaquo;
 +
      &lsaquo;/tr&rsaquo;
 +
      &lsaquo;!-- BEGIN students --&rsaquo;
 +
      &lsaquo;tr&rsaquo;
 +
          &lsaquo;td&rsaquo;{number}&lsaquo;/td&rsaquo;
 +
          &lsaquo;td&rsaquo;{fio}&lsaquo;/td&rsaquo;
 +
          &lsaquo;td&rsaquo;&lsaquo;grade>&lsaquo;/td>
 +
      &lsaquo;/tr&rsaquo;
 +
      &lsaquo;!-- END students --&rsaquo;
 +
      &lsaquo;!-- END classes --&rsaquo;
 +
    &lsaquo;/table&rsaquo;
 +
    ....
 +
    &lsaquo;/html&rsaquo;
  
Пример: в модуле типа '''im''', который называется '''sample''' при просмотре расписания необходимо экспортировать все уроки за месяц. Для этого структура папок im должна выглядеть следующим образом:
+
Каждый файл шаблона должен иметь имя template.тип_файла экспорта. К примеру '''template.html'''. Из этого правила есть несколько исключений. В частности, odf-формат имеет сложную структуру, поэтому и его шаблон должен быть устроен соответственно. Структура папок шаблона odf-документа описана [[Разработка:modlibs/templater#ODF|тут]]. В ряде случаев шаблон документа вообще не нужен. Так например, формат dbg - это тестовый вариант вывода данных. В этом случае неформатированные данные экспорта выводятся на экран. Другой случай - экспорт в формат '''csv'''. Файл в этом формате представляет собой набор строк, в которых данные разделены запятыми. Для него шаблон также не нужен.
  
[[Изображение:folders.jpg]]
+
=== Альтернативный способ формирования документа ===
 +
Можно изменить способ формирования документа в существующий формат. Для этого надо, в своем плагине, в папке с названием типа файла экспорта создать файл '''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
  
В каждой папке с типом экспорта может лежать файл init.php, который содержит класс, наследуемый от класса '''dof_modlib_templater''' и переопределяющий его метод '''format()'''. Именно он определяет, каким образом будет отформатирован окончательный файл. Для формата odt в папке с названием формата должна находится папка «content», содержащая следующие файлы:
+
Общий принцип формирования имен классов:
* '''content.xml''' - xml-документ с основным содержанием, размеченный тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma]
+
* Для создания нового формата ''dof_modlib_templater_format''_'''тип-файла-экспорта'''.
* '''mimetype''' - mime-тип документа, который будет использоваться при передаче документа по http и на основании которого выбирается расширение
+
* Для изменения логики работы существующего формата ''dof''_'''типплагина_имяплагина'''_''templater''_'''название-папки-документа'''_'''тип-файла-экспорта'''.
Эти файлы будут определять форматирование будущего документа. Их можно получить, распаковав обычный odt-файл (как zip-архив).
+
Таким образом, для выше приведенных примеров имена классов будут такими:
 +
* Новый класс экспорта в 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  - класс плагина DOF
+
Дальнейшее использование созданного вами формата аналогично использованию готового формата. Более подробную информацию о методах и свойствах класса ''dof_modlib_templater_format'' можно найти в разделе [[Разработка:modlibs/templater#dof_modlib_templater_format|API]].
* 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. В остальных случаях создавать собственные классы не потребуется.
+
Если работа стандартного контейнера экспорта [[Разработка: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'''.
  
[[Изображение:extending2.jpg]]
+
== 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'''.
  
==== Наследование от dof_modlib_templater_format ====
+
*'''template_path'''($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - возвращает путь внутри плагина.
Наследование от этого класса нужно производить, если вам понадобится написать экспорт в новый, еще не реализованный формат.
+
** $plugintype - тип плагина
 
 
[[Изображение:extending1.jpg]]
 
 
 
== API ==
 
 
 
=== API для использования плагина templater ===
 
Здесь описаны классы и их методы, которые необходимо использовать для того, чтобы осуществлять экспорт документов. Их достаточно для большинства задач.
 
====dof_modlib_templater:====
 
*'''template'''($plugintype, $pluginname, $templatename) — получить класс для экспорта в указанном плагине, с указанным названием. Возвращает объект класса dof_modlib_templater_packet или dof_типплагина_имяплагина_templater_кодшаблона. В дальнейшем, полученный оюъект будет производить все действия, необходимые для экспорта документов.  
 
** $plugintype - тип плагина (im, storage, modlib и т. д.)
 
 
** $pluginname - имя плагина  
 
** $pluginname - имя плагина  
** $templatename - имя шаблона форматирования
+
** $templatename - имя документа (см. предыдущую функцию)
*'''template_path'''($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - путь к шаблону (корню или внутренней папке). используется только для получения пути. Если запрошенный путь не существует - вернет false.
+
** $adds - дополнительный путь внутри плагина
**$plugintype - тип плагина (im, storage, modlib и т. д.)
+
** $fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Ее возможные значения:
**$pluginname - имя плагина
+
*** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем во внутреннем
**$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  - искать только во внешнем планине
 
*** true  - искать только во внешнем планине
 
*** false - искать только в modlib/templater
 
*** false - искать только в modlib/templater
 
+
Таблица, описывающая работу этой функции:
 
 
== Реализация функционала классов ==
 
===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 в случае ошибки.
 
*Возвращенная строка гарантированно является строкой директорией, файлом, или символической ссылкой
 
 
 
Таблица, иллюстрирующая работу этой функции:
 
 
 
 
{| 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
  
Класс шаблона документа
+
=== Внутренний ===
 +
Этот раздел понадобится вам в случае если вам будет нужно написать собственный формат или тип документа.
  
'''function __construct'''($dof,$plugintype, $pluginname, $templatename=null)
+
====dof_modlib_templater_package:====
*Делает переданные переменные свойствами класса.
+
*'''__construct'''($dof, $plugintype, $pluginname, $templatename)
*Загружает файл format.php, с обстрактным классом.
+
**$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
  
'''function set_data'''($obj) - загрузить необработанные данные в объект.
+
=== Дополнительные методы Sigma ===
*Помещает $obj в свойство класса $data;
+
*'''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.
'''private function get_data'''() - Получить необработанный объект с данными.
+
**  $id - id записи в таблице
*Возвращает свойство класса $data;
+
**  $field - поле в таблице
 
+
**  $code - имя плагина справочника
 +
*'''get_string'''($identifier, $pluginname = NULL, $a = NULL, $plugintype = 'im') - Возвращает строку перевода из файла локализации. Равносилен стандартному методу деканата '''get_string'''.
  
'''function get_file'''($type, $options=null) - получить отформатированные данные, пригодные для обработки функцией file_put_contents().
+
== Форматы экспорта ==
 +
В этом разделе будут рассмотрены все поддерживаемые плагином templater форматы экспорта.
  
*Ищем файл $type.php в папке modlib/templater/formats/.
 
**Файл есть. Проверяем наличие в нем класса dof_modlib_templater_format_$type.
 
***Класс есть. Создаем объект от него.
 
***Класса нет - возвращаем false;
 
** Файла нет. Возвращаем false.
 
*$data = $this->get_data();//получаем данные для форматирования.
 
*Превращаем данные в файл методами из dof_modlib_templater_format_$type.
 
*Возвращаем файл в виде строки.
 
  
 +
=== ODF ===
 +
Open Document Format.
 +
Этот формат используется документами [http://openoffice.ru OpenOffice]. В этом формате можно создавать как обычные текстовые документы (odt), так и электронные таблицы (ods). Для подготовки документа нужно разметить его тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma Sigma]. Создание текстового документа и электронной таблицы происходит одинаково - разница только в расширении файла: odt - для текстового документа, и ods для электронной таблицы.
  
'''function send_file'''($type, $options) инициализировать передачу файла клиенту через браузер
+
Экспорт в формат 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]]
  
'''function get_formats'''()
+
Пример реализации экспорта в '''odf''':
*сканируем папку modlibs/templater/formats и получаем список форматов, в которые мы можем экспортировать.
+
    $template = $DOF->modlib('templater')->template('im', 'reports', $data, 'grades_list');
*Если указан шаблон внешнего плагина, то сканируем папку $plugintype/$pluginname/$templatename/.Получаем список форматов.
+
    $template->send_file('odf');
*Объединяем оба списка.
+
    die;
*Для каждого типа файла проверяем наличие шаблонов для экспорта. Если шаблона нет - исключаем тип из списка форматов.
 
*Возвращаем массив с перечнем типов файлов, в которые возможен экспорт. Или пустой массив.
 
  
'''function template_path'''($adds=null) - путь к шаблону (работает через класс dof_modlib_templater).
+
=== CSV ===
 +
Comma Separated Value - значения разделенные запятыми. Файлы этого формата - это набор строк, данные в которых отделяются друг от друга специальными текстовыми разделителями. Обычно запятой, точкой с запятой или символом таблуляции.
  
=== 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();
 
  
==== dof_templater_format_odf: Список функций ====
+
Поскольку csv-файлы имеют стандартную и неизменную структуру, шаблоны для их построения не требуются. Из объекта данных формируется последовательность строк, после чего обработанные данные отсылаются клиенту:
* $tpl. Глобальная переменная - экземпляр от HTML_Template_Sigma.
+
    $template = $DOF->modlib('templater')->template('im', 'reports', $data, 'teachers_list');
* insert_content(). Эта функция вставляет переданные данные в файл и возвращает его как строку.
+
    $template->send_file('csv');
* insert_data($data). Эта функция вставляет поля и блоки из объекта данных в файл.
+
    die;
* set_block($blockname). Вставляет блок данных.
 
* set_field($name, $value). Вставляет поле.
 
  
== Структура вызова классов ==
+
По умолчанию строка заголовка вставляется в конечный файл. Но можно это отключить:
 +
    $template = $DOF->modlib('templater')->template('im', 'reports', $data, 'teachers_list');
 +
    $options = new object;
 +
    $options->title = false;
 +
    $template->send_file('csv', $options);
 +
    die;
  
[[Изображение:calls3.jpg]]
+
=== 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

Ниже представлена схема структуры папок, с пояснением, для чего какие файлы и директории нужны. 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. О том, как правильно его разметить можно прочитать в разделе Подготовка шаблона документа. Пример кода:

   $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');

Ссылки