From aa83b26ce2d601617622d763650b242b159467dc Mon Sep 17 00:00:00 2001
From: Carsten Rose <carsten.rose@math.uzh.ch>
Date: Sun, 7 Mar 2021 23:24:47 +0100
Subject: [PATCH] Fix typo.
---
Documentation/Report.rst | 86 +++++++++++++++++++++++++++++++++++-----
1 file changed, 76 insertions(+), 10 deletions(-)
diff --git a/Documentation/Report.rst b/Documentation/Report.rst
index f431d2d47..31cf948e8 100644
--- a/Documentation/Report.rst
+++ b/Documentation/Report.rst
@@ -1944,20 +1944,45 @@ Output::
Download
--------
-Download offers:
++--------------------+--------------------------------------------------------+----------------------------------------+
+| Mode | Security | Note |
++====================+========================================================+========================================+
+| Direct File access | | Files are public available. No access restriction | | Use ``<a href="...">`` |
+| | | Pro: Simple, links can be copied. | | Merge multiple sources: no |
+| | | Con: Directory access, guess of filenames, only | but check :ref:`column-save-pdf` |
+| | removing the file will deny access. | | Custom 'save as filename': no |
++--------------------+--------------------------------------------------------+----------------------------------------+
+| Persistent Link | | Access is be defined by a SQL statement. In *T3/BE | | Use ``..., 'd:1234|s:0' AS _link`` |
+| | > Extension > QFQ > File > download* define a SQL | | Merge multiple sources: yes |
+| | statement. | | Custom 'save as filename': yes |
+| | | Pro: speaking URL, link can be copied, access can | |
+| | can be defined a SQL statement. | |
+| | | Con: **Key might be altered by user**, permission | |
+| | can't be user logged in dependent. | |
++--------------------+--------------------------------------------------------+----------------------------------------+
+| Secure Link | | **Default**. SIP protected link. | | Use ``..., 'd|F:file.pdf' AS _link`` |
+| | | Pro: Parameter can't be altered, most easy definition| | Merge multiple sources: yes |
+| | in QFQ, access might be logged in user dependent. | | Custom 'save as filename': yes |
+| | | Cons: Links are assigned to a browser session and | |
+| | can't be copied | |
++--------------------+--------------------------------------------------------+----------------------------------------+
+
+The rest of this section applies only to `Persistent Link` and `Secure Link`. Download offers:
* Single file - download a single file (any type),
* PDF create - one or concatenate several files (uploaded) and/or web pages (=HTML to PDF) into one PDF output file,
* ZIP archive - filled with several files ('uploaded' or 'HTML to PDF'-converted).
* Excel - created from scratch or fill a template xlsx with database values.
-The downloads are SIP protected. Only the current user can use the link to download files.
-
By using the `_link` column name:
-* the option `d:...` initiate creating the download link and optional specifies an export filename,
+* the option `d:...` initiate creating the download link and optional specifies
+
+ * in `SIP` mode: an export filename (),
+ * in `persistent link` mode: path download script (optional) and key(s) to identify the record with the PathFilename
+ information (see below).
+
* the optional `M:...` (Mode) specifies the export type (file, pdf, zip, export),
-* setting `s:1` is recommended for the download function (file / path name is hidden to the user),
* the alttext `a:...` specifies a message in the download popup.
By using `_pdf`, `_Pdf`, `_file`, `_File`, `_zip`, `_Zip`, `_excel` as column name, the options `d`, `M` and `s`
@@ -1966,16 +1991,12 @@ will be set.
All files will be read by PHP - therefore the directory might be protected against direct web access. This is the
preferred option to offer secure downloads via QFQ.
-In case the download needs a persistant URL (no SIP, no user session), a regular
-link, pointing directly to a file, have to be used - the download functionality described here is not appropriate for
-such a scenario. If necessary, :ref:`column-save-pdf` can be used to generate such a file.
-
.. _download-parameter-files:
Parameter and (element) sources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* *download*: `d[:<exportFilename>]`
+* mode `secure link` (s:1) - *download*: `d[:<exportFilename>]`
* *exportFilename* = <filename for save as> - Name, offered in the 'File save as' browser dialog. Default: 'output.<ext>'.
@@ -1983,6 +2004,51 @@ Parameter and (element) sources
The user typically expects meaningful and distinct file names for different download links.
+* mode `persistent link` (s:0) - *download*: `d:[<path/name>]<key1>[/<keyN>]`
+
+ This setup is divided in part a) and b):
+
+ Part a) - offering the download link.
+
+ * The whole part a) is optional. The download itself will work without it.
+
+ * (Optional) *path/name* = of the QFQ `download.php` script. By default``typo3conf/ext/qfq/Classes/Api/download.php``.
+ Three further possibilities: ``dl.php`` or ``dl2.php`` or ``dl3.php`` (see below).
+
+ * *key1* = give a uniq identifier to select the wished record.
+
+ Part b) - process the download
+
+ * In the QFQ extension config: File > Query for direct download mode: `download.php` or `dl.php` or `dl2.php` or `dl3.php`
+ up to 4 different SQL statements can be given with the regular QFQ download link syntax (skip the visual elements
+ like button, text, glyph icon, question,...)::
+
+ SELECT CONCAT('d|F:', n.pathFileName) FROM Note AS n WHERE n.id=?
+
+ All `?` in the SQL statement will be replaced by the specified parameter. If there are more `?` than parameter,
+ the last parameter will be reused for all pending `?`.
+
+ E.g. ``10.sql = SELECT 'd:1234|t:File.pdf' AS _link`` creates a link
+ ``<a href="typo3conf/ext/qfq/Classes/Api/download.php/1234"><span class="btn btn-default">File.pdf</span></span>``.
+ If the user clicks on the link, QFQ will extract the `1234` argument and via ``download.php`` the query (defined in
+ the Typo QFQ extension config) will be prepared and fires ``SELECT CONCAT('d|F:', n.pathFileName, '|t:File.pdf') FROM Note AS n WHERE n.id=1234``.
+ The download of the file, specified by ``n.pathFileName``, will start.
+
+ If no record ist selected, a custom error will be shown. If the query selectes more than one record, a general error will be shown.
+
+ If one of ``dl.php`` or ``dl2.php`` or ``dl3.php`` should be used, please initially create the symlink(s), e.g. in the
+ application directory (same level as typo3conf) ``ln -s typo3conf/ext/qfq/Classes/Api/download.php dl.php`` (or dl2.ph, dl3.php).
+
+ Speaking URL)
+
+ Instead of using a numeric value reference key, also a text can be used. Always take care that exactly one record is
+ selected. The key is transferred by URL therefore untrusted: The sanitize class :ref:`alnumx<sanitize-class>` is applied.
+ Example::
+
+ Query: SELECT CONCAT('d|F:', n.pathFileName) FROM Person AS p WHERE p.name=? AND p.firstName=? AND p.publish='yes'
+ Link: https://example.com/dl.php/doe/john
+
+
* *popupMessage*: `a:<text>` - will be displayed in the popup window during download. If the creating/download is fast, the window might disappear quickly.
* *mode*: `M:<mode>`
--
GitLab