Usage

Enable the PDF generation

PDFResource works out of the box and creates PDF files from all resources, that have the template variable create_pdf assigned (the template variable name could be changed in MODX system settings). The generated PDF files are saved with the current alias path to {assets_url}/pdf/

So after the installation you only have to assign the template variable create_pdf to the templates of the resources that should be converted to PDF and check that template variable in the resource (checked by default).

PDF generation on the fly

To generate PDF files on the fly with PDFResource you have to assign the template variable live_pdf to a template (the template variable name could be changed in MODX system settings) and check this template variable on a resource. After this, the resource will be rendered as PDF file in the browser. The file could be saved with the current alias.

PDF options

By default the PDF content and the CSS code for the PDF could be changed with the chunks tplPDF and tplCSS. Some other PDF options (pagesize, margins etc.) could be set in MODX system setting.

PDFResource uses the following system settings in the namespace pdfresource:

Resource based PDF options

All these options could be modified on resource base in a template variable pdf_options (the template variable name could be changed in MODX system settings). This template variable has to contain a JSON-encoded object of options without the prefix pdfresource..

Example

{
    "format": "A4-L",
    "mgl": 20,
    "mgr": 20
}

PDF content template

The content of the PDF is filled with the chunk defined by pdfresource.pdfTpl MODX system setting (or on resource base by the pdf_options template variable). By default PDFResource uses the tplPDF chunk. You could fill this chunk like a normal MODX template with resource placeholders, snippet calls etc. Since the PDF is not created on the fly, the content is fixed after saving the resource.

PDF header and footer templates

The HTML header and footer of each PDF page are filled with the chunks defined by the pdfresource.headerTpl and pdfresource.footerTpl MODX system settings (or on resource base by the pdf_options template variable). Both settings are empty by default, so no header or footer is set. The chunks are parsed like the PDF content template, so you can use the same resource placeholders, snippet calls etc. Additionally, you can use the mPDF placeholders {PAGENO} (current page number) and {nbpg} (total number of pages).

Example

A chunk tplPDFFooter with the following content:

<table width="100%" style="font-size: 8pt;">
    <tr>
        <td width="50%">[[+pagetitle]]</td>
        <td width="50%" align="right">Page {PAGENO} of {nbpg}</td>
    </tr>
</table>

Referenced in the pdf_options template variable:

{
    "footerTpl": "tplPDFFooter"
}

The header is placed mgh millimeters below the top edge and the footer mgf millimeters above the bottom edge of the page. If a header or footer template is set, the top or bottom margin (mgt, mgb) is increased automatically, if the header or footer needs more space. The styles of the pdfresource.cssTpl chunk are used for the header and footer, too.

If a template chunk could not be loaded, a warning is logged in the MODX error log.

PDF styles template

The style of the PDF is set with the chunk defined by pdfresource.cssTpl MODX system setting (or on resource base by the pdf_options template variable). By default PDFResource uses the tplCSS chunk. There are some limitations with mPDF and CSS (e.g. position: absolute works only with elements on root level).

Custom fonts

To use custom fonts in your PDF files, you have to add them as JSON-encoded object in the MODX system setting pdfresource.customFonts. See Fonts in the mPDF documentation a the full description.

Example

{
  "frutiger": {
    "R": "Frutiger-Normal.ttf",
    "I": "FrutigerObl-Normal.ttf"
  }
}

Please copy the font files to the folder referenced in the MODX system setting pdfresource.customFontsFolder. Before PDFResource version 2 they have to copied to {core_path}components/pdfresource/vendor/mpdf/mpdf/ttfonts/.

PDF permissions

The generated PDF could be encrypted to set user permissions. An user password to open the file and an owner password to bypass and/or change the permission restrictions could be set. The PDF encryption is enabled if the user or the owner password is set.

A list of permissions could be found at permissions in the mPDF documentation. By default all permissions are denied if the file is encrypted.

The following example JSON will grant copying and printing (low-res) to the end-user of the generated PDF.

Example

["copy", "print"]

Other mPDF options

If you want to set other mPDF options to modify the PDF file creation, you could call the mPDF class methods with callbacks.

To use the callbacs, you first have to fill the MODX system setting pdfresource.mPDFMethods with a JSON-encoded array of called method names. After that, you have to fill the according MODX system setting or (on resource base) an according key in pdf_options template variable. The method parameters have to be set by a JSON-encoded array.

Example

To call the mPDF method SetHTMLFooter you have to set the MODX system setting pdfresource.mPDFMethods to

["SetHTMLFooter"]

After that you have to create a MODX system setting pdfresource.SetHTMLFooter and fill it with

["<div align='right' style='font-size: 8pt;'>{PAGENO}</div><div align='center' style='font-size: 8pt; font-style: italic;'><hr>My footer text.</div>"]

or fill the PDF Options template variable of a resource with

{
  "SetHTMLFooter": [
    "<div align='right' style='font-size: 8pt;'>{PAGENO}</div><div align='center' style='font-size: 8pt; font-style: italic;'><hr>My footer text.</div>"
  ]
}

Linking to a generated PDF

All generated static PDF files are saved with the aliaspath of the generating resource. If you want to create a link to that PDF file, you could use the following code. The output filter returns - if the file does not exist:

[[*id:pdfresourcelink:ne=`-`:then=`<a href="[[*id:pdfresourcelink]]">PDF</a>`:else=``]]

Debug HTML/CSS output

The pre-rendered HTML or CSS output handled by mPDF can be debugged with the mode url parameter. For this you have to enable the pdfresource.debug system setting and load the PDF generating resource with mode=html, mode=css, mode=header or mode=footer as URL parameter. The result will be the HTML, CSS, header or footer code that is handled by mPDF.

That way you can identify wrong image paths etc. in this code. Don't forget to disable the pdfresource.debug system setting afterwards.

Tips and tricks

If you want to change the filename of the generated PDF on the fly, you have to create a new plugin that runs before PDFResource in OnWebPagePrerender. This plugin has to execute $modx->resource->set('alias', 'invoice_' . date('Ymd', $invoice->get('date')) . '_' . $invoice->get('client_id')) to set the alias on the fly (it works even without saving $modx->resource).