Дерево страниц
Перейти к концу метаданных
Переход к началу метаданных

О плагине

Плагин предназначен для генерации и учёта печатных форм документов. Понятие "документ" здесь трактуется достаточно широко: так это может быть и HTML отчёт, генерируемый из очереди процессов.

Механизм работы

Схематично принцип работы плагина изображён ниже. Синим цветом выделены блоки с использованием устаревшей XSLT технологии. Она поддержана в режиме обратной совместимости.

Однако все XSLT шаблоны рекомендуется в ближайшем будущем заменить на JSP.

Причины, по которой технология шаблонов была заменена:

  • унификация, JSP уже массово используется в системе;
  • производительность и ресурсоёмкость у JSP шаблонов существенно ниже;
  • затруднённый доступ к Java API из XSLT, фактически необходимость создания каждый раз XML оболочек для существующих Java методов.

Пояснения по схеме выше. Изначально на вход шаблонизатора подаётся одно либо набор событий с идентификаторами объектов, для которых следует сгенерироват документ и требуемом шаблоне. Идентификатор объекта - это код контрагента, процесса и т.п. Одно событие - генерация документа непосредственно для объекта, блок событий - генерация, например, из очереди процессов.

Есть некоторая разница в генерации событий в зависимости от результирующего формата. При генерации HTML документа из многих объектов генерируется одно событие, т.к. HTML подразумевает единый корень документа. При генерации PDF генерируются несколько событий и результаты склеиваются. Генерация ODT/DOCX и прочих форматов для нескольких объектов невозможна.

При использовании устаревшей XSLT (type=xsltHtml) генерации HTML фрагменты с результатами для отдельных объектов также склеиваются. В результате получить целостное HTML дерево с его помощью невозможно. Однако, большинство современных браузеров всё-таки отображают такой результат корректно.

С системой поставляется набор примеров генерации различных видов документов. Примеры JSP файлов с инструкциями по их настройке в комментариях расположены в каталоге webapps/WEB-INF/jspf/user/plugin/document/template/example.

Дополнительные примеры могут быть найдены в WiKi.

Конфигурация

Для добавления генератора документа в конфигурации указывается запись вида:

Где:

  • <id> - уникальный числовой идентификатор типа документа;
  • <title> - отображаемое наименование шаблона, необходимо только для шаблонов, которые можно выбрать;
  • <scope> - тип сущности, для которой генерируется документ, см. далее;
  • <type> - тип генерируемого документа, описание типом см. далее;
  • <jsp> - путь к JSP шаблону, генерирующему HTML, либо подготавливающему данные для шаблонов;
  • <result> - допустимые значения через запятую: stream - не сохранять сгенерированный документ и сразу выдать его клиенту, save - сохранить документ;
  • <doc_title> - имя создаваемого документа;
  • <file> - имя файла со шаблоном документа (PDF форма либо иной исходный документ для подстановки параметров) рекомендуется располагать в каталоге BGCRM/docpattern;
  • <title_pattern> - REGEXP шаблон имени сущности, для которой будет предлагаться к генерации данный тип документа;
  • <additional_params_jsp> - JSP файл с дополнительными параметрами для генерации документа;
  • <file> - исходный документ, заполняемый данными;
  • <flattening> - 1, для типа pdfForm, если сгенерированный PDF документ следует сделать нередактируемым.

Возможные значения параметра <scope>, для генерации документов объектов ядра:

Также интеграцию с Document поддерживают следующие плагины, для них возможны свои значения параметра <scope>:

Поддерживаемые типы (параметр <type>):

  • pdfForm - PDF форма, исходная форма получается из параметра <file>, поля формы заполняются из XML документа с параметрами, подготовленного с помощью JSP шаблона <jsp>;
  • docxForm либо odtForm - .docx либо .odt файл с макросами вида ${macros}, значения которых заменяются значениями из XML документа с параметрами, подготовленного с помощью JSP шаблона <jsp>;
  • jspHtml - преобразование исходных данных в HTML с помощью JSP шаблона <jsp>;
  • xsltHtml - (устарело) преобразование исходных XML данных в HTML документ с помощью XSLT шаблона <xslt>.

PDF формы можно подготовить с помощью Adobe Acrobat, Master PDF Editor или аналогичной программы.

При использовании типов docxForm либо odtForm производится замена в текстовых файлах word/document.xml и content.xml макросов на значения.

Файлы эти расположены внутри архивов, коими по сути являются файлы этих двух форматов. Для проверки корректности макросов можно переименовать .docx либо .odt файл в .zip, открыть архиватором и просмотреть указанные ранее файлы. Важно проконтролировать, чтобы макросы шли сплошными блоками и находились поиском в текстовом редакторе.

Возможны, например, такие варианты форматирования, макрос в этом случае корректно заменён не будет:

В этом случае макрос следует забить повторно и пересохранить документ, добившись примерно такого варианта:

Пример настройки генерации HTML документа из карточки процесса (взят из примеров webapps/WEB-INF/jspf/user/plugin/document/template/example).

При использовании не HTML результирующего формата вывод JSP шаблона используется только в режиме отладки (см. далее). Для заполнения полей в JSP шаблон передаётся объект field, методом set которого можно установить значения именованных параметров.

Установленные промежуточные данные возможно просмотреть в режиме отладки. Режим отладки запускается при генерации документа с зажатой клавишей Alt в режиме без сохранения на диск. Отладка выводится в отдельном окне.

Режим отладки имеет смысл для типов шаблонов, где результирующим документом выступает не HTML. Он предоставляет возможность изучить вывод JSP шаблона с отладочной информацией  и подготовленные им поля. Для шаблонов, генерирующих HTML отладка возможна сразу в результирующий документ.

Плагин документов может быть использован для генерации отчётов в очереди процессов. Для запуска режима отладки в этом случае клавиша Alt должна быть зажата в момент выбора пункта обработчика в меню Ещё.

Интерфейс пользователя

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

В выпадающем списке выводятся настроенные для данного типа сущности шаблоны документов. Далее кнопки генерации документа с сохранением и без (настраиваются с помощью result параметра в конфигурации шаблона). Кнопка +? позволяет загружать произвольные файлы.

При удержании нажатой клавиши Alt в момент генерации документа без сохранения запускается режим отладки.

Примеры и документация к устаревшей XSLT технологии

Раздел будет удалён вскорости. Необходим лишь для возможности изучения логики работы устаревшей технологии и адаптации шаблонов.

Пример 1. Шаблон документа бланка заказа единого договора.

Пример 2. Шаблон для генерации печатной формы в очереди процессов.

Пример 3. Шаблон для генерации печатной формы акта в договоре BGBilling, используются доп. параметры и отличный от CommonDocumentGenerator обработчик-генератор документа.

Исходные данные преобразуются с помощью XSLT преобразования. На вход XSLT генератора подаётся XML документ следующего содержания.

Где:

  • <objectId> - код объекта для которого генерируется документ;
  • <objectType> - тип объекта;
  • <paramNameX> и <valueX> - параметры HTTP запроса, переданные на генерацию документа, благодаря этим данным возможен параметризированный вызов генерации документа из внешних систем.

Для просмотра хода генерации включите вывод в лог отладочной информации. Работу можно начать с подобного шаблона, который просто выводит в результирующий документ (а следовательно и в лог) исходный XML.

Получение дополнительной информации осуществляется с помощью функций-расширений. Результат вызова функции-расширения можно вывести в отладку с помощью инструкции <xsl:copy-of>.

При генерации для типа xsltHtml исходный документ преобразуется сразу в HTML.

Для типов *Form в результате преобразования для генерации шаблона подготавливается документ XML следующего вида со значениями параметров.

Далее параметры подставляются в поля PDF формы либо заменяют макросы документа, указанного в параметре file.

В составе ядра представлены перечисленные далее пространства имён и функции в них. Список может дополняться в плагинах.

Примеры XSLT шаблонов для генерации документов доступны в WiKi.

Расширения пространства имён "http://bgcrm.ru/saxon-extension-math"

isbitset( <value>, <bitNumber> ) - возвращает результат проверки установленности в значении <value> бита <bitNumber>, нумерация с 0 от конца двоичного представления числа.

Пример:

Расширения пространства имён "http://bgcrm.ru/saxon-extension"

customer( <id> ) - получение XML документа с данными контрагента с кодом <id>.

Пример:

process( <id> ) - получение XML документа с данными о процесе с кодом <id>.

Возвращается XML примерно следующего вида:

Пример использования:

user( <id> ) - получение XML документа с данными о пользователе с кодом <id>.

Пример использования:

param( <objectId>, <paramId> ) - получение XML документа с данными о параметре <paramId> объекта с кодом <objectId>.

 

  • Нет меток
Документация BGCRM 3.0