Manual.rst

General

• Project homepage: https://qfq.io
• Latest releases: https://qfq.io/download
• Development: https://git.math.uzh.ch/typo3/qfq
• Chat: https://hello.math.uzh.ch > QFQ

Installation

The following features are only tested / supported on linux hosts:

• General: QFQ is coded to run on Linux hosts, preferable on Debian derivates like Ubuntu.
• HTML to PDF conversion - command wkhtmltopdf.
• Concatenation of PDF files - command pdfunite.
• PDF decrypt (used for merge with pdfunite) - command qpdf.
• Mime type detection for uploads - command file.

Preparation

Report & Form

To normalize UTF8 input, php-intl package is needed by

• normalizer::normalize()

For the download function, the programs pdfunite, qpdf and file are necessary to concatenate PDF files.

Preparation for Ubuntu:

sudo apt install php-intl
sudo apt install poppler-utils libxrender1 file pdf2svg pdfunite qpdf # for file upload, PDF and 'HTML to PDF' (wkhtmltopdf), PDF split
sudo apt install inkscape imagemagick            # to render thumbnails

wkhtmltopdf

wkhtmltopdf will be used by QFQ to offer 'website print' and 'HTML to PDF' conversion. The program is not included in QFQ and has to be manually installed.

• The Ubuntu package wkhtmltopdf needs a running Xserver - this does not work on a headless webserver.
  • Best is to install the QT version from the named website above.
  • In case of trouble with wkhtmltopdf, also install 'libxrender1'.
  • The current version 0.12.4 might have trouble with https connections. Version 0.12.5-dev (github master branch) seems more reliable. Please contact the QFQ authors if you need a compiled Ubuntu version of wkhtmltopdf.

In configuration specify:

config.cmdWkhtmltopdf:  /opt/wkhtmltox/bin/wkhtmltopdf
config.baseUrl: http://www.example.com/

If wkhtml has been compiled with dedicated libraries (not part of LD_LIBRARY_PATH), specify the LD_LIBRARY_PATH together with the path-filename:

config.cmdWkhtmltopdf: LD_LIBRARY_PATH=/opt/wkhtmltox/lib /opt/wkhtmltox/bin/wkhtmltopdf

Important

To access FE_GROUP protected pages or content, it's necessary to disable the [FE][lockIP] check! wkhtml will access the Typo3 page locally (localhost) and that IP address is different from the client (=user) IP.

Configure via Typo3 Installtool All configuration > $TYPO3_CONF_VARS['FE']:

[FE][lockIP] = 0

Warning

[FE][lockIP] = 0 disables an important anti-'session hijacking' protection. The security level of the whole installation will be lowered! Again, this is only needed if wkhtml needs access to FE_GROUP protected pages & content. As an alternative to lower the security level, create a separated page subtree which is only accessible (configured via Typoscript) from specific IPs or if a FE-User is logged in.

If there are problems with converting/downloading FE_GROUP protected pages, check configuration showDebugInfo = download to debug.

Note

Converting HTML to PDF gives no error message but RC=-1? Check carefully all includes of CSS, JS, images and so on! Typically some of them fails to load and wkhtml stops running! Verify the correct loading of all elements by calling the site via a regular browser and bypassing any browser cache (Ctrl F5).

Checklist wkhtml problems

• config.baseUrl is configured and correct. The baseUrl has to be the same protocol as the website (http or https).
• To track down problems:
  • In configuration set debug.showDebugInfo=auto,download.
  • Do the download.
  • Check QFQ_LOG for any output.
  • Grab the URL given in the QFQ_LOG, open a browser in private mode (no existing browser session) and open the URL.
  • Check the --cookie-jar '/tmp/qfq.cookie....' file for the cookie.
  • Call wkhtml manually on the webserver, with the same options as given in the QFQ_LOG.

HTML to PDF conversion

wkhtmltopdf converts a website (local or remote) to a (multi)-page PDF file. It's mainly used in download.

Print

Different browser prints the same page in different variations. To prevent this, QFQ implements a small PHP wrapper print.php with uses wkhtmltopdf to convert HTML to PDF.

Provide a print this page-link (replace 'current pageId' ):

<a href="typo3conf/ext/qfq/Classes/Api/print.php?id={current pageId}">Print this page</a>

Any parameter specified after print.php will be delivered to wkhtmltopdf as part of the URL.

Typoscript code to implement a print link on every page:

10 = TEXT
10 {
  wrap = <a href="typo3conf/ext/qfq/Classes/Api/print.php?id=|&type=99"><span class="glyphicon glyphicon-print" aria-hidden="true"></span> Printview</a>
  data = page:uid
}

Send Email

QFQ sends mail via sendEmail http://caspian.dotconf.net/menu/Software/SendEmail/ - a small perl script without a central configuration.

By default, sendEmail uses the local installed MTA, writes a logfile to fileadmin/protected/log/mail.log and handles attachments via commandline options. A basic HTML email support is implemented.

The latest version is v1.56, which has at least one bug. That one is patched in the QFQ internal version v1.56p1 (see QFQ GIT sources in directory 'patches/sendEmail.patch').

Nevertheless, on latest system the TLS support is broken - please check sendEmailProblem.