limebeck/template-editor repository overview

⁠Редактор шаблонов

⁠Описание

Инструмент для тестирования и разработки шаблонов в формате Fanzilla Template Service.

Основан на шаблонизаторе Apache FreeMarker (ссылка на документацию: https://freemarker.apache.org/docs/index.html⁠), с добавлением собственного формата описания ресурсов шаблона и упаковки (Template Meta File), а также с расширенным функционалом, задействованным в сервисе.

Позволяет генерировать PDF таким, как он будет получен после заливки шаблона на сервер.

⁠Важно

Для генерации PDF используется Headless Chrome, поэтому при разработке шаблонов для распечатки можно использовать все доступные CSS свойства и задействовать минимальный набор JS (минимальный, так как скорость отрисовки - КРИТИЧНЫЙ фактор).

При разработке шаблонов, ориентированных на отображение в вебе стоит учесть основные актуальные браузерные движки - Chrome, Firefox, Safari и использовать вендорные свойства CSS

Обязательно нужно прикладывать все используемые шрифты, как ресурсы и явно добавлять их на страницу. В Headless Chrome шрифтов по умолчанию самый минимум, не факт, что используемый будет входить в их число. Также не факт, что устройства клиентов будут иметь этот шрифт. (Да, даже если это Times New Roman или Comic Sans)

⁠Как пользоваться:

1. Клонировать проект
2. Собрать в одну папку все исходники:
   • Шаблон
   • JSON файл с данными
   • Meta-файл с описанием шаблона (template_meta.json), который оформить по примеру:

   {
      // Название шаблона
      "name": "TEMPLATE_NAME",
      // Версия шаблона (по умолчанию используйте 1)
      "version": "1",
      // Основной файл шаблона
      "content": "index.ftl",
      // Описание всех ресурсов, используемых в шаблоне
      "resources": [
          {
              // Название ресурса, по которому он доступен из шаблона 
              "name": "logo",
              // Путь к файлу относительно корня шаблона
              "file": "assets/logo.png",
              // Тип файла (MIME, content-type)
              "contentType": "image/png"
          },
          {
              "name": "style",
              "file": "assets/style.css",
              "contentType": "text/css"
          },
          {
              "name": "footer",
              "file": "footer.ftl",
              "contentType": "text/plain"
          }
      ]
   }
   

   Copy
   • Все остальные исходники (css, js и т.д.)
   • Пример шаблона можно посмотреть по пути example/simple_template
3. В файле docker-compose.yml:
   • В разделе volumes указать полный путь к папке с исходниками вместо ./data
4. Запустить контейнер командой docker-compose up
5. По умолчанию, шаблон доступен по адресу http://localhost:3000, сгенерированный по нему PDF файл - http://localhost:3000/out.pdf (в терминале эти адреса тоже будут выведены)
6. Завершить работу с редактором шаблонов можно по нажатию CTRL+C

⁠Дополнительные функции в шаблонизаторе:

1. Генерация QR кода:

   • getQRCode - генерация простого QR кода. Принимает 3 параметра: данные, ширина картинки, высота картинки. Пример использования:

     <img src="${getQRCode("hello",256,200)}"/>
     

     Copy
   • getQRCodeAndLogo - генерация QR кода с логотипом внутри. Принимает 4 параметра: данные, ширина картинки, высота картинки, имя ресурса логотипа. Логотип должен быть в формате png, jpg Пример использования:

     <img src="${getQRCodeAndLogo("hello",512,460, "logo")}"/>
     

     Copy

2. Использование ресурсов в шаблонах:

   • Для импорта шаблонов друг в друга используется такая конструкция:

     <#include "resource:footer">
     

     Copy
     При обработке шаблона, затребованный ресурс будет обработан и заинлайнен в результирующий html файл.
     Сам ресурс должен быть предварительно описан в template_meta.json
   • getResourceUrl - для получения ссылки на ресурс. Принимает один параметр - название ресурса. Примеры использования:

     <img src="${getResourceUrl("logo")}"/>
     

     Copy

     <link rel="stylesheet" type="text/css" href="${getResourceUrl("style")}">
     

     Copy
   • getResourceBase64 - для получения всего ресурса, закодированного в Base64. Принимает один параметр - название ресурса. Пример использования:

     <img src="${getResourceBase64("logo")}"/>
     

     Copy

3. Изменять размер получаемого PDF можно свойством CSS:

   @page {
       size: 105mm 148mm;
   }
   

   Copy