Note
Доступно только в Enterprise версии.
Опциональный Ecos-микросервис ecos-transformations для генерации документов по шаблонам, которые можно подгрузить с проектом или добавить через инструменты администратора.
Contents
- Подключение микросервиса
- Создание нового шаблона
- Вычисляемые атрибуты для шаблонов
- Действие сгенерировать и скачать документ
- Импорт/экспорт шаблонов
- Автоматическая генерация контента из шаблона
- Синтаксис условных операторов
- Параметры работы с документом во встроенном редакторе OnlyOffice
- Временное решение ошибки при генерации шаблона с условиями
Микросервис Трансформации (ecos-transformations) - самостоятельный микросервис, не требующих развертывания дополнительных баз данных (все шаблоны хранятся в бд ecos-model). Для обеспечения работоспособности необходимы:
- ecos-model:2.13.0
#=== TRANSFORMATIONS ===#
transformations-app-dev:
container_name: transformations-app-dev
image: nexus.citeck.ru/ecos-transformations:1.0.0
ports:
- 8087:8087
environment:
- _JAVA_OPTIONS=-Xmx256m -Xms256m
- SPRING_PROFILES_ACTIVE=dev,swagger
- ECOS_INTEGRATIONS_ONLYOFFICE_HOST=only-office-app
- ECOS_WEBAPP_RABBITMQ_HOST=rabbitmq-dev
- EUREKA_CLIENT_SERVICE_URL_DEFAULTZONE=http://admin:$${jhipster.registry.password}@ecos-registry:8761/eureka
- SPRING_CLOUD_CONFIG_URI=http://admin:$${jhipster.registry.password}@ecos-registry:8761/config
- ECOS_INIT_DELAY=0
depends_on:
- ecos-registry
Для работы с новыми шаблонами документов в Ecos есть журнал "Шаблоны документов", расположеный он в меню Инструменты в разделе Трансформации:
Существует 2 способа создавать шаблоны документов в системе:
- Располагая их в проекте в определенной директории.
- Загрузив их через действие Добавить в журнале Шаблоны документов.
Для успешного добавления в систему вашего шаблона необходимо учитывать некоторые вещи:
Вместе с самим шаблонов должен храниться файл
meta.yml, который будет хранить метоинформацию о шаблоне.Особенность наименования файлов:
Если файл шаблона один, то мета-файл называется по шаблону
${Полное_имя_файла_с_расширением}.meta.ymlПример:
Если файлов шаблона несколько в результате разделения их по локализации, то мета-файл именуется по следующему шаблону
&{Имя_файла_до_указания_локали}.meta.ymlПример:
Структура мета-файла
Мета-файл должен содержать следующие поля в своей структуре:
Поле
Описание
id
Уникальный идентификатор шаблона в системеid: test-template
engine
Наименования движка, который будет обрабатывать заполнение шаблона(На данный момент существует толькоfreemarker)engine: freemarker
name
Имя шаблонаname: TestTemplate
mimeType
Тип файла шаблонаmimeType: application/vnd.openxmlformats-officedocument.wordprocessingml.document
model
Представляет собой мапу ключ-значение, где в качестве ключа используется атрибут из шаблона, а в качестве значения атрибут, который возмется из карточки.model: regNumber: idocs:registrationNumber regDate: idocs:registrationDate|fmt('dd.MM.yyyy') initiator: idocs:initiator.cm:firstNameВ значениях можно использовать все возможности обращения с атрибутами через :ref:`Records API<Records_API>`computedAttributes
Вычисляемые атрибуты модели.Задается списком атрибутов.Перед генерацией шаблона преобразует полученные атрибуты в моделе согласно типу преобразования.computedAttributes: - id: docInvestigationInfo type: html-to-texttags
Список вспомогательных меток где удобного поискаtags: - Template - Test - Example
Пример:
--- id: test-docx-template engine: freemarker name: TestDocxTemplate mimeType: application/vnd.openxmlformats-officedocument.wordprocessingml.document model: modelValue: ?disp
Файлы должны располагаться в проекте по определенному пути.
Путь для расположения файлов имеет следующий паттерн:
В МКР:
${home_dir}/src/main/resources/eapps/artifacts/transformation/template/В проектах:
${module_name}/src/main/resources/alfresco/module/${module_name}/transformation/template/В данных директориях вы можете создавать создавать внутреннюю структуру папок. Поиск артифактов шаблонов происходит рекурсивно по папкам, но начинается именно с этих директорий.
Для создания шаблона документа через журнал необходимо зайти в Инструменты в левом меню, затем в справа в разделе Трансформации выбрать журнал Шаблоны документов и создать новую запись.
Необходимо заполнить следующие поля:
| Поле | Описание |
|---|---|
| ID | Уникальный идентификатор шаблона в системе |
| Имя | Имя шаблона |
| Движок | Наименования движка, который будет обрабатывать заполнение шаблона
(На данный момент существует только Freemarker)
|
| Шаблоны | Загружается файл шаблона
Шаблон должен быть добавлен в zip архиве. (Так как именно так шаблоны хранятся в базе. пока так…)
В архиве должен быть файл с шаблоном в формате docx или ftl. Строгих правил к его наименованию нет, но желательно придерживаться общей концепции и называть файл как id шаблона.
Если шаблонов несколько (разделены по локализации), то при названии файлов в конце нужно приписывать суффиксы _ru, _en и т.п.
|
| Модель | Представляет собой мапу ключ-значение, где в качестве ключа используется атрибут из шаблона, а в качестве значения атрибут, который возмется из карточки. |
| Вычисляемые атрибуты | Лист объектов с информацией о вычисляемых атрибутах.
|
| Теги | Список вспомогательных меток для удобного поиска
|
Вычисляемые атрибуты в метафайле шаблона предназначены для тоже, чтобы совершить какую-то постобработку над значениями, которые пришли в модели, и обновить эти значения в модели или добавить под новыми именами.
Структура записи:
Указания вычисляемых атрибутов начинается с указания ключевого атрибута computedAttributes в корневой страктуре метафайла, содержащего в себе список объектов следующего вида:
| Поле | Описание |
|---|---|
| ID | Уникальный идентификатор атрибута. Именно с этим значением атрибут попадет в итоговую модель.
Если в модели есть аттрибут с таким именем, то значение в модели обновится.
|
| type | Указания типа преобразования значения. |
| config | Представляет собой мапу ключ-значение, из дополнительных параметров конфигурации и их значений.
config: attribute: test1 Имеет общий параметр для всех видов -
attribute. Данный параметр в качетве значения принимает имя атрибута, значение которого возмется для преобразования.Если данный параметр не задан, то из модели возметря значение атрибута с именем из поля id вычисляемого атрибута.
|
Пример:
model:
test1: ecos:text1
test2: ecos:text2
computedAttributes:
- id: test3
type: html-to-text
config:
attribute: test1
- id: test2
type: html-to-text
| Тип | Описание |
|---|---|
| html-to-text | Преобразует входной текст из HTML кода в текст, убирая из него лишние теги (такие как <p>, <br>, <li>). |
В системе предусмотрено действие, позволяющее на основе карточки, сгенерировать документ из шаблона документов и сразу его скачать. Для это необходимо в системе создать новое действие (Подробнее о действиях тут: :ref:`Действия<ui_actions>`) с типом download-by-template.
Для работы действия необходимо заполнить следующие атрибуты в конфиге действия:
| Атрибут | Значение |
|---|---|
| resultName | Имя итогового документа.
resultName: 'test-docx.docx' Если данный атрибут будет отсутствовать, то возьмется имя документа шаблона.
|
| templateRef | Ссылка на вызываемый шаблон
templateRef: 'transformations/template@test-template'
|
Принцип работы:
Вызывая действие из меню действий карточки система сделает запрос к шаблону, достанет модель из шаблона, заполнит ее соответствующими значениями и отправит все данные в микросервис транснформации, где на основе модели и шаблона сгенерируется документ и вернется обратно на UI, где просто скачается.
Особенность: Если используются зашифрованные поля (зашифрованы в БД и расшифровываются непосредственно у пользователя), то такие поля передадутся в расшифрованном виде и в сгенерированном документе они будут корректно отображаться.
Примеры действий:
--- id: download-by-test-template type: download-by-template config: templateRef: 'transformations/template@test-template''
--- id: download-by-test-docx-template type: download-by-template name: ru: Скачать DOCX шаблон en: Download DOCX template config: templateRef: 'transformations/template@test-docx-template' resultName: 'test-docx.docx''
Импорт и экспорт шаблонов помогает легко и просто переносить шаблоны документов между стендами. Мы скачиваем необходимые нам шаблоны на одном стенде и импортируем их на другом без особой нагрузки. Также можно сгенерировать архив с шаблоном самому, и импортировать нужный шаблон на стенд в одно несложное действие.
При импорте/экспорте будет осуществляться работа с zip-архивом, который содержит метоинформацию шаблона и непосредственно сам шаблон документа:
Импорт шаблонов осуществляется через вариант создания шаблона Импортировать шаблон документа в журнале Шаблон документов:
Для импорта необходимо приложить zip-архив с файлами:
- Файл с метаданными от шаблона. Имя файла должно быть сформировано по принципу: Имя_файла.meta.yml
- Непосредственно сам шаблон (или шаблоны с разной локализацией).
Important
Именно такой архив формируется при экспорте шаблона
Экспорт осуществляется с помощью действия Скачать при наведении на необходимый нам шаблон документа.
После нажатия на действие будет осуществляться скачивание zip-архива с шаблоном и его метаданными.
Для автоматической генерации контента из шаблона при создании рекорда необходимо:
- В тип данных добавить :ref:`аспект <aspects_user>`
templated-content- В конфигурации аспекта выбрать шаблон:
Note
Если при создании рекорда включен аспект templated-content, но автоматическую генерацию нужно выключить, то можно выставить атрибут templated-content:autoGenerate в false.
При создании рекорда автоматическая генерация выполняется синхронно, результат будет записан в атрибут _content.
Сгенерированный контент будет доступен для скачивания, предпросмотра и сравнения версий.
В микросервис трансформации перенесена логика из класса DocxFreeMarkerProcessor из проекта ecos-community-core. Расположена в классе DocxFreemarkerTemplateService.
Необходимо обратить внимание на описание сервиса, а именно на синтаксис условных операторов:
Выражения, которые содержат открывающий и закрывающий теги, необходимо оборачивать в теги группировки [# #] :
В действии, в url, через "&config=JSON" необходимо прописать конфиг, предварительно сгенерировав его в encodeURIComponent прямо в браузере:
В данном примере мы разрешаем пользователю редактировать только определённые поля, и при этом убираем возможность скачать файл.
Варианты конфигурации редактора описаны в официальной документации
Для создания документа с редактируемыми полями необходимо исходный .docx файл локально открыть в редакторе OnlyOffice и сохранить в формате .docxf
Открыть уже в этом формате, и с помощью вкладки Формы → Текстовое поле, разметить необходимые поля.
При этом нужно убедиться, что "Заполнитель" и "Значение по умолчанию" пустые (для избежание проблем вёрстки и изменения цвета текста после генерации по шаблону)
Отметив необходимые поля, необходимо снова сохранить документ в формате .docx, открыть в Word, заполнить необходимыми тегами и сохранить:
Далее опять открыть с помощью OnlyOffice и через вкладку Защита→ Защитить документ:
Указать пароль и "Заполнение форм":
В итоге получаем готовый .docx файл, который перед тем как загружать в систему, следует поправить, пользуясь статьей :ref:`Временное решение ошибки при генерации шаблона с условиями<temporary_solution>`
При генерации документа из шаблона документа, в котором есть условие (т.е. if, else или elseif), возникает ошибка.
так как файл document.xml дробит условие на множество тегов:
Work around для решения проблемы:
Открыть docx как архив.
В папке word открыть файл document.xml
Найти условие, разбитое на теги:
Собрать в один тег:
Сохранить. Загрузить
