Manual Contaoforms Bundle
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 8
| Download | |
| Open PDF In Browser | View PDF |
Manual
for Contao extension "contao-pdfforms-bundle"
This Contao extension from Softleister expands the form generator and the ability to
fill out a PDF template with the data entered in the online form, to store and to mail.
The extension contao-pdfforms-bundle is installed as a limited demo. The demo
version prints a demo note in the PDF, has full functionality but is limited to 2 output
pages.
When you buy a license key, the restrictions are removed. The license allows you to
use the extension in the domain specified at the time of purchase. The use in other
domains requires an additional license.
Contents
1. System Requirements
2. Interaction with other extensions
3. Installation
4. Advanced form properties
5. Definition of text positions in the PDF
6. Setting up the email attachment
7. Directory protection, protected PDF
8. Insert tags
9. For programmers and developers
10. Troubleshooting
1. System Requirements
The extension is approved for Contao 4 from version 4.4
The Composer or Contao Manager is required for the installation.
2. Interaction with other extensions
With the following extensions further features are available:
notification_center
terminal42/notification_center
contao-pdfforms-bundle enables a new notification type for
sending notifications. The generated file can be attached to the
mail with tokens.
3. Installation
Simply install the extension with the Contao Manager, search for
do-while/contao-pdfforms-bundle
or on the command line with the Composer:
composer require do-while/contao-pdfforms-bundle
4. Advanced form properties
After the installation, more functions are available in the properties of the form
generator:
In the section Fill in PDF form, you can turn on the creation of a PDF file.
You specify a PDF template file that includes an empty paper form. The form is used
as a copy and will be filled out with inputs from the web form. The page sizes of the
original pages are copied.
You can specify under Further processing that the generated file is to be included
as a mail attachment in the form mail.
To save the PDF files, you specify a Directory for storing. In this directory the
complete generated PDFs are stored. The file name is generated from the form name
and a timestamp, you can change the file name scheme by editing the optional field
Expand file name. By default the file name is expanded by date an time. The usage
of Insert tags is possible.
With Take all document pages you control whether all document pages to be
included in the PDF, or just the pages with valid positions are entered. So you have
the possibility to create optional pages on the submission. If you want a single
unused page (such as GTC) to be included, you should create a position data that
adds a white space on that page.
If you determine the positions of the entries, there are often differences to the edge of
the paper. This offset is true for all positions of the PDF. To avoid having to adjust
each item, you can just define a Basic offset by an entry in the form properties.
For the presentation, you can define the text color in PDF and the Title and the
Author for the file properties.
It is possible to protect the created PDF with a password. There are 2 ways:
a) Password protection when opening the document
You can also enter the InsertTag {{pdf_forms::password_random}} to use a
random password. Send this password with another notification mail (Notification
Center).
b) Restriction of privileges, select all allowed permissions. If the PDF password for
permissions is left blank, a random password is generated. The password is then
unknown.
Note: The PDF protection is not completely secure. With appropriate programs, the password can be
bypassed!
5. Definition of text positions in the PDF
In the overview of the form generator there is an additional icon (PDF icon). The
following table, the positions of the entries in the template PDF are created. Any
number of positions can be created.
It is possible to create a completed test PDF file directly in the backend. This allows
you to quickly check that all the positions are on the right places in the form. All
published positions are output, form fields are printed with its field name.
Creating the individual positions:
In the first section the text information are set. There are 2 options: a field name from
the form generator or a fixed text in quotation marks.
In the example, the form fields firstname, lastname and a fixed text with comma/
space. This individual lines are lined up with spaces (no space before the comma).
In the second column a output condition can be programmed. In the example, the
comma is dependent on the filled form field firstname.
The condition can also be inverted:
used = Field is filled / checkbox or radio button is checked
empty = Field is empty / checkbox or radio button is unchecked
The fixed texts can also contain Insert tags:
In this example, "Berlin, 2018-02-04" or only "2018-02-04" entered in the PDF,
depending on whether the location is specified or not.
To cross check boxes, we use an "X" with the checkbox value in the condition:
In the lower part of the backend form it comes to the position in the PDF where the
selected information is entered and the font attributes.
The position consists of the PDF page, the horizontal distance from the left edge
and the vertical distance from the top edge. Optionally, also a right margin can be
entered. This is often useful in form fields of type textarea as a position where the
lines of text to wrap. Depending on the font used (defined as PDF_FONT_NAME_
MAIN /system/config/tcpdf.php), there may be a constant offset of over- and underlengths in this font.
A good way to determine the positions, is a measurement of the PDF page e.g. in
Photoshop. With a test position you can easily detect the offset values. Enter these
offsets in the form properties and the offset will be included in all other positions.
Note: The positions always refer to the basic offset in the form properties.
6. Setting up the email attachment
In the form properties, there is the checkbox "Send form data via e-mail". This
checkbox sends the input data mostly as raw data to the recipient's address. If you
select "Save PDF file and attach it to the email" at further processing, the output PDF
file is sent as attachments with the e-mail.
When using the notification center there is an additional type of notification
"pdf_forms - pdf_form_transmit". In the attachment input you can use the token
##pdfdocument## to add the PDF file to the e-mail.
7. Directory protection, protected PDF
To prevent direct downloads of PDF files, which often contain personal data, the
storage directory can be protected in the file manager of Contao. The files are still
fully usable as an e-mail attachment.
In addition, the PDF created can be protected with a password. The protection can
prevent the opening or restrict the permissions.
Note: The PDF protection is not completely secure. With appropriate programs, the password can be
bypassed!
8. Insert tags
The extension replaces insert tags in the position definitions, so that, if necessary,
dynamic data or the data of the registered member may be used.
The extension also provides its own insert tags available:
{{pdf_forms::pdfdocument}}
can be used to insert a file link to the generated document in a download link.
{{pdf_forms::pdfdocument::name}}
can be used to insert the file name of the PDF document produced in the page.
{{pdf_forms::password_random}}
generates a random password, e. g. as the open password of the PDF. Send the
password in an additional notification mail (Notification Center). The Simple token for
this is ##openpassword##
9. For programmers and developers
This section is intended for programmers who want to take in your own modules
influence on these extensions. In the program sequence you can inject at different
locations by means of a HOOK-registration. The extension contao-pdfforms-bundle
then calls the registered hooks, provided there are any.
The following hooks are available:
$GLOBALS['TL_HOOKS']['pdf_formsBeforePdf']
Called after the data preparation before the PDF is created. Here you can add items
in the passed array $arrPDF or modified existing ones. The hook should return the
$arrPDF as return value.
Example:
// config.php
$GLOBALS['TL_HOOKS']['pdf_formsBeforePdf'][] = array('vendor\MyExtension\MyClass',
'myPdfFormsBeforePdf');
// MyClass.php
namespace vendor\MyExtension;
public function myPdfFormsBeforePdf( $arrPDF, $this )
{
// beliebiger Code
return $arrPDF;
}
$GLOBALS['TL_HOOKS']['pdf_formsPositions']
Called when creating a PDF for each position item on the form. It is possible to manipulate data. The page number can not be changed, otherwise the output will not work
correctly. The return value is the modified array $arrItem.
Example:
// config.php
$GLOBALS['TL_HOOKS']['pdf_formsPositions'][] = array('vendor\MyExtension\MyClass',
'myPdfFormsPositions');
// MyClass.php
namespace vendor\MyExtension;
public function myPdfFormsPositions( $arrItem )
{
// beliebiger Code
return $arrItem;
}
$GLOBALS['TL_HOOKS']['pdf_formsAfterPdf']
Called after the generation, storage and shipping. You can add more final activities
by this Hook. The hook has no return value.
Example:
// config.php
$GLOBALS['TL_HOOKS']['pdf_formsAfterPdf'][] = array('vendor\MyExtension\MyClass',
'myPdfFormsAfterPdf');
// MyClass.php
namespace vendor\MyExtension;
public function myPdfFormsAfterPdf( $pdfdatei, $arrPDF, $this )
{
// beliebiger Code
}
10. Troubleshooting
Collection of some points which could cause errors:
The template PDF file can not be read
The template PDF must be readable for the extension tcpdf_ext, it must be available
in the PDF specification format 1.4 (Acrobat 5.x). Recent PDF versions must be converted to the older format before.
In Adobe Acrobat on "Save As ..." select "Adobe PDF files optimized (*.pdf)" and then
adjust the settings to "Acrobat 5.0 and higher."
The text does not have the right position in the form PDF generator
The measured positions usually have a fixed offset, which comes from the over- and
under-lengths in the font. The easiest way is to set a text on test position and measure the difference to the desired position. This basic offset can be entered in the
form properties and will calculate in the output at each position.
There are fields that do not exist in PDF form, but should be output in the
document anyway.
Simply enter an additional page number, if the target page is not included in the
template, a blank page is added where additional information can be placed in the
same way.
___
Status: Version 1.1.0 - 2018-02-22
Softleister, Dipl. Ing. Hagen Klemp, info@softleister.de, www.softleister.de
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No Language : de-DE XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:08:04 Create Date : 2018:02:22 22:38:52+01:00 Creator Tool : Writer Modify Date : 2018:02:22 22:40:52+01:00 Metadata Date : 2018:02:22 22:40:52+01:00 Producer : LibreOffice 5.3 Format : application/pdf Title : Manual contao-pdfforms-bundle Creator : Softleister Document ID : uuid:194c53d5-37b1-4ce9-8c15-4ed31ec44124 Instance ID : uuid:cc50b8a6-9946-421b-acb9-cfa6e483ec3d Page Count : 8 Author : Softleister Warning : [Minor] Ignored duplicate Info dictionaryEXIF Metadata provided by EXIF.tools