Сервис рендеринга (генерации файлов)

Назначение - генерация файлов в формате pdf, xlsx и csv. Возможно добавление других форматов. На вход сервис получает:

1. Шаблон в формате handlebars + хелперы на js.
2. json-данные
3. Опции (не обязательно) В результате своей работы сервис формирует файл с уникальным именем (нечитаемый хэш) и кладёт его в указанную в настройках папку.

Состав репозитория

В монорепозитории присутствуют две логические единицы: собственно приложение и npm-пакет к нему.

Зависимости

Для корректной работы приложения требуется:

• REDIS. Доступ к приложению осуществляется redis при помощи пакета @skeleton/e-tasks <добавить ссылку на документацию>
• Системные библиотеки:
  • CentOS: libXrender, fontconfig, libXext
  • Ubuntu: libxrender1, fontconfig, libxext-dev Иногда (редко - был один случай на CentOS) библиотек в системе не оказывается, а без них wkhtmltopdf не может работать.

Приложение

render-worker

Модуль основанный на @skeleton-nest/e-tasks. Вся работоспособность сводится к следующему:

1. Воркер выбирает новую задачу из очереди.
2. На основе шаблона handlebars (лежат в /src/reports, сбилженные в /dist/reports/reports.json) и данных, переданных в задаче, генерирует файл.
3. Сохраняет файл на диск, результат выполнения задачи - имя файла.

Настройка и запуск.

Requirements: см. выше.

1. Клонируем репозиторий.
2. Устанавливаем зависимости:

npm install
npm run bootstrap # Как для любого монорепозитория.

Иногда модуль wkhtmltopdf долго загружается, нужно подождать.

3. Создаём конфиги при помощи @skeleton/cli:

npm run gen-config
# ВРЕМЕННО! До версии 1.7.0 @skeleton/cli Конфиги генерируются в корне репозитория.
# Их необходимо переместить в units/application.
mv .env units/renderer-worker

Глобальная установка cli больше не требуется.

4. Собираем приложение npm run build.

5. Запуск приложения

npm run start

Поддерживаемые стили при экспорте в XLSX

Строки таблицы <tr>

| Поле | Допустимые значения | Примечание | | ---------------- | :-----------------: | :-------------------------:| | height, min-height, max-height | от 1px до 100500px | При выводе на excel указанное число делится на 10. Размер может быть только один в перечисленном приоритете | | text-align | 'center', 'left', 'right', 'justify' | Настраивается только горизонтальное расположение, вертикальное всегда middle | | word-wrap | break-word | Разрешает перенос строк | | border-style| solid | Ставит в xlsx обводку всех ячеек в строке черной тонкой | | border-inheritance-type | solid | Кастомный тег, ставить, если нужно чтобы была вся строка была в обрамлении, даже с пустыми ячейками |

Столбцы таблицы <th>

| Поле | Допустимые значения | Примечание | | ----------------- | :-----------------: | :-------------------------:| | width, min-width, max-width | от 1px до 100500px | При выводе на excel указанное число делится на 10. Размер может быть только один в перечисленном приоритете | | text-align | center, left, right, justify | Настраивается только горизонтальное расположение, вертикальное всегда middle | | word-wrap | break-word | Разрешает перенос строк | | border-style| solid | Ставит в xlsx обводку всех ячеек в строке черной тонкой | | font-weight | любое | Делает текст жирным | | font-size | от 1 до N | Устанавливает размер шрифта | | colspan | от 1 до N | Мержит указанное количество ячеек начиная с текущей. Парсер пока не умеет корректно работать с смерженными ячейками. Пустые ячейки нужно указывать явно в шаблоне, иначе произойдет перезаписывание. |

Ячейки таблицы <td>

| Поле | Допустимые значения | Примечание | | ---------------- | :-----------------: | :-------------------------:| | text-align | center, left, right, justify | Настраивается только горизонтальное расположение, вертикальное всегда middle | | word-wrap | break-word | Разрешает перенос строк | | border-style| solid | Ставит в xlsx обводку всех ячеек в строке черной тонкой | | font-weight | любое | Делает текст жирным | | font-size | от 1 до N | Устанавливает размер шрифта | | colspan | от 1 до N | Мержит указанное количество ячеек начиная с текущей. Парсер пока не умеет корректно работать с смерженными ячейками. Пустые ячейки нужно указывать явно в шаблоне, иначе произойдет перезаписывание. |

Создание своего рецепта в jsreport

jsreport используется в проекте для генерации отчета из шаблонов (pug, handlebars) в html и для последующей генерации отчета из html в другие форматы (xlsx, pdf, etc). По ряду причин существующий рецепт для генерации из html в xlsx не подходит. Решено было написать свой. Находится в src/renderer-worker/recipe-html-to-xlsx.

Написание своего рецепта описано в документации тут. Для этого надо:

• Создать папку с рецептом.

Название папки не играет роли, jsreport сам сканирует папку проекта и находит все кастомные рецепты.

• Создать конфиг рецепта.

Должен находиться в корне папки в файле с названием jsreport.config.ts. Содержание файла должно быть следующим (пример на typescript):

export = {
  name: '<recipe-name>',
  dependencies: 'templates',
  main: './main.js'
}

Здесь name - имя рецепта, передается также в функцию render, по нему jsreport понимает, какой именно рецепт использовать. main - путь к скрипту с рецептом. Важно, чтобы путь был указан к транспилированному js файлу, т.к. jsreport добавляет рецепты в рантайме.

• Создать файл с рецептом.

Содержание файла должно быть следующим (пример на typescript):

export = (reporter: any, definition: any) => {
  reporter.extensionsManager.recipes.push({
    name: `<recipe-name>`,
    execute: async (request: any, response: any) => {
      // Действия по преобразованию response.content
      const result = await convert(response.content)

      response.content = result
    }
  })
}

Тут происходит добавление рецепта к существующим рецептам. name должен соответствовать названию рецепту из конфига. Функция execute должна выполнять сам код рецепта. Поле response.content содержит html в виде строки. Необходимо её преобразовать в нужный формат и перезаписать поле.

В остальном инициализация jsreportcore происходит как обычно, он сам сканирует папки проекта и ищет рецепты.

Опции генерации

При создании задачи на рендер НЕ через сервис, в объект задачи можно положить новое поле options для генерации. Например:

"options": {
 "pdfOptions": {
   "orientation": "landscape"
 }
}

orientation может быть landscape и portrait

быстрый запуск

npm install npm run bootstrap npm run gen-config mv .env units/renderer-worker npm run build npm run start