Разработка шаблона FreeMarker#

DCGN использует Apache FreeMarker версии 2.3.30. Apache FreeMarker – это библиотека Java для генерации текста (HTML-страницы, электронные письма, файлы конфигурации, исходный код и другое) на основе шаблонов и изменяемых данных. Шаблон представляет собой текстовый файл или HTML-файл с конструкциями Freemarker (например, $\{name\}). Шаблон может содержать списки, строковые и арифметические операции, условные выражения, циклы, макросы и другое. Шаблоны написаны на простом специализированном языке шаблонов FreeMarker (FreeMarker Template Language, FTL).

DCGN поддерживает следующие типы для передачи параметров ресурсов при генерации:

  1. InputStream. На текущий момент только при генерации через библиотеку.

  2. String.

Движок шаблона FreeMarker не поддерживает работу с ресурсами по умолчанию. Если нужно использовать изображения в шаблоне, их можно передавать в формате base64 в виде пути до файла или в виде ссылки.

Для описания картинки, которая будет встроена, необходимо:

  1. В шаблоне ftl добавить стандартный тег HTML <img ... src="${image}" ... />, где image — название параметра в конфигурационном файле шаблона, через который будет получена картинка.

  2. Установить все необходимые атрибуты (размер и т.д.).

Пример шаблона с названием параметра сimage

<html>
    <head>
        <meta charset="utf-8">
            <title>Анкета сотрудника</title>
    </head>
    <body>
        <h1>Анкета сотрудника</h1>
        <img alt="Фото сотрудника" src="${image}" width=100 height=100 align="left"/>
    </body>
</html>

В шаблонах Freemarker в функциях не рекомендуется использовать символы < или >. Заменяйте их на &lt; и &gt; соответственно.

Подробная инструкция о разработке шаблона документа для Apache FreeMarker приведена в Документации.

Ограничения для шаблона Apache FreeMarker#

Разработка шаблона в Apache FreeMarker должна производиться с соблюдением следующих ограничений:

  • не поддерживается обработка тега <!DOCTYPE>, за исключением <!DOCTYPE html>;

  • не поддерживается обработка тега <#include>;

  • не поддерживается обработка тега <#import>;

  • не поддерживается обработка тега <#stop>;

  • не поддерживаются сноски для PDF;

  • параметры внутри тега <#attempt> обрабатываются как обязательные;

  • перед тегом <#ftl> не должно быть указано дополнительных символов — BOM (Byte order mark), так как тег <#ftl> можно использовать только с первого байта документа. Подробнее о решении читайте в разделе «Рекомендации по исправлению ошибок».