M4 PDF Extensions Guide

Introduction

M4 PDF Extensions module replaces the built-in PDF document generation and adds new options for document creation in the administration through user templates. All with full support for UTF-8 encoding and with the possibility to use non-latin fonts.

Features

  • create an unlimited number of PDF outputs with Smarty templates
  • PDF documents for one record or for more selected records
  • extended range of products from multiple categories
  • optional replacement for embedded PDF documents
  • create documents and lists by using templates
  • change the look of documents with CSS style templates
  • documents can contain images, indexes, headers, footers, watermarks, bar codes
  • support for user-defined additional field output to the database
  • full support for UTF-8
  • support for non-latin fonts
  • multi-language support for user texts in templates
  • sample templates for easier design
  • for template tuning, there is a template displaying the data transferred
  • the module does not require any interaction with PrestaShop™

How the module works

The module operates in two modes. The two modes differ only in activation. They use the same data source and can use the same templates. In the first mode, PDF documents can be created in the administration module.

In the second mode, a PDF document is created as a replacement in one of the 8 options for creating PDF documents in PrestaShop™. These options can be individually selected in the module configuration.

The following diagram shows how to activate and create PDF documents. The first step is to gather or select the desired data. Data is loaded into the selected Smarty template. The template processes the data and generates a HTML page that is transferred to a mPDF library, which creates a PDF document.

More information on the libraries used:
Smarty - http://www.smarty.net/docs.php
mPDF - http://mpdf1.com/manual/

Data Sources

There are 5 sources of data. These correspond exactly to the selections in the module configuration. The module can work with this data and create outputs:

  • Catalog
  • Customers
  • Orders
  • Orders with details
  • Credit slips with details

All data sources provide a log list. For itemized orders and credit notes, related items are also available. This can be used to generate invoices, delivery slips and credit slips.

Templates

Templates mean Smarty Templates. It must be a fully featured HTML document with <head> and <body> tags. Templates are located in the subdirectory /tpl of the module. The module includes a tuning template and a testing template. These can be used to get started and familiarize with the template features.

The template can have 4 basic elements. Individual elements are highlighted in this simple template example.

A. Template identification

To identify a template and determine whether it can be used with a particular data source, each template must contain a reference to name and data. The element name is the name of the template. The element data describes the data source for which the template is intended. Valid data sources are:

  • customer - customers
  • order - orders
  • order+detail - orders with details
  • orderslip+detail - credit slips with details
  • product - catalog

and

  • * - all data sources without distinction (for example, the tuning template)

Marking the template with the elements name and data must appear at the beginning of the template as an HTML comment line (prepended by <!-- and -->), not on more than 5 lines.

B. Smarty functions

The second component of the sample refers to the Smarty {assign} function, which assigns a value to the template variable. This part is optional. Even if you wish to use the Smarty function, you do not have to place it here. We mention this possibility because this is a well structured location to place constants or other code.

C. Style definition

For a clear style definition, it is best to use CSS. The CSS style block must be enclosed within double tags {literal}<style> and </style>{/literal}. Style definition is not mandatory.

Rule @page defines page layout, orientation and edges. This and other supported rules are described in the mPDF library manual and on the User's Guide >> CSS & Stylesheets >> Supported CSS page.

D. Template content

The actual template content is located between tags <body> and </body>. Besides text, you can use tables, images, form elements and format the content using HTML tags and CSS. Their overview can be found in the mPDF library manual and on the User's Guide >> HTML support >> HTML Tags page.

Header, footer, index and other elements

The mPDF library can be used to add elements to the final document that cannot be created using standard HTML tags. In order to accomplish that, it uses its own tags. Some of them are the following:

  • <annotation> - Add an Annotation to the document
  • <barcode> - Add a Barcode to the document
  • <columnbreak> - Start a new Column
  • <columns> - Control use of Columns on the page
  • <dottab> - Insert dots to following (right-aligned) text
  • <formfeed> - Add a new page keeping current HTML tags/CSS styles active
  • <htmlpagefooter> - Define an HTML page footer with a given name
  • <htmlpageheader> - Define an HTML page header with a given name
  • <pagebreak> - Add a new page
  • <tocentry> - Insert an entry for the Table of Contents
  • <tocpagebreak> - Insert a table of contents
  • <watermarkimage> - Set an image to use as a Watermark
  • <watermarktext> - Set the text to use as a Watermark

All tags are described in the mPDF library manual and on the Reference >> HTML control tags page.

Translation of template texts

PrestaShop™ administrative tools can be used to translate multilingual texts. Select Tools >>Translations in the administration panel, in block Modify translations select Module translations and choose the language for translation.

All the PrestaShop™ modules for translation will appear on the next page. They include all the templates, as well as the administrative interface of the module. For easy identification of the templates, a common prefix, such as m4 should be used. In this way, all texts in the templates that use Smarty syntax {l s='text for translation'} can be changed.