HTML - PDF conversion with custom header and footer

In this tutorial we’ll learn how to create a document with a custom header and footer using HTML to PDF API. Also, we’ll see how some related options work, and learn some little tricks on how to customize each page differently.

Basic options

To start, I’m using an already complete invoice template from one of our previous articles which can be easily converted to pdf using a simple cURL command:

curl -H 'Authentication: Token <your token>' \
-F 'file=@invoice.html' \
'https://htmlpdfapi.com/api/v1/pdf' > invoice.pdf 

For more information about cURL visit: http://curl.haxx.se/docs/manpage.html

In this cURL we are covering only basic options but there are a lot more options for customization which can make your document look professional and polished. For example, if we want to add margins we can easily do this with a cURL command:

curl -H 'Authentication: Token <your token>' \
-F 'file=@invoice.html' \
-F 'margin_left=20mm' \
-F 'margin_right=20mm' \
-F 'margin_top=20mm' \
-F 'margin_bottom=20mm' \
'https://htmlpdfapi.com/api/v1/pdf' > invoice.pdf

If we don’t transfer margin options, default ones will be used - which are 10mm. Units can be transferred in the following measures: mm, cm... If measurement is not defined, mm are assumed.

Note: Pixels are not physical units of measurement, therefore they can’t be used here.

List of all options and default values can be found here.

Adding a header and a footer to our PDF

Headers and footers can help keep longer documents organized and make them easier to read. In our example, a header and a footer are a part of a template markup. If our document is longer than one page, the header will appear only on the first page, and the footer on the last and it will be followed by content. What we want is for the text entered in the header or footer to appear on each page of the document. To achieve this, first, we need to split the header and footer markup into separate files.

To include a header and a footer as separate templates, we need to transfer ‘header’ and ‘footer’ options via cURL command. They both accept strings as value:

curl -H 'Authentication: Token <your token>' \
-F 'file=@invoice_body.html' \
-F 'header=<invoice_header.html' \
-F 'footer=<invoice_footer.html' \
-F 'margin_left=20mm' \
-F 'margin_right=20mm' \
-F 'margin_top=20mm' \
-F 'margin_bottom=20mm' \
'https://htmlpdfapi.com/api/v1/pdf' > invoice.pdf

Now, our document has a head and a tail and we can finally add some spacing between the header or footer and the body with ‘header_spacing’ and ‘footer_spacing’ options. Both options actually shift the header or footer up or down so we need to adjust our page margins a little bit.

Same goes for footer margins.

curl -H 'Authentication: Token <your token>' \
-F 'file=@invoice_body.html' \
-F 'header=<invoice_header.html' \
-F 'footer=<invoice_footer.html' \
-F 'margin_left=20mm' \
-F 'margin_right=20mm' \
-F 'margin_top=46mm' \
-F 'margin_bottom=64mm' \
-F 'header_spacing=10mm' \
-F 'footer_spacing=10mm' \
'https://htmlpdfapi.com/api/v1/pdf' > invoice.pdf

Header/footer variables

It is worth mentioning that header or footer can not be different sizes on pages. Only one template of type can be included in conversion, so here we need another approach. With variables available in the header and the footer you can easily customize your document. For example, if you want to modify the footer on the first page, simply add {{page}} to your class selector, and customize it with CSS.

<footer class="footer-{{page}}">
//content
</footer>

<style type="text/css">
.footer-1 {display:none}
</style>

A full variable list can be found here.