Manual.rst

.. ==================================================
.. Header hierarchy
.. ==
..  --
..   ^^
..    ""
..     ;;
..      ,,
..
.. --------------------------------------------used to the update the records specified ------
.. Best Practice T3 reST: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html
..             Reference: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/Index.html
.. Italic *italic*
.. Bold **bold**
.. Code ``text``
.. External Links: `Bootstrap <http://getbootstrap.com/>`_
.. Add Images:    .. image:: ../images/a4.jpg
..
..
.. Admonitions
..       .. note::    .. important::     .. tip::      .. warning::
.. Color:   (grey)       (orange)           (green)      (red)
..
.. Definition:
.. some text becomes strong (only one line)
..      description has to indented

.. -*- coding: utf-8 -*- with BOM.


.. include:: Includes.txt

.. _general:

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:

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`.
* PDF decrypt (used for merge with pdfunite) - command `gs` - in case `qpdf` is not successful.
* Mime type detection for uploads - command `file`.


.. _`preparation`:

Preparation
-----------

Report & Form
^^^^^^^^^^^^^

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

* normalizer::normalize()

For the `download`_ function, the programs `pdfunite`, `qpdf`, `gs` 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 ghostscript # for file upload, PDF and 'HTML to PDF' (wkhtmltopdf), PDF split
  sudo apt install inkscape imagemagick            # to render thumbnails

.. _wkhtml:

wkhtmltopdf
^^^^^^^^^^^

`wkhtmltopdf <http://wkhtmltopdf.org/>`_ 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_.

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: `column-thumbnail`_.

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.