poi-tl(poi-template-language)

Лучший способ создания документов Word (docx) с использованием шаблонов, основанный на Apache POI — Java API для Microsoft документов.

Что такое poi-tl

FreeMarker или Velocity генерируют новые HTML-страницы или конфигурационные файлы на основе текстовых шаблонов и данных. poi-tl — это движок шаблонов для Word, который создаёт новые документы на основе Word-шаблонов и данных.

Word-шаблон имеет богатые стили. Poi-tl идеально сохраняет стили из шаблона в создаваемых документах. Вы также можете задавать стили для тегов. Стили тегов применяются к заменённому тексту, поэтому вы можете сосредоточиться на дизайне шаблона.

poi-tl — это "безлогический" движок шаблонов. Здесь нет сложных конструкций управления и присваивания переменных, только теги, некоторые теги могут быть заменены текстом, изображениями, таблицами и т.д., некоторые теги скрывают определённые части документа, в то время как другие теги выполняют цикл по серии содержимого документа.> "Сильные" конструкции, такие как присваивание переменных или условные операторы, делают удобным изменение внешнего вида приложения внутри системы шаблонов, однако за счёт утраты разделения, шаблоны сами становятся частью логики приложения.

«Google CTemplate»poi-tl поддерживает пользовательские функции (плагины), которые могут выполняться в любом месте Word-шаблона и делать всё что угодно в любом месте документа — это цель poi-tl.## Содержание

• Maven
• Быстрый старт
• Теги
  • Текст
  • Картинка
  • Таблица
  • Нумерация
  • Разделы
    • Ложные значения или пустая коллекция
    • Неложные значения и не коллекция
    • Непустая коллекция
  • Вложенность
• Документация и примеры
• Участие
• Часто задаваемые вопросы (FAQ)## Maven

<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>poi-tl</artifactId>
  <version>1.11.0</version>
</dependency>

ВАЖНО: версия poi-tl 1.11.0 требует версии POI 5.1.0.

Быстрый старт

Начнем с простого примера: заменим {{title}} на "poi-tl template engine".

1. Создайте новый документ template.docx, содержащий текст {{title}}
2. Режим TDO: Шаблон + модель данных = выходной документ

// Основной API использует минималистичный подход, требуется всего одна строка кода
XWPFTemplate.compile("template.docx").render(new HashMap<String, Object>(){{
         put("title", "poi-tl template engine");
}}).writeToFile("out_template.docx");

Откройте документ out_template.docx, и убедитесь, что всё соответствует вашим ожиданиям.

Теги

Теги состоят из двух фигурных скобок, {{title}} — это тег, {{?title}} — тоже тег, title — имя тега, а ? указывает на тип тега. Давайте рассмотрим, какие типы тегов существуют.### Текст Тег текста — самый базовый тип тега в шаблоне Word. {{name}} будет заменен значением ключа name в модели данных. Если ключ отсутствует, тег будет удален (программа может настроить, чтобы сохранить тег или выбросить исключение).

Стиль текстового тега будет применен к замененному тексту, как показано в следующем примере.

Код:

put("name", "Mama");
put("thing", "chocolates");

Шаблон:

{{name}} всегда говорила, что жизнь похожа на коробку {{thing}}.

Выходной документ:

Mama всегда говорила, что жизнь похожа на коробку шоколадов.

Изображение

Тег изображения начинается с @, например, {{@logo}} будет искать значение ключа logo в модели данных и заменит тег изображением. Данные, соответствующие тегу изображения, могут быть простым URL или строкой пути, или структурой, содержащей ширину и высоту изображения.

Код:

put("watermelon", "assets/watermelon.png");
put("watermelon", "http://x/lemon.png");
put("lemon", Pictures.ofLocal("sob.jpeg", PictureType.JPEG).size(24, 24).create());

Шаблон:

Фруктовый логотип:
watermelon {{@watermelon}}
lemon {{@lemon}}
banana {{@banana}}

Выходной документ:

Фруктовый логотип:
watermelon 🍉
lemon 🍋
banana 🍌

Таблица

Тег таблицы начинается с #, например, {{#table}}, будет отображаться как таблица Word с N строками и N столбцами. Значение N зависит от данных тега table.

Код:

put("table", Tables.of(new String[][] {
                new String[] { "Song name", "Artist" }
            }).border(BorderStyle.DEFAULT).create());
```Шаблон:

{{#table}}

Выход:

<table>
<tr><td>Название песни</td><td>Исполнитель</td></tr>
</table>

### Нумерованные списки
Тег списка соответствует списку символов или нумерованному списку в Word, начинающемуся с `*`, например, `{{*list}}`.

Код:
```java
put("list", Numberings.create("Плагин грамматики",
                  "Поддерживает текст слова, изображения, таблицы...",
                  "Шаблон, не просто шаблон, а также стиль шаблона"));

Шаблон:

{{*list}}

Выход:

● Плагин грамматики
● Поддерживает текст слова, изображения, таблицы...
● Шаблон, не просто шаблон, а также стиль шаблона

Разделы

Раздел состоит из двух тегов перед и после, начальный тег определяется символом ?, а конечный тег — символом /, например, {{?section}} — начальный тег блока раздела, {{/section}} — конечный тег, а section — имя этого раздела.

Разделы очень полезны при обработке последовательности элементов документа. Элементы документа (текст, изображения, таблицы и т.д.), расположенные в разделе, могут быть отображены ноль, один или N раз, в зависимости от значения раздела.

Ложные значения или пустая коллекция

Если значение раздела равно null, false или пустой коллекции, все элементы документа, расположенные в разделе, не будут отображены, аналогично условию, когда условие if равно false.

Модель данных:

{
  "announce": false
}
```Шаблон:

Made it,Ma!{{?announce}}Top of the world!{{/announce}} Made it,Ma! {{?announce}} Top of the world!🎋 {{/announce}}

Выход:

Made it,Ma! Made it,Ma!

#### Не-ложные значения и не коллекция
Если значение раздела не равно `null`, `false` и не является коллекцией, все элементы документа в разделе будут **отображены один раз**, аналогично условию, когда условие `if` равно `true`.

Модель данных:
```json
{
  "person": { "name": "Sayi" }
}

Шаблон:

{{?person}}
  Привет {{name}}!
{{/person}}

Выход:

  Привет Sayi!

Модель данных:

{
  "песни": [
    { "название": "Memories" },
    { "название": "Sugar" },
    { "название": "Last Dance" }
  ]
}

Шаблон:

{{?песни}}
{{название}}
{{/песни}}

Выход:

Memories
Sugar
Last Dance

В цикле можно использовать специальный тег {{=#this}} для прямого обращения к объекту текущей итерации.

Модель данных:

{
  "производит": [
    "application/json",
    "application/xml"
  ]
}

Шаблон:

{{?производит}}
{{=#this}}
{{/производит}}

Выход:

application/json
application/xml

Вложенность

Вложенность — это объединение одного шаблона Word в другой шаблон Word, что можно понять как импорт, включение или объединение документов Word, отмеченное символом +, например {{+вложенный}}.

Код:

class AddrModel {
  String addr;
  public AddrModel(String addr) {
    this.addr = addr;
  }
}

List<AddrModel> подДанные = new ArrayList<>();
подДанные.add(new AddrModel("Hangzhou,China"));
подДанные.add(new AddrModel("Shanghai,China"));
put("вложенный", Includes.ofLocal("sub.docx").setRenderModel(подДанные).create());
```Два шаблона Word:

main.docx:

Привет, Мир {{+вложенный}}

sub.docx:

Адрес: {{адрес}}

Выход:

Привет, Мир Адрес: Hangzhou,China Адрес: Shanghai,China

## Документация и примеры

[Китайская документация](http://deepoove.com/poi-tl)

* [Основной пример](http://deepoove.com/poi-tl/#_Передоставление_документа)
* [Пример с таблицей](http://deepoove.com/poi-tl/#example-table)
* [Пример с разделами и графиками](http://deepoove.com/poi-tl/#example-animal)
* [Пример с текстовым полем](http://deepoove.com/poi-tl/#example-certificate)
* [Пример с комментариями](http://deepoove.com/poi-tl/#plugin-comment)
* [Пример: Создание резюме](http://deepoove.com/poi-tl/#example-resume)
* [Пример: Выделение кода](http://deepoove.com/poi-tl/#plugin-highlight)
* [Пример: Преобразование Markdown в Word](http://deepoove.com/poi-tl/#plugin-markdown)
* [Пример: Преобразование Swagger в Word](http://deepoove.com/poi-tl/#example-swagger)

Для получения дополнительных примеров и исходного кода всех примеров, см. JUnit тестовые случаи.

![](http://deepoove.com/poi-tl/demo.png)
![](http://deepoove.com/poi-tl/demo_result.png)

## Вклад
Вы можете присоединиться к этому проекту различными способами, не ограничиваясь следующими:

* Обратная связь по проблемам, с которыми вы столкнулись
* Поделиться радостью успеха
* Обновление и улучшение документации
* Решение и обсуждение проблем

## Часто задаваемые вопросы
См. [Часто задаваемые вопросы](http://deepoove.com/poi-tl/#_Популярные_вопросы)