¶ Генерация документов в ozma.io
Генератор документов в ozma.io позволяет собирать договора, отчеты, накладные, наклейки для продукции и любые другие документы, использующие данные из системы.
Генератор документов сейчас на раннем этапе развития, так что возможны баги. При обнаружении странного поведения - пишите нам в телеграм
¶ Работа с генератором документов
Администратор решения:
- реализует шаблон документа
- загружает шаблон в систему в odt
- настраивает в системе кнопку для генерации документа
Пользователь решения:
- нажимает на кнопку генерации документа
- получает сгенерированный документ в выбранном формате (
.pdf,.html,.txt)
¶ Создание шаблона документа
Для генерации документа необходим шаблон документа, который после обработки превратится в .pdf, .html, .txt документы.
Шаблон представляет из себя произвольный текстовый документ формата .odt. Шаблон содержит разметку, позволяющую включать и исключать области документа, вставлять результаты произвольных запросов на языке FunQL в виде
- одиночных полей
- таблиц
- кодов (штрихкодов и QR-кодов).
Шаблон состоит из 2-х блоков:
- Тело документа
{{FieldName}}подставлены вместо конкретных значений
- Блока с именованными или анонимными запросами.
- Именованный:
<query>{$id reference(base.people)}SELECT name FROM base.people WHERE id = $id</query> - Анонимный (как на скриншоте):
<query>/views/schema/userview_name</query>
- Именованный:
¶ Поля одной записи
Если запрос возвращает одну запись - используйте в запросе значение type="SingleRow
<query name="Operation" type="SingleRow">/views/schema/userview</query>
Пример:
https://acmeinc.ozma.org/views/reports/operation_info?id=11Запрос
<query name="Operation" type="SingleRow">/views/reports/operation_info</query>возвращает 6 колонок для одной записи Операции:
id,op_datetime,from_storage,to_storage,lines_count,barcodeТеперь в любом месте тела отчета можно использовать
{{Operation.id}},{{Operation.op_datetime}}и т.п. для вставки данных об этой операции в конкретное место документа.
¶ Таблица
Если нужно отобразить таблицу - используйте в запросе type="ManyRows"
<query name="ProductsList" type="ManyRows">/views/schema/userview</query>
В теле документа используйте конструкцию
{% for product in ProductsList %}
Любой контент с использованием {{product.id}} или например, {{product.name}}
{% endfor %}
Пример:
https://acmeinc.ozma.org/views/reports/products_in_operation?id=3
Запрос<query name="Products" type="ManyRows">/views/reports/products_in_operation</query>возвращает 4 колонок для четырех Продуктов:
article,name,base_count,base_unitТеперь можно отрисовать в отчете таблицу с данными о четырех продуктах вот так:
Артикул Наименование Количество Единица {% for product in Products %}{{product.article}}{{product.name}}{{product.base_count}}{{product.base_unit}}{% endfor %}
¶ QR-коды и штрихкоды
В отчеты можно встраивать штрихкоды (поддерживаемые форматы - itf-14, ean-13, code-39) и QR-коды.
В самом шаблоне документа для их использования ничего не нужно.
Для того, чтобы генератор отобразил что-то как штрихкод необходимо добавить два атрибута в представления, из которых генератор будет брать данные:
SELECT
products.id as qrcode @{
control = 'qrcode',
image_height = 100
},
products.id as barcode @{
control = 'itf-14',
image_height = 100
},
FROM
production.products
control- указывает тип генерируемого штрихкодаimage_height- задает высоту генерируемого штрихкода
¶ Администрирование
Администрирование шаблонов для конкретного решения осуществляется через админку генератора по адресу:
https://report-generator.ozma.io/admin/{instance-name}
Для работы с админкой необходимы права администратора инстанса (users.is_root = true)
- Загружаемый файл шаблона должен иметь формат
.odt - У каждого шаблона должна быть схема
- Не допускаются одинаковые названия шаблонов в рамках одной схемы
- Во всех названиях (инстанса, схемы, шаблонов) не допускается использование двойных подчеркиваний ("__"), пробелов, слэшей ("/")
¶ Генерация отчетов из системы
Cсылка для генерации документа по шаблону fin.invoice для транзакции с id=501 будет выглядеть так:
https://report-generator.ozma.io/api/instance-name/fin/invoice/generate/My-invoice-501.pdf?id=501
Чтобы по нажатию на кнопку в системе пользователь получил готовый PDF файл - добавьте информацию для генератора на кнопку.
Формат данных для генерации:
{
document_template: {
schema: string,
name: string
},
filename?: string,
args?: object
}
document_template- содержит информацию о схеме и названии шаблона документаfilename- имя готового сгенерированного документа. Можно указать имя вместе с расширением (например,my-document.odt), если расширение не указано - по умолчаниюpdfargs- аргументы, передаваемые в генератор
Пример:
{
$type enum('products', 'details', 'materials', 'all')
}:
SELECT
@type = 'table',
@title = 'Справочник товаров',
@row_link = &production.good_form,
goods.attribute @{ column_width = 125 },
goods.name @{ column_width = 375 },
goods.base_unit @{ column_width = 150 },
goods.notes @{ column_width = 450 },
[{
name: 'Наклейки', icon: 'qr_code_2',
document_template: {
schema: 'storage',
name: 'product10',
},
filename: goods.attribute || '-stickers',
args: {
id: goods.id
},
}] as buttons @{
column_type = 'buttons',
cell_color = '#F4F4F4',
column_width = 130,
caption = 'Печать'
},
FROM
production.goods
ORDER BY
goods.name
Пример: https://acmeinc.ozma.org/views/production/goods_table_all?type="all"
¶ F.A.Q.
Если вы получили 500-ую ошибку при генерации, проверьте
- При использовании именованных юзервью в
<query>- что юзервью существуют и не сломаны - При использовании анонимных юзервью в
<query>- что запрос возвращает данные - Имена полей в шаблоне совпадают с именами полей, которые возвращаются запросом
- При использовании штрихкодов - данные, для которых генерируется штрихкод, соответствуют требованиям для генерации кода именно этого типа
Если есть уверенность, что все в шаблоне верно, а генератор все равно возвращает 500 - попробуйте в удалить все элементы в фигурных скобках {{element.id}} и написать их еще раз вручную (не используя copy-paste). И загрузить новый шаблон в систему.