Installation.rst

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 and qfqpdf.
• Concatenation of PDF files - command pdfunite.
• Convert of images to PDF files - command img2pdf.
• PDF decrypt (used for merge with pdfunite) - command qpdf.
• PDF decrypt (used for merge with pdfunite) - command gs - in case qpdf is not successful.
• PDF fix (used for merge with pdfunite) - command pdf2ps and ps2pdf - in case qpdf is not successful.
• Mime type detection for uploads - command file.
• Split PDF into JPG - command convert.
• Repair PDF - command pdftocairo.
• Convert HEIC/HEIF to png - command heif-info and heif-convert.

Preparation

Report & Form

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

• normalizer::normalize()

For the :ref:`download` function, the programs img2pdf, pdfunite, qpdf, gs, pdf2ps, ps2pdf and file are necessary to concatenate PDF files.

Preparation for Ubuntu:

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

HTML to PDF: qfqpdf

The below named wkhtml becomes more and more outdated (no further development). As a replacement, QFQ started to use puppeteer (https://developers.google.com/web/tools/puppeteer/). The tool can't be used directly, a wrapper is neccessary which is available under https://git.math.uzh.ch/bbaer/qfqpdf. The wrapper uses and installs always the latest version of puppeteer. On first start and during updates, it might take longer to render a pdf.

Installation:

mkdir /opt/qfqpdf; cd /opt/qfqpdf
curl -L -o qfqpdf https://www.math.uzh.ch/repo/qfqpdf/current/qfqpdf-linux
chmod a+x qfqpdf
./qfqpdf --version

HTML to PDF: 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 :ref:`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 :ref:`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).

Note

On Ubuntu, Apache is started by default with LANG=C. This is true even when the OS default locale is set to en_US.UTF-8. Furthermore, all child processes of Apache will inherit LANG=C. Some PHP functions (like 'escapeshellarg()') or wkhtml will strip all non-ASCII characters (e.g. commandline arguments).

Let Apache run with the system locale: /etc/apache/envvars, activate the line . /etc/default/locale and restart Apache.

Checklist wkhtml problems

• config.baseUrl is configured and correct.
• To track down problems:
  • In :ref:`configuration` set debug.showDebugInfo=auto,download.
  • Do the download.
  • Check :ref:`QFQ_LOG` for any output.
  • Grab the URL given in the :ref:`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 :ref:`QFQ_LOG`.

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/qfqProject/log/mail.log and handles attachments via commandline options. A basic HTML email support is implemented.

NOTE: The log directory has been moved into qfqProject with a recent upgrade of QFQ. For backwards compatibility logs are still stored in fileadmin/protected/log/ if that directory already exists.

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 :ref:`sendEmailProblem`.

The Typo3 sendmail eco-system is not used at all by QFQ.

Thumbnail

Thumbnails will be rendered via ImageMagick (https://www.imagemagick.org/) 'convert' and 'inkscape' (https://inkscape.org). 'inkscape' is only used for '.svg' files.

The Typo3 graphic eco-system is not used at all by QFQ.

Usage: :ref:`column-thumbnail`.

If there are no thumbnails and you see convert-im6.q16: no images defined in syslog: Check file /etc/ImageMagick-6/policy.xml and update:

old: <policy domain="coder" rights="none" pattern="PDF" /> New: <policy domain="coder" rights="read | write" pattern="PDF" />

Setup

• Install the extension via the Extension Manager.
  • If you install the extension by manual download/upload and get an error message "can't activate extension": rename the downloaded zip file to qfq.zip or qfq_<version>.zip (e.g. version: 18.12.0).
  • If the Extension Manager stops after importing: check your memory limit in php.ini.
• Copy/rename the file <site path>/fileadmin/protected/qfqProject/conf/example.qfq.json to <site path>/fileadmin/protected/qfqProject/conf/qfq.json. Configure the necessary settings :ref:`configuration` The configuration file is outside of the extension directory, to not loose it during de-install and install again.
• When the QFQ Extension is called the first time on the Typo3 frontend, the file <ext_dir>/Classes/Sql/qfqDefaultTables.sql will played and fills the database with the QFQ system tables.
• Configure Typoscript to include Bootstrap, jQuery, QFQ javascript and CSS files.

Setup CSS & JS

page.meta {
    X-UA-Compatible = IE=edge
    X-UA-Compatible.attribute = http-equiv
    viewport=width=device-width, initial-scale=1
}

page.includeCSS {
    file01 = typo3conf/ext/qfq/Resources/Public/Css/bootstrap.min.css
    file02 = typo3conf/ext/qfq/Resources/Public/Css/bootstrap-theme.min.css
    file03 = typo3conf/ext/qfq/Resources/Public/Css/jqx.base.css
    file04 = typo3conf/ext/qfq/Resources/Public/Css/jqx.bootstrap.css
    file05 = typo3conf/ext/qfq/Resources/Public/Css/qfq-bs.css
    file06 = typo3conf/ext/qfq/Resources/Public/Css/tablesorter-bootstrap.css
    file07 = typo3conf/ext/qfq/Resources/Public/Css/font-awesome.min.css
    file08 = typo3conf/ext/qfq/Resources/Public/Css/bootstrap-datetimepicker.min.css
    file09 = typo3conf/ext/qfq/Resources/Public/Css/codemirror.css

    # Only needed in case FullCalendar is used
    file10 = typo3conf/ext/qfq/Resources/Public/Css/fullcalendar.min.css
}

page.includeJS {
    file01 = typo3conf/ext/qfq/Resources/Public/JavaScript/jquery.min.js
    file02 = typo3conf/ext/qfq/Resources/Public/JavaScript/bootstrap.min.js
    file03 = typo3conf/ext/qfq/Resources/Public/JavaScript/validator.min.js
    file04 = typo3conf/ext/qfq/Resources/Public/JavaScript/jqx-all.js
    file05 = typo3conf/ext/qfq/Resources/Public/JavaScript/globalize.js
    file06 = typo3conf/ext/qfq/Resources/Public/JavaScript/tinymce.min.js
    file07 = typo3conf/ext/qfq/Resources/Public/JavaScript/EventEmitter.min.js
    file08 = typo3conf/ext/qfq/Resources/Public/JavaScript/typeahead.bundle.min.js
    file09 = typo3conf/ext/qfq/Resources/Public/JavaScript/qfq.min.js
    file10 = typo3conf/ext/qfq/Resources/Public/JavaScript/jquery.tablesorter.combined.min.js
    file11 = typo3conf/ext/qfq/Resources/Public/JavaScript/jquery.tablesorter.pager.min.js
    file12 = typo3conf/ext/qfq/Resources/Public/JavaScript/widget-columnSelector.min.js
    file13 = typo3conf/ext/qfq/Resources/Public/JavaScript/widget-output.min.js
    file14 = typo3conf/ext/qfq/Resources/Public/JavaScript/moment.min.js
    file15 = typo3conf/ext/qfq/Resources/Public/JavaScript/bootstrap-datetimepicker.min.js
    file16 = typo3conf/ext/qfq/Resources/Public/JavaScript/codemirror.js
    file17 = typo3conf/ext/qfq/Resources/Public/JavaScript/code-mirror-mode/sql/sql.js

    # Only needed in case FormElement 'annotate' is used.
    file18 = typo3conf/ext/qfq/Resources/Public/JavaScript/fabric.min.js
    file19 = typo3conf/ext/qfq/Resources/Public/JavaScript/qfq.fabric.min.js

    # Only needed in case FullCalendar is used.
    file20 = typo3conf/ext/qfq/Resources/Public/JavaScript/fullcalendar.min.js

}

Datetimepicker

Include the JS and CSS Files to get datetimepicker work: Following scripts are needed:

• bootstrap-datetimepicker.min.css
• bootstrap-datetimepicker.min.js

As first option both can be inserted to the setup of the main Template like the other scripts shown above.

Second option is to use the UZH CD template.

Following configurations can be set over FormElement.parameter:

dateFormat = DD.MM.YYYY HH:mm:ss | MM-DD-YYYY HH:mm | dddd DD.MM.YYYY HH:mm -> DD:day of month,MM:month value,YYYY:year value,HH:24h,hh:12h AM-PM,mm:minutes,ss:seconds,dddd:written day of week dateDaysOfWeekEnabled = 0,1,6 -> 0:sunday,1:monday,2:tuesday,3:wednesday,4:thursday,5:friday,6:saturday dateLocale = en | de -> Set language min = 03.05.2022 -> minDate that can be selected max = 23.07.2022 -> maxDate that can be selected dateViewModeDefault = days | months | years clearMe = 0 | 1 -> show clear button dateShowCalendarWeeks = false | true dateUseCurrentDatetime = false | true datetimeSideBySide = false | true -> Show time right to date

FormEditor

Setup a report to manage all forms:

• Create a Typo3 page.

• Set the 'URL Alias' to form (recommended) or the individual defined value in parameter editFormPage (configuration).

• Insert a content record of type qfq.

• In the bodytext insert the following code (see explanation of code: :ref:`reportAsFile`):

  file=_formEditor

• Twig version of FormEditor is available too

  file=_formEditorTwig

Intitialization

During the first run (or on QFQ update), the forms defined in Resources/Private/Form/* are imported. These are system forms and might be overwritten through QFQ when during QFQ updates.