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/