Налаштування шаблонів витягів у форматах PDF, DOCX, CSV

ЗМІСТ

1. Загальний опис
2. Налаштування шаблонів витягів
3. Поширені помилки та їх усунення
- 3.1. Помилка з неправильним форматом шаблону
- 3.2. Конфлікт шрифтів
4. Пов’язані сторінки

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Загальний опис

Щоб сформувати та завантажити витяги у форматах .pdf, .docx, або .csv, необхідно попередньо налаштувати відповідні шаблони у регламенті реєстру.

Адміністратор має додати шаблон витягу та його атрибути до відповідної директорії регламенту, зокрема:

для .pdf — excerpts/excerpt-name-pdf/index.html.ftl;
для .docx — excerpts-docx/excerpt.docx;
для .csv — excerpts-csv/excerpt-csv.json.

У шаблонах витягів Платформа використовує Apache FreeMarker, але з альтернативним синтаксисом тегів. Це відрізняється від стандартного синтаксису, описаного в офіційній документації FreeMarker. Детальніше про можливості та використання цього альтернативного синтаксису див. за посиланням.

Враховуйте це при налаштуванні шаблонів, щоб уникнути помилок у їх обробці та відображенні.

Зображення 1. Структура регламенту для формування витягів у форматах PDF, DOCX та CSV

excerpts, excerpts-docx, excerpts-csv — обов’язкові назви директорій для витягів у відповідному форматі.
index.html.ftl, excerpt.docx, excerpt-csv.json — приклади назв витягів.

Назви кожної директорії та файлів мають бути унікальними навіть для різних форматів. На базі цих шаблонів формуються файли витягів у Кабінетах користувачів реєстру.

Для налаштування локалізованих витягів потрібною мовою зверніться до сторінки registry-admin/excerpts/localized-excerpts.adoc.

2. Налаштування шаблонів витягів

2.1. Налаштування шаблонів для PDF-витягів

Налаштувати шаблон PDF-витягу можна так:

Увійдіть до локального репозиторію Gerrit у вашому реєстрі.

Додайте файл шаблону index.html.ftl до директорії з унікальною назвою, наприклад, excerpts/excerpt-pdf-1.

Шаблон PDF-витягу має бути створений у форматі .html.ftl за допомогою Apache FreeMarker з альтернативним синтаксисом тегів. Це шаблонізатор, який дозволяє підставляти змінні у шаблонах PDF (.html.ftl) або .docx. Використовуйте конструкції FreeMarker для вставки змінних:

<html>
   <body>
      <h1>Витяг для [=userName]</h1>
      <p>Дата: [=currentDate]</p>
   </body>
</html>

Тут [=userName] і [=currentDate] — змінні, значення яких будуть підставлені під час генерації документа. Обов’язково враховуйте альтернативний синтаксис тегів FreeMarker, щоб уникнути помилок при обробці шаблонів.

Створіть та збережіть файл стилів style.css у директорії excerpts/excerpt-pdf-1/css.

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

<html>
  <head>
     <meta charset="UTF-8">
     <link rel="stylesheet" href="style-1.css">
     <link rel="stylesheet" href="style-2.css">
     <style>
        * { font-family: Roboto; }
     </style>
  </head>
  <body>
     <h1>Заголовок витягу</h1>
     <p>Це приклад вмісту PDF-документа.</p>
  </body>
</html>

Використовуйте кодування UTF-8. За замовчуванням шрифт має бути Roboto. Використання інших шрифтів може спричинити помилки.

Щоб вказати горизонтальну орієнтацію сторінки, налаштуйте style.css:

@page {
    size: 15in 8.5in;
    margin: 0.75in 0.9in;
}

У параметрі size зазначте широту і висоту файлу в дюймах.

Додайте зображення у форматі .png до директорії excerpts/excerpt-pdf-1/images. Використовуйте посилання на зображення у шаблоні:
```
<img src="images/image.png" alt="Опис зображення" width="300">
```
У цьому прикладі використовується зображення з папки images, яка розташована у директорії шаблону. Атрибут alt забезпечує альтернативний текст для випадків, коли зображення не відображається, а атрибут width задає ширину зображення у пікселях.

Фінальний варіант шаблону із доданим зображенням може виглядати так:

<html>
   <head>
      <meta charset="UTF-8">
      <link rel="stylesheet" href="style-1.css">
      <link rel="stylesheet" href="style-2.css">
      <style>
         * { font-family: Roboto; }
      </style>
   </head>
   <body>
      <h1>Заголовок витягу для [=userName]</h1>
      <p>Дата створення: [=currentDate]</p>
      <p>Нижче наведено зображення, яке використовується у витягу:</p>
      <img src="images/image.png" alt="Опис зображення" width="300">
      <p>Додаткова інформація про витяг може бути додана тут.</p>
   </body>
</html>

Збережіть зміни до віддаленого репозиторію Gerrit (див. детальніше на сторінці Процес розгортання регламенту в Gerrit).
Після оновлення регламенту можна буде формувати PDF-витяги у Кабінеті користувача (див. деталі на сторінці Формування PDF-витягів).

2.2. Налаштування шаблонів для DOCX-витягів

Щоб налаштувати шаблон DOCX-витягу:

Увійдіть до локального репозиторію Gerrit.
Додайте файл excerpt.docx до директорії excerpts-docx.
Збережіть зміни до віддаленого репозиторію Gerrit (див. детальніше на сторінці Процес розгортання регламенту в Gerrit).
Після оновлення регламенту можна буде формувати DOCX-витяги у Кабінеті користувача (див. деталі на сторінці Формування проєктів наказів у форматі DOCX).

Завантажте приклад витягу у форматі .docx: Приклад шаблону DOCX.

Приклад моделювання бізнес-процесів для формування CSV та DOCX-витягів доступний за посиланням: Моделювання бізнес-процесу з формування витягів у форматі csv та docx.

2.3. Налаштування шаблонів для CSV-витягів

Щоб налаштувати шаблон CSV-витягу:

Увійдіть до локального репозиторію Gerrit.

Додайте файл excerpt.json у директорію excerpts-csv.

Щоб налаштувати заголовки стовпців, створіть .json-файл із заміною назв:

{
"lastName": "Прізвище",
"firstName": "Ім'я",
"secondName": "По батькові",
"birthday": "Дата народження",
"residenceAddress": "Адреса",
"phoneNumber": "Телефон",
"gender": "Стать"
}

Ключі у лівому стовпці відповідають назвам параметрів у системі, а значення у правому стовпці — новим назвам, які будуть відображені у витягу.

Збережіть зміни до віддаленого репозиторію Gerrit (див. детальніше на сторінці Процес розгортання регламенту в Gerrit).
Після оновлення регламенту можна буде формувати CSV-витяги у Кабінеті користувача (див. деталі на сторінці Формування витягів-звітів у форматі CSV).