Шаблоны документов
===================

.. _doc_templates:

.. note::

    Доступно только в Enterprise версии.

.. contents::
	    :depth: 3

**Шаблоны документов** — инструмент для автоматической генерации файлов (docx и др.) на основе заранее подготовленных шаблонов и данных из карточек записей. Шаблон описывается в формате `Freemarker <https://freemarker.apache.org/docs/dgui_template.html>`_ и содержит переменные, которые при генерации подставляются из полей карточки согласно настроенной модели маппинга. Это позволяет автоматически формировать договоры, акты, письма и другие документы без ручного копирования данных.

Настройка расположена в журнале **"Шаблоны документов" (Раздел администратора - Трансформации)** ``v2/journals?journalId=document-templates&viewMode=table&ws=admin$workspace`` 

 .. image:: _static/doc_templates/template_01.png
       :width: 700
       :align: center 

|

 .. image:: _static/doc_templates/template_02.png
       :width: 500
       :align: center 

Необходимо заполнить следующие поля:

.. list-table::
      :widths: 5 10
      :header-rows: 1
      :class: tight-table 
      
      * - Поле
        - Описание
      * - **ID**
        - Уникальный идентификатор шаблона в системе
      * - **Имя**
        - Имя шаблона 
      * - **Движок**
        - | Наименования движка, который будет обрабатывать заполнение шаблона - **Freemarker**
      * - **Шаблоны**
        - | Загрузите файл шаблона.
          | Шаблон должен быть добавлен в zip архиве. (Так как именно так шаблоны хранятся в базе)
          | В архиве должен быть файл с шаблоном в формате docx или ftl. Строгих правил к его наименованию нет, но желательно придерживаться общей концепции и называть файл как id шаблона. 
          | Если шаблонов несколько (разделены по локализации), то при названии файлов в конце нужно приписывать суффиксы _ru, _en и т.п.
      * - **Модель**
        - | Представляет собой мапинг ключ-значение, где в качестве ключа используется атрибут из шаблона, а в качестве значения атрибут, который берется из карточки.
          | См. ниже
      * - **Вычисляемые атрибуты**
        - | Лист объектов с информацией о вычисляемых атрибутах. 
          | Подробнее тут :ref:`Вычисляемые атрибуты для шаблонов<calculated_attr>` 
      * - **Теги**
        - | Список вспомогательных меток для удобного поиска
          | Подробнее тут :ref:`Вычисляемые атрибуты для шаблонов<calculated_attr>`

Заполнение модели
-----------------

**Ключ** -  атрибут, который используется в шаблоне, **значение** -  атрибут, который берется из заполняемой карточки.

Указываются как атрибуты из самого типа данных, так и атрибуты, которые являются ассоциацией. Например:

  В типе данных **Договор** есть атрибут **Контрагент (counterparty)**. И, например, чтобы получить ИНН контрагента, необходимо указать **counterparty.inn**.

  В типе данных **Договор** есть атрибут **Юридическое лицо (legalEntity)**. И, например, чтобы получить полное наименование юридического лица, необходимо указать **legalEntity.fullOrganizationName**.

Пример заполненной модели:

 .. image:: _static/doc_templates/template_03.png
       :width: 500
       :align: center 


Заполнение шаблона документа
------------------------------

Используется `freemarker <https://freemarker.apache.org/docs/dgui_template.html>`_. 

Синтаксис его следующий:

       - **${…}** в шаблоне будет заменено в сгенерированном выводе фактическим значением выражения внутри фигурных скобок.
       - теги FTL похожи на теги HTML (но содержат # или @ ), и FreeMarker интерпретирует их.
       - комментарии в FreeMarker начинаются с **<#– и заканчиваются -->**
       - кавычки вида ``«пример»`` не распознаются. Необходимо ставить кавычки следующего вида ``"пример"``.

Например:

  -	вывод переменной:

    ``${contract}``

  -	вывод переменных с проверкой на null - если возвращаемое значение «пусто» (null) - выводится то, что указано между ``" "``.  В данном случае пустое поле, которое можно заполнить вручную позднее:  
  
    ``${counterpartyInn!""}``
  
  - конструкция «если, то .., иначе» - если Вид контрагента - ИП, то выводится ОГРНИП, если ЮЛ - то ОГРН:

    ``[#if counterpartyKind == "individualEntrepreneur"]ОГРНИП: ${psrnsp}[#else] ОГРН: ${counterpartyOgrn!""}[/#if]``

  - системный атрибут дата в формате дд.мм.гггг:

    ``date | fmt("dd.MM.yyyy")``

  - заголовок документа :ref:`системный атрибут<system_attributes>` :

    ``.disp``

.. list-table::
      :widths: 20 20
      :align: center

      * - |

            .. image:: _static/doc_templates/doc_contr_01.png
                  :width: 500
                  :align: center

        - |

            .. image:: _static/doc_templates/doc_contr_02.png
                  :width: 500
                  :align: center


Добавьте шаблон в zip архив и прикрепите его в карточку шаблона документа. См. выше.

Настройка генерации контента из шаблона
----------------------------------------

Для автоматической генерации контента из шаблона в типе данных необходимо:

    1. В тип данных добавить :ref:`аспект <aspects_user>` **Шаблонизируемый контент**

      .. image:: _static/doc_templates/data_type_aspect_01.png
            :width: 700
            :align: center 
  
    2. В конфигурации аспекта выбрать шаблон:

      .. image:: _static/doc_templates/data_type_aspect_02.png
            :width: 500
            :align: center 

Далее на форме необходимо добавить элемент **чекбокс**:

 .. image:: _static/doc_templates/form_01.png
       :width: 700
       :align: center 

В **Имя свойства** укажите **templated-content:autoGenerate**.

При заполнении полей карточки при выставленном чекбоксе по данным формы будет заполняться шаблон.

Действие сгенерировать и скачать документ
----------------------------------------- 

Далее настройте :ref:`действие<download_by_template>`

.. note::

  См. больше :ref:`о миросервисе трансформации<transformation>`

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

В модуле :ref:`Договоры<ecos-contract>` при выставленном чекбоксе **«Сгенерировать из шаблона»**: 

 .. image:: _static/doc_templates/contract_01.png
       :width: 600
       :align: center

файл-вложение будет сгенерирован по шаблону на основании введенных данных:

 .. image:: _static/doc_templates/contract_03.png
       :width: 600
       :align: center

Также файл будет доступен для предпросмотра:

 .. image:: _static/doc_templates/contract_02.png
       :width: 600
       :align: center