19 April 2012

Шаблоны *.docx с использованием скриптлетов Groovy

Website developmentProgrammingGroovy & Grails
image

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

Задача


Первичные требования были такими:
В сложном стилизованном документе doc или docx вывести нужную информацию в помеченных местах.

В дальнейшем они были уточнены и расширены:
  • В сложном стилизованном документе docx вывести данные в помеченных местах.
  • Разметка вывода данных должна быть похожа на скриптлеты: ${}, <%%>, <%=%>.
  • Данными для вывода могут быть объект. Нужна возможность обращения к полям.
  • Для вывода использовать один из скриптовых языков: Groovy, JavaScript.
  • Нужно иметь возможность выводить списки объектов в таблицы, в каждой ячейке отображая поля.


Имеющиеся решения


Оказалось, что имеющиеся в области продукты (я говорю про платформу Java), не решают поставленную задачу. Ниже краткий обзор продуктов:

Jasper reports

В качестве шаблона использует файл xml-разметки *.jrxml. Файл разметки документа + данные (как из БД, так и Map параметров) отдаются процессору, который формирует любой из следующих форматов: PDF, XML, HTML, CSV, XLS, RTF, TXT.
Не устроило:
  • Это не WYSIWYG, даже при наличии iReport — визуального средства формирования jrxml-файлов.
  • Надо хорошо изучить JasperReports API, чтобы создать и стилизовать сложный шаблон.
  • Не выводит в нужном формате. Можно и PDF, но хотелось бы иметь возможность потом поредактировать выходной документ.

Docx4java

Инструмент манипулирования составными частями docx-, pptx-, xlsx- документов с помощью Java-API.
Не устроило:
  • В документации к Docx4Java нет совпадающего с моими требованиями кейса. Есть краткое упоминание функции XMLUtils.unmarshallFromTemplate, который делает простейшие подстановки.
  • Обработка повторов вывода реализована через XML-исходники с использование XPath, ссылка.

Apache POI

Инструмент манипулирования составными частями doc-, ppt-, xls- документов с помощью Java-API. Изначально создан для получения данных из документов этих форматов.
Не устроило:
  • Нет решешения поставленной задачи.


Решение задачи


Это было интересно :)

1. Контент документа хранится в виде xml, сжатом в zip-архиве. Распаковка-запаковка трудна тем, что традиционный зиппер JDK 6 не поддерживает явное указание кодировки (видимо, имен файлов). Получался битый docx при архивировании. Пришлось при запаковке контента использовать Groovy-класс-обертку AntBuilder, имеющий соответствующий параметр.

2. Любой введенный в MS Word текст может быть разбит программой на кусочки и помещен в разные группы xml-тэгов.Таким образом, мне пришлось вначале решить задачу очистки шаблона от сгенерированных прокладок xml. Для этой задачи я использовал regex-выражения, мне они показались быстрее SAX-парсера (хотя производительность не мерил).

3. Я решил использовать Groovy как скриптовый язык из-за простоты, Java-природы и входящего в ядро процессора шаблонов. С ним также возникли интересные трудности. Оказалось, что даже в небольшом документе на 10 листов, можно легко нарваться на ограничение по длине строки между двумя скриптлетами. Пришлось заменять весь текст, идущий между скриптлетами на UUID-строки, прогонять процессор шаблонов Groovy, и только на выходе заменять UUID-строки на исходные кусочки XML.

Преодолев эти трудности, я опробовал проект в реальной жизни. Получилось хорошо!

Я создал англоязычный сайт проекта и опубликовал его.
Адрес проекта: snowindy.github.com/scriptlet4docx

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

HashMap<String, Object> params = new HashMap<String, Object>();
params.put("name", "John");
params.put("sirname", "Smith");

DocxTemplater docxTemplater = new DocxTemplater(new File("path_to_docx_template/template.docx"));
docxTemplater.process(new File("path_to_result_docx/result.docx"), params);


На этом можно закончить, адресуя вас на сайт проекта…
Но для улучшения понимания, переведу наиболее интересную секцию “Scriptlet types explanation”.

Типы скриптлетов, подробнее


Disclaimer: При работе с темплейтами, процессор шаблонов Groovy переводит все скриптлеты в Groovy-код, а текст между скриптлетами выводит таким образом: out.print('template_text')

${ data }

Эквивалент выводу data в out: out.print(data)

<%= data %>

Эквивалент выводу data в out: out.print(data)

<% any_code %>

Выполнение кода внутри скриптлета, ничего не выводит. Может быть использован для условного вывода:
<% if (cond) { %>
Этот текст будет вставлен, если "cond == true"
<% } else { %>
Этот текст будет вставлен, если "cond != true"
<% } %>


$[ @listVar.field ]

Это самый интересный вид скриптлетов! Он используется для вывода списков объектов в таблицу внутри docx-документа. Должен использоваться внутри ячейки таблицы.
К примеру, у нас есть список объектов Person. Объект имеет два поля: 'name' и 'address'. Мы хотим вывести список в таблице из двух колонок.

  1. Создание параметра 'personList' в карте входных значений, ссылается на список объектов.
  2. Создание таблицы с двумя колоноками и одной строкой в docx-документе.
  3. $[@person.name] надо ввести в первую ячейку; $[@person.address] — во вторую.
  4. Все готово, список personList будет распечатан в таблице.


Живой пример шаблона

Лежит здесь: ссылка.

Развитие проекта


Если я действительно изобрел новый подход к процессингу docx-шаблонов, хотелось бы популяризовать его.
Проекту есть куда стремиться:
  • Полноценное кеширование,
  • Поддержка скриптлетов в списках
  • Внедрение Streaming API


Буду рад советам в распространении проекта в англоязычной аудитории!
Tags:docxgroovytemplatescriptletscriptlet4docxскриптлетшаблоншаблонизатор
Hubs: Website development Programming Groovy & Grails
+3
10.7k 34
Comments 10
Popular right now
Тестировщик/ QA Engineer
from 50,000 ₽NatlexПетрозаводскRemote job
Java-разработчик
from 200,000 to 250,000 ₽Страховая Компания СогласиеМоскваRemote job
Business Development Manager
from 60,000 to 270,000 ₽EVEN LabМосква
Chаpter Lead разработчиков java
from 300,000 ₽Банк «Открытие»Москва
Разработчик Middle/Senior Java
from 100,000 ₽WMT GroupRemote job
Top of the last 24 hours