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

Материал из DOF
Перейти к: навигация, поиск
м (Подготовка шаблона и данных: мелкая правка)
(Дополнительные методы Sigma)
 
(не показаны 134 промежуточные версии 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_format - абстрактный класс. Является родительским, для классов, реализующих преобразование данных в файл конкретного типа. Определяет минимальный обязательный набор методов для дочерних классов.
 
*dof_modlib_templater_format_odf - возвращает odf-файл как строку.
 
*dof_modlib_templater_package - стандартный обработчик экспорта. Получает необработанные данные, обрабатывает их и посылает клиенту.
 
*dof_modlib_templater - проверяет наличие у внешнего плагина своего обработчика экспорта. Если он есть, возвращает его, если нет - возвращает стандартный обработчик.
 
==== Пример работы экспорта для формата odf ====
 
*dof_modlib_templater вызывает стандартный обработчик экспорта dof_modlib_templater_package. В  будущем, планируется возможность переопределять обработчик во внешнем шаблоне, в классе dof_типплагина_имяплагина_templater_имяшаблона.
 
* _templater_package вызывает стандартный преобразователь данных в файл нужного типа (например, odf) dof_modlib_templater_format_odf. В будущем планируется возможность переопределять преобразователь данных во внешнем плагине в классе с именем dof_типплагина_имяплагина_имяшаблона_odf;
 
* _format_odf ищет шаблон оформления документа в файле типплагина/имяплагина/templater/имяшаблона/odf/content/content.xml, читает его, и размещает переданные данные как указано в этом файле.
 
* Получившийся поток данных возвращается в _templater_package, который посылает его клиенту.
 
  
===== Назначение content.xml =====
+
''$dataforexport'' - собранные на предыдущем этапе данные.
Напомним, что файл должен быть размечен тэгами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma].
 
  
=== Структура плагина templater ===
+
* Получив объект, инициализируем отправку файла:
*templater - папка плагина;
+
    $exporter->send_file('odf');
**init.php - обязательный файл плагина, содержит класс dof_modlib_templater, который вызывает собственный или внешний обработчик форматирования и экспорта
+
    die;
**format.php - файл, содержащий класс dof_modlib_templater_format - содержит базовый класс для остальных классов форматирования.
+
Функция die здесь использована для того, чтобы больше ничего в файл экспорта не попало.  
**package.php - файл, содержащий класс dof_modlib_templater_package, который вызывает собственный обработчик форматирования и экспорта
 
**lib.php - файл, который содержит класс placeholder. Этот класс используется для замены в шаблоне полей вставки данных самими данными.
 
**formats - папка, в которой лежат файлы, преобразующие данные в файл определенного типа.
 
***odf - папка, содержащая все файлы, которые понадобятся для преобразования данных в один из форматов odt, ods и т.д.
 
****init.php - файл, содержащий класс dof_modlib_templater_format_'''odf''' для преобразования в конкретный формат
 
***csv - папка, содержащая все файлы, которые понадобятся для преобразования данных в формат csv.
 
****init.php - файл, содержащий класс dof_modlib_templater_format_'''csv''' для преобразования в конкретный формат
 
  
=== Структура папок внешнего плагина ===
+
Обратите внимание, что объект $exporter уже хранит в себе все необходимые данные. Если вы хотите еще раз экспортировать данные, но уже в другой формат - не нужно заново создавать объект, достаточно обратиться к нему еще раз, например:
В плагине modlibs/templater объявляются базовые классы для работы с шаблоном и экспорта в различные форматы. В плагинах, использующих modlibs/templater хранятся шаблоны, а так же есть возможность переопределить базовые классы, для уточнения процедуры экспорта заданного документа в заданный формат.
+
    $exporter = $DOF->modlib('templater')->template('im', 'reports', $dataforexport, 'grades_list');   
 
+
    switch ($type)
Шаблоны хранятся в плагинах, использующих данную библиотеку по следующей схеме:
+
    {
* папка плагина, использующего modlib/templater для экспорта документа
+
        case 'odf': $exporter->send_file('odf');break;
** templater - в этой папке хранятся все шаблоны, принадлежащие этому плагину
+
        case 'csv': $exporter->send_file('csv');break;
*** Ппака имяшаблона (например order)
+
    }
**** init.php - необязательный файл, переопределяющий класс экспорта
+
    die;
**** Папка типфайла (pdf, csv)
+
По умолчанию имя посылаемого файла формируется из собственно имени файла (которое по умолчанию равно '''export'''), и расширения, в качестве которого используется тип файла, указанный при инициализации экспорта. Но можно задать и другое имя. Для этого надо использовать второй необязательный параметр функции '''send_file''':
***** init.php - необязательный (для некоторых шаблонов) файл, переопределяющий класс преобразования данных в файл заданного типа;
+
    $options = new object;
**** odf - пример шаблона odf (конкретный формат odt,ods задается уже внутри шаблона, поскольку все документы устроены одинаково);
+
    $options->filename = 'new_export_file_name';
***** init.php (необязательно);
+
    $exporter->send_file('odf', $options);
***** content - папка с распакованным документов ODF;
+
Имя файла надо указывать без расширения.
****** content.xml - xml-документ с основным контентом, размеченный тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma]
 
****** mimetype - mime-тип документа, который будет использоваться при передаче документа по http и на основании которого выбирается расширение
 
  
 +
=== Подготовка шаблона документа ===
 +
Если вам нужно создать новый документ, то нужно создать и новый шаблон документа.
 +
Файл шаблона должен быть размечен тегами шаблонизатора [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#Пример исходных данных|Пример исходных данных]])
  
Пример: в модуле типа '''im''', который называется '''sample''' при просмотре расписания необходимо экспортировать все уроки за месяц. Для этого структура папок im должна выглядеть следующим образом:
+
    {|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
 +
      |}
  
[[Изображение:folders.jpg]]
+
получить в виде 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;
  
Каждый синий квадрат обозначает папку, желтый — пояснение, серый — отдельный файл.
+
Каждый файл шаблона должен иметь имя template.тип_файла экспорта. К примеру '''template.html'''. Из этого правила есть несколько исключений. В частности, odf-формат имеет сложную структуру, поэтому и его шаблон должен быть устроен соответственно. Структура папок шаблона odf-документа описана [[Разработка:modlibs/templater#ODF|тут]]. В ряде случаев шаблон документа вообще не нужен. Так например, формат dbg - это тестовый вариант вывода данных. В этом случае неформатированные данные экспорта выводятся на экран. Другой случай - экспорт в формат '''csv'''. Файл в этом формате представляет собой набор строк, в которых данные разделены запятыми. Для него шаблон также не нужен.
  
В каждой папке с типом экспорта может лежать файл init.php, который содержит класс, наследуемый от класса '''dof_modlib_templater''' и переопределяющий его метод '''format()'''. Именно он определяет, каким образом будет отформатирован окончательный файл. Для формата odt в папке с названием формата должна находится папка «content», содержащая следующие файлы:
+
=== Альтернативный способ формирования документа ===
* '''content.xml''' - xml-документ с основным содержанием, размеченный тегами шаблонизатора [http://pear.php.net/package/HTML_Template_Sigma  PEAR::HTMLTemlateSigma]
+
Можно изменить способ формирования документа в существующий формат. Для этого надо, в своем плагине, в папке с названием типа файла экспорта создать файл '''init.php'''. Т.е. если мы хотим изменить формирование списка оценок в файл '''html''', то должна получиться такая структура папок
* '''mimetype''' - mime-тип документа, который будет использоваться при передаче документа по http и на основании которого выбирается расширение
+
    .../templater/reports/grades_list/html/init.php
Эти файлы будут определять форматирование будущего документа. Их можно получить, распаковав обычный odt-файл (как zip-архив).
+
    .../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  - класс плагина DOF
+
Общий принцип формирования имен классов:
* dof_modlib_templater_package - класс шаблона документа
+
* Для создания нового формата ''dof_modlib_templater_format''_'''тип-файла-экспорта'''.
** dof_типплагина_имяплагина_templater_кодшаблона - переопределенный класс шаблона данного документа
+
* Для изменения логики работы существующего формата ''dof''_'''типплагина_имяплагина'''_''templater''_'''название-папки-документа'''_'''тип-файла-экспорта'''.
** dof_im_genedu_templater_order - переопределенный класс шаблона документа order из плагина im/genedu
+
Таким образом, для выше приведенных примеров имена классов будут такими:
* dof_modlib_templater_format - базовый (абстрактный) класс формата экспорта
+
* Новый класс экспорта в excell: '''dof_moblib_templater_format_xls'''.
** dof_modlib_templater_format_формат - стандартный класс экспорта в заданный формат
+
* Альтернативный класс экспорта в '''html''': '''dof_im_reports_templater_grades_list_html'''.
*** dof_типплагина_имяплагина_templater_кодшаблона_формат - переопределенный класс экспорта заданного шаблона в заданный формат
 
** dof_modlib_templater_format_odt - стандартный класс экспорта в формат odt
 
*** dof_im_genedu_templater_order_odf - переопределенный класс экспорта шаблона order из плагина im/genedu в формат odf
 
  
==== Наследование от dof_modlib_templater_package ====
+
В плагине '''templater''' существует абстрактный базовый класс  '''dof_modlib_templater_format'''. Каждый класс, который вы создаете, должен наследоваться от него.
Эта схема показывает, каким образом нужно создавать классы для форматирования групп документов. Это может быть полезно, если вам не хватает функционала класса dof_modlib_templater_package. В остальных случаях создавать собственные классы не потребуется.
+
При создании нового формата обязательно нужно реализовать следующие методы:
 +
* '''get_file'''($options) - получить файл в виде строки. Главная функция, производящая все преобразования над данными.
 +
* '''get_filename'''($options) - получить имя файла вместе с расширением одной строкой.
 +
* '''get_mimetype'''($options) - получить MIME-тип для подстановки его в HTTP-заголовок.
  
[[Изображение:extending2.jpg]]
+
Дальнейшее использование созданного вами формата аналогично использованию готового формата. Более подробную информацию о методах и свойствах класса ''dof_modlib_templater_format'' можно найти в разделе [[Разработка:modlibs/templater#dof_modlib_templater_format|API]].
  
==== Наследование от dof_modlib_templater_format ====
+
=== Альтернативный способ экспорта ===
Наследование от этого класса нужно производить, если вам понадобится написать экспорт в новый, еще не реализованный формат.
+
Если работа стандартного контейнера экспорта [[Разработка: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'''.
  
[[Изображение:extending1.jpg]]
+
== API плагина ==
 
+
В этом разделе описаны все функции интерфейса плагина templater.
== API ==
+
=== Внешний ===
 
 
=== API для использования плагина templater ===
 
Здесь описаны классы и их методы, которые необходимо использовать для того, чтобы осуществлять экспорт документов. Их достаточно для большинства задач.
 
 
====dof_modlib_templater:====
 
====dof_modlib_templater:====
*'''template'''($plugintype, $pluginname, $templatename) — получить класс для экспорта в указанном плагине, с указанным названием. Возвращает объект класса dof_modlib_templater_packet или dof_типплагина_имяплагина_templater_кодшаблона
+
*'''template'''($plugintype, $pluginname, $data, $templatename) — возвращает класс экспорта документа из указанного плагина. Возвращает объект класса dof_modlib_templater_package или dof_тип-плагина_имя-плагина_templater_имя-документа
*'''template_path'''($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - путь к шаблону (корню или внутренней папке)
+
** $plugintype - тип плагина
**$plugintype - тип плагина (im, storage, modlib и т. д.)
+
** $pluginname - имя плагина
**$pluginname - имя плагина  
+
** $data - данные для экспорта, структурированные как указано [[Разработка:modlibs/templater#Формат исходных данных|выше]].
**$templatename - имя шаблона форматирования
+
** $templatename - имя документа; здесь указывается имя папки, в которой лежат шаблоны для формирования документа в разных форматах. В рассмотренных выше примерах это '''grages_list''', '''teachers_list''' или '''students_list'''.
**$adds - дополнительный путь после папки шаблона
 
**$fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Ее возможные значения:
 
*** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем в  
 
*** true  - искать только во внешнем планине
 
*** false - искать только в modlib/templater
 
  
=== API для разработки собственных модулей к плагину templater ===
+
*'''template_path'''($plugintype, $pluginname, $templatename,$adds=null, $fromplugin) - возвращает путь внутри плагина.
Здесь описана структура всех классов, задействованных в подготовки документа для экспорта. Если вы хотите расширить возможности плагина templater, или вам не достаточно его базового функционала, вы можете переопределить некоторые стандартные классы.
+
** $plugintype - тип плагина
 
+
** $pluginname - имя плагина  
==== Стандарт именования классов: ====
+
** $templatename - имя документа (см. предыдущую функцию)
 
+
** $adds - дополнительный путь внутри плагина
Переопределенный класс парсера всего шаблона, который ищется при наличии init.php в корне шаблона:
+
** $fromplugin - какой путь нужно вернуть: из внешнего плагина или из modlib/templater. Ее возможные значения:
'''dof_типплагина_имяплагина_templater_кодшаблона'''
+
*** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем во внутреннем
 
 
Переопределенный класс парсера шаблона для формата odf, который ищется при наличии файла init.php в шаблоне
 
'''dof_типплагина_имяплагина_templater_кодшаблона_odf'''
 
 
 
''Пример:''
 
Стандартный класс для парсера 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  - искать только во внешнем планине
 
*** true  - искать только во внешнем планине
 
*** false - искать только в modlib/templater
 
*** false - искать только в modlib/templater
 
+
Таблица, описывающая работу этой функции:
====dof_modlib_templater_format====
 
*'''__construct'''($dof,$package)
 
**$dof
 
**$package
 
*'''get_file'''($options)
 
**$options
 
*'''set_data'''($data)
 
**$data
 
*'''get_filename'''($options)
 
**$options
 
*'''get_mimetype'''($options)
 
**$options
 
*'''template_path'''($adds=null, $fromplugin) - путь к папке данного формата (работает через класс package)
 
**$adds - дополнительный путь, присоединяемый к возвращаемому функцией template_path в классе '''dof_modlib_templater_package''':
 
**$fromplugin - какой путь нужно вернуть: из внутреннего плагина или из modlib/templater. Возможные значения:
 
*** null (по умолчанию) - искать путь сначала во внешнем плагине, а затем в
 
*** true  - искать только во внешнем планине
 
*** false - искать только в modlib/templater
 
 
 
 
 
== Реализация функционала классов ==
 
===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
 
  |'''№'''
 
  |'''№'''
Строка 312: Строка 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');

Ссылки