Intro
Hublify provides a very flexible and easy-to-use pdf-templating engine. This does not apply only to the main content-body but especially to all other parts like.
With Hublify PDF-Templating you can ...
- create PDF documents from Hublify's HTML-Template-Engine (HTML-2-PDF)
- with custom (paper-) dimensions and orientation
- embed PDF-Header and -Footer areas.
Quick Facts
Some valuable infos on the Hublify PDF-Engine
- The HTML-2-PDF Conversion is based on the wonderful headless-Chrome-Browser (PDF).
Hublify makes this easily available for you with all it capabilities and limitations. - HTML-PDF-Templates are stored like all other templates within Hublify's Template-Area.
- The technical render-process within Hublifyis as follows ...
- Hublify renders dynamically your "html"-template (twig).
- Hublify sends that html-file along with the extracted Hublify-PDF-Header and -Footer the headless-Chrome-Browser.
- Headless-Chorme-Browser generates and returns from that a new real PDF-file.
- CSS print-media is supported / used within the HTML-2-PDFconversion.
- Hublify provides some basic HTML/PDF-templates and -layouts, as well as some css-classes.
But in the end you can do, program and style however you like!
Easy and flexible
What is particularly convenient when creating PDFs in Hublify is that you only need one Twig template. Headers, footers, stylings etc. are integrated into this Twig template. Of course, you are free to store code (such as stylings) in separate files and include these files.
Custom PDFs
Considerations
Whenever you want to create a new template you have to decide for which main dataset, aka data-type (e.g. "person", "order", "invoice", ...) , this template will be used.
A new template
Create a new Hublify-CMS's template-file. This template-file will hold the html source-code that will later get converted to the final PDF.
You can do this either via ...
- the Hublify App directly (CMS > Template > new)
- SFTP by creating a template file in your desired directory.
(Do not forget then to let Hublify re-index the template-files of this namespace!)
"Classify" your template
Hublify manages a lot of different templates for a lot of different types of datasets and so forth.
Navigate within the Hublify-CMS-Template to the template's edit "classification"-tab and enter:
- Content Typ: "html"
- Typ: "document"
- Content Context: "<your dataset-label / model>"
- Content Structure: "record"
HTML Template Structure
Hublify has some prepared special features.
Example (raw)
Here is an example, showing the usage of some typically used special Hublify-PDF-Tags.
example-pdf.html.twig
<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="de-DE"> <head> <style> html { -webkit-print-color-adjust: exact !important; } </style> </head> <body> {# --- Header --- #} <header> <hublify-pdf-header style="display: none;"> This is the PDF-Header </hublify-pdf-header> </header> {# --- Content --- #} <main> <div class="hfy-contents"> Hello PDF-World ! </div> </main> {# --- Footer --- #} <footer> <hublify-pdf-footer style="display: none;"> This is the PDF-Footer </hublify-pdf-footer> </footer> </body> </html>
Special Tags
<hublify-pdf-header>
If present, this tag will be extracted from the finally rendered html-twig-result and injected as the PDF's page-header into the PDF-rendering.
You can adjust the header's height / size by setting the page's margin-top (see below).
Attention: The header requires its own separate CSS styling. The globally loaded CSS styling is not used in the header if it is not explicitly reloaded in the header.
<hublify-pdf-footer>
If present, this tag will be extracted from the finally rendered html-twig-result and injected as the PDF's page-footer into the PDF-rendering.
You can adjust the header's height / size by setting the page's margin-bottom (see below).
Attention: The footer requires its own separate CSS styling. The globally loaded CSS styling is not used in the footer if it is not explicitly reloaded in the footer.
Hublify Specials
The usage of the following prepared Hublify Templates for HTML, CSS etc. is completely optional!
HTML-PDF Layouts
A basic Hublify template from which you can extend your twig template easily.
Basic template
This is a very basic, very generic skeleton template which handles all the html-/pdf-structuring already for you.
You can then simply add your "content" as html-source-code very easily. E.g. into the twig-block "doc_contents".
In your HTML-PDF-twig-template, simply:
{% extends "@ecs/hublify/pdf/doc--base.html.twig" %} {# ------- your src-code, here ... ----------- #} {% block doc_contents %} <div class="hfy-doc-contents"> Hello world! </div> {% endblock %}
This template provides following twig-"blocks":
- "doc_header"
- "doc_frontpage"
- "doc_contents"
- "doc_tail"
- "doc_footer"
HFY_PAGE - Variable
Hublify's provided template use an own twig-variable (type: object / associative array): HFY_PAGE
This variable can be used to override and set own values for e.g. the PDF's paper-size, margins, etc..
Example, how to use it:
{# -------- set own Page-Configs -------------- #} {% set HFY_PAGE = { size: '300mm 100mm', marginTop: '40mm', marginRight: '20mm', marginBottom: '30mm', marginLeft: '15mm' } %} {# -------- use/extend Hublify-Standard-PDF-Template (this uses then HFY_PAGE !) -------------- #} {% extends "@ecs/hublify/pdf/doc--base.html.twig" %} {# ------- your src-code, here ... ----------- #} {% block doc_contents %} <div class="hfy-doc-contents"> Hello world! </div> {% endblock %}
size
This sets the final PDF's paper dimensions. Usually it defaults to "A4".
Example values are: "A4" , "B5", "300mm 100mm", ...
See further details, e.g. here: https://developer.mozilla.org/en-US/docs/Web/CSS/@page/size
marginTop
This sets the top-margin. This is distance to real paper-page-edge.
Example values are: "0" , "25mm", ...
marginBottom
This sets the top-margin. This is distance to real paper-page-edge.
Example values are: "0" , "25mm", ...
marginLeft
This sets the top-margin. This is distance to real paper-page-edge.
Example values are: "0" , "25mm", ...
marginRight
This sets the top-margin. This is distance to real paper-page-edge.
Example values are: "0" , "25mm", ...
Hublify CSS Classes
Hublify brings some standard print-media css classes that you can use.
These classes are defined within the theme, located within template : doc-style--hublify.css.twig :
.hfy-page-break
Forces a page-break.
<div class="hfy-page-break"></div>
.hfy-break-before
Forces a break before.
<div class="hfy-break-before"></div>
.hfy-page-break-before
Forces a page-break before.
<div class="hfy-page-break-before"></div>
.hfy-break-after
Forces a break after.
<div class="hfy-break-after"></div>
.hfy-page-break-after
Forces a page-break after.
<div class="hfy-page-break-after"></div>
.hfy-avoid-break-inside
Avoids a break inside.
<div class="hfy-avoid-break-inside"></div>
.hfy-no-print
Prevents this area from being printed.
<div class="hfy-no-print"></div>
hfy-doc-contents
Not used, yet. Reserved for future use.
.hfy-doc-frontpage
Not used, yet. Reserved for future use.
.hfy-doc-tail
Not used, yet. Reserved for future use.
.hfy-doc-appendix
Not used, yet. Reserved for future use.
.hfy-dev-layout
Renders a dashed border on the applied html-element.
<div class="hfy-dev-layout"></div>
Other resources
Some other maybe helpful external resources:
- https://www.smashingmagazine.com/2015/01/designing-for-print-with-css/