Руководство по созданию и настройке шаблонов

Firok Fax использует движок шаблонизации Docxtemplater, позволяющий подставлять значения из формы прямо в исходный файл Microsoft Word (.docx).

---

1. Подготовка файла Word (.docx)

Создайте обычный документ Microsoft Word (.docx) со всеми стилями, таблицами, шрифтами и колонтитулами. В местах, куда должны вставляться данные, используйте специальные теги в фигурных скобках {...}.

Основные типы тегов в Word:

1. Простая подстановка значения:

   Niniejsza umowa zawarta w dniu {data_dzis} pomiędzy:
   {firma_nazwa}, z siedzibą w: {firma_adres}, NIP: {firma_nip}

2. Многострочный текст с сохранением переносов строк: Если в поле формы введён текст с абзацами, тег {zlecenie_pl} автоматически сохранит переносы строк.

3. Условные блоки (if / else):

   {#has_bonus}
   Pracownikowi przysługuje premia uznaniowa.
   {/has_bonus}

4. Списки и таблицы (циклы): Для списков строк (string-list) или списков объектов (object-list):

   {#elementy}
   - {nazwa}: {cena} PLN
   {/elementy}

   В таблицах Word: поместите {#elementy} в первую ячейку строки таблицы, а {/elementy} — в последнюю ячейку той же строки. Docxtemplater автоматически размножит строки таблицы для каждого элемента.

---

2. Размещение файлов в папке content

Каждый шаблон состоит из двух частей:

1. Файл Word (.docx) — помещается в папку content/templates/ (например, content/templates/umowa-zlecenie.docx).
2. Файл конфигурации (.json) — создается в визуальном редакторе приложения либо вручную в content/documents/ (например, content/documents/umowa-zlecenie.json).

💡 Совет: Вы можете открыть папку шаблонов прямо из приложения: на странице редактирования шаблона нажмите на иконку папки рядом с полем «Plik DOCX».

---

3. Визуальный редактор шаблонов в приложении

Чтобы создать шаблон в приложении, нажмите «+ Nowy szablon» в верхней панели:

Основные параметры шаблона:

• ID: уникальный системный идентификатор (только латиница, цифры, дефис и подчеркивание, например umowa-o-prace).
• Nazwa (Title): отображаемое название (например, Umowa o pracę).
• Opis (Description): краткое описание назначения документа.
• Plik DOCX (Template): имя файла DOCX из папки content/templates/ (например, umowa-o-prace.docx).
• Nazwa wyniku (Output Name): шаблон имени итогового файла. Можно использовать теги полей в фигурных скобках, например: Umowa-o-prace-{pracownik_nazwisko}-{data_dzis}.docx

---

4. Настройка полей формы (Form Fields)

Для каждого тега из вашего Word-документа добавьте соответствующее поле:

Тип поля (type)	Назначение	Пример использования
Tekst (string)	Однострочный текст	ФИО, номер паспорта, NIP, город
Tekst wieloliniowy (textarea)	Многострочный блок текста	Предмет договора, перечень обязанностей
Liczba (number)	Числовые значения	Ставка, количество часов, сумма
Data (date)	Выбор даты через календарь	Дата заключения, срок действия
Tak / nie (boolean)	Чекбокс (логическое условие)	Признак наличия приложений, выплата премии
Lista tekstów (string-list)	Список строк (по строке на строку)	Список обязательств, перечень документов
Lista obiektów (object-list)	Табличные данные со своими подполями	Список товаров/услуг, перечень этапов работ

Дополнительные опции поля:

• Klucz (Key): точное имя тега из Word-документа (без скобок {}).
• Etykieta (Label): понятное название для пользователя (например, «Data zawarcia umowy»).
• Pole wymagane (Required): если включено, документ нельзя будет сгенерировать без заполнения этого поля.
• Wyliczaj ze słowami (Computed): настройка автоматического перевода суммы в слова (см. подробное руководство).