Commit 9b1ef2ce authored by Carsten  Rose's avatar Carsten Rose
Browse files

Merge branch 'F11998CustomQFQ-Function' into 'develop'

F11998 custom qfq function

See merge request !321
parents 5744133f 92963fb7
Pipeline #5060 passed with stages
in 3 minutes and 39 seconds
...@@ -320,8 +320,8 @@ In :ref:`config-qfq-php` mutliple database credentials can be prepared. Mandator ...@@ -320,8 +320,8 @@ In :ref:`config-qfq-php` mutliple database credentials can be prepared. Mandator
`DB_1_USER`, `DB_1_SERVER`, `DB_1_PASSWORD`, `DB_1_NAME`. The number '1' indicates the `dbIndex`. Increment the number `DB_1_USER`, `DB_1_SERVER`, `DB_1_PASSWORD`, `DB_1_NAME`. The number '1' indicates the `dbIndex`. Increment the number
to specify further database credential setups. to specify further database credential setups.
Typically the credentials for `DB_1` also have access to the T3 database. By convention, it's necessary that `DB_1` is the one who also have access to the Typo3 database. E.q. `QFQ Function`_ or
download links (based on QFQ functions) needs access to the T3 database to directly fetch tt-content records.
Different QFQ versions, shared database Different QFQ versions, shared database
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
...@@ -173,11 +173,11 @@ Processing of the resulting rows and columns: ...@@ -173,11 +173,11 @@ Processing of the resulting rows and columns:
* In general, all columns of all rows will be printed out sequentially. * In general, all columns of all rows will be printed out sequentially.
* On a per column base, printing of columns can be suppressed by starting the column name with an underscore '_'. E.g. * On a per column base, printing of columns can be suppressed by starting the column name with an underscore '_'. E.g.
`SELECT id AS _id`. ``SELECT id AS _id``.
This might be useful to store values, which will be used later on in another query via the `{{id:R}}` or This might be useful to store values, which will be used later on in another query via the ``{{id:R}}`` or
`{{<level>.columnName}}` variable. To suppress printing of a column, use a underscore as column name prefix. E.g. ``{{<level>.columnName}}`` variable. To suppress printing of a column, use a underscore as column name prefix. E.g.
`SELECT id AS _id` ``SELECT id AS _id``
*Reserved column names* have a special meaning and will be processed in a special way. See *Reserved column names* have a special meaning and will be processed in a special way. See
:ref:`Processing of columns in the SQL result<Processing of columns in the SQL result>` for details. :ref:`Processing of columns in the SQL result<Processing of columns in the SQL result>` for details.
...@@ -489,8 +489,8 @@ Access column values ...@@ -489,8 +489,8 @@ Access column values
Columns of the upper / outer level result can be accessed via variables in two ways Columns of the upper / outer level result can be accessed via variables in two ways
* STORE_RECORD: `{{pId:R}}` * STORE_RECORD: ``{{pId:R}}``
* Level Key: `{{10.pId}}` * Level Key: ``{{10.pId}}``
The STORE_RECORD will always be merged with previous content. The Level Keys are unique. The STORE_RECORD will always be merged with previous content. The Level Keys are unique.
...@@ -507,7 +507,7 @@ Example:: ...@@ -507,7 +507,7 @@ Example::
10.sql = SELECT 'p:home&form=Person|s|b:success|t:Edit' AS _link 10.sql = SELECT 'p:home&form=Person|s|b:success|t:Edit' AS _link
10.20.sql = SELECT '{{link:R}}', '{{&link:R}}' 10.20.sql = SELECT '{{link:R}}', '{{&link:R}}'
The first column of row `10.20` returns 'p:home&form=Person|s|b:success|t:Edit',the second column returns The first column of row `10.20` returns `p:home&form=Person|s|b:success|t:Edit`,the second column returns
'<span class="btn btn-success"><a href="?home&s=badcaffee1234">Edit</a></span>'. '<span class="btn btn-success"><a href="?home&s=badcaffee1234">Edit</a></span>'.
Example STORE_RECORD:: Example STORE_RECORD::
...@@ -606,11 +606,11 @@ One exception are columns, whose name starts with '_'. E.g.:: ...@@ -606,11 +606,11 @@ One exception are columns, whose name starts with '_'. E.g.::
* The fourth column (alias name 'link') uses a QFQ special column name. Here, only in this example, it has no * The fourth column (alias name 'link') uses a QFQ special column name. Here, only in this example, it has no
further meaning. further meaning.
* All columns in a row, with the same special column name (e.g. ``... AS _page``) will have the same column name: 'page'. * All columns in a row, with the same special column name (e.g. ``... AS _page``) will have the same column name: 'page'.
To access individual columns a uniq column title is necessary and can be added ``|_column1``:: To access individual columns a uniq column title is necessary and can be added ``...|column1``::
10.sql = SELECT '..1..' AS '_page|column1', '..2..' AS '_page|column2' 10.sql = SELECT '..1..' AS '_page|column1', '..2..' AS '_page|column2'
Those columns can be accessed via ``{{10.column1}}`` , ``{{10.column2}}`` or (recommended) ``{{column1:R}}`` , ``{{column2:R}}`` Those columns can be accessed via ``{{column1:R}}`` , ``{{column2:R}}`` (recommended) or ``{{10.column1}}`` , ``{{10.column2}}``.
* To skip wrapping via ``fbeg``, ``fsep``, ``fend`` for dedicated columns, add the keyword ``|_noWrap`` to the column alias. * To skip wrapping via ``fbeg``, ``fsep``, ``fend`` for dedicated columns, add the keyword ``|_noWrap`` to the column alias.
Example:: Example::
...@@ -618,17 +618,17 @@ One exception are columns, whose name starts with '_'. E.g.:: ...@@ -618,17 +618,17 @@ One exception are columns, whose name starts with '_'. E.g.::
Summary: Summary:
.. note::
* Special column names always start with '_'. * For 'special column names': the column name together with the value controls how QFQ processes the column.
* Columns starting with a '_' but not defined as as QFQ special column name are hidden(!) - in other words: they are * Special column names always start with '_'.
not **printed** as output. * Important: to reference a column, the name has to be given without '_'. E.g. ``SELECT 'cat' AS _pet`` will be used with
* SQL hint: If there is no column alias defined, the column name becomes the value ``{{pet:R}}`` (notice the missing '_').
of the first row. E.g. if the first selected row contains a '_' as the first * Columns starting with a '_' but not defined as as QFQ special column name are hidden(!) - in other words: they are
character, the column name becomes '_....' - which will be hidden! To be safe: always define an alias! not **printed** as output.
* Access to 'hidden' columns via ``{{<level>.<column>}}`` or ``{{<column>:R}}`` are possible and often used. * Tip: if a column name starts with '_' the column name becomes '_....' - which will be hidden! To be safe: always
* Important: to reference a column, the name has to be given without '_'. E.g. ``SELECT 'cat' AS _pet`` will be used with define an alias!
``{{pet:R}}`` (notice the missing '_'). * Access to 'hidden' columns via ``{{<level>.<column>}}`` or ``{{<column>:R}}`` are possible and often used.
* For 'special column names': the column name together with the value controls how QFQ processes the column.
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Reserved column name | Purpose | | Reserved column name | Purpose |
...@@ -687,13 +687,14 @@ Summary: ...@@ -687,13 +687,14 @@ Summary:
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| _XLSn |Used for Excel export. Prepend 'n=' and append a `newline` character around the string. See :ref:`excel-export`. | | _XLSn |Used for Excel export. Prepend 'n=' and append a `newline` character around the string. See :ref:`excel-export`. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| _noWrap |Skip wrapping via `fbeg`, ``fsep``, ``fend``. | | _noWrap |Skip wrapping via ``fbeg``, ``fsep``, ``fend``. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| _hide |Column is hidden. | | _hide |Hide a column with a special column name (like ``... AS _link``). Note: regular columns should be hidden by using '_' as the first letter of the column name. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| _+<html-tag attributes>|The content will be wrapped with '<html-tag attributes>'. Example: SELECT 'example' AS '_+a href="http://example.com"' creates '<a href="http://example.com">example</a>' | | _+<html-tag attributes>|The content will be wrapped with '<html-tag attributes>'. Example: ``SELECT 'example' AS '_+a href="http://example.com"'`` creates ``'<a href="http://example.com">example</a>'`` |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| _=<varname> |The content will be saved in store 'user' under 'varname'. Retrieve it later via {{varname:U}}. Example: 'SELECT "Hello world" AS _=text'. See :ref:`STORE_USER`, :ref:`store_user_examples` | | _=<varname> |The content will be saved in store 'user' under 'varname'. Retrieve it later via ``{{varname:U}}``. Example: ``'SELECT "Hello world" AS _=text'``. |
| |See :ref:`STORE_USER`, :ref:`store_user_examples` |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|_<nonReservedName> |Suppress output. Column names with leading underscore are used to select data from the database and make it available in other parts of the report without generating any output. | |_<nonReservedName> |Suppress output. Column names with leading underscore are used to select data from the database and make it available in other parts of the report without generating any output. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
...@@ -704,10 +705,10 @@ Column: _link ...@@ -704,10 +705,10 @@ Column: _link
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
* Most URLs will be rendered via class link. * Most URLs will be rendered via class link.
* Column names like `_pagee`, `_mailto`, ... are wrapper to class link. * Column names like ``_pagee`, ``_mailto``, ... are wrapper to class link.
* The parameters for link contains a prefix to make them position-independent. * The parameters for link contains a prefix to make them position-independent.
* Parameter have to be separated with '|'. If '|' is part of the value, it needs to be escaped '\\|'. This can be done * Parameter have to be separated with '|'. If '|' is part of the value, it needs to be escaped '\\|'. This can be done
via QFQ SQL function `QBAR()` - see :ref:`qbar-escape-qfq-delimiter`. via QFQ SQL function ``QBAR()`` - see :ref:`qbar-escape-qfq-delimiter`.
+---+---+--------------+-----------------------------------+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ +---+---+--------------+-----------------------------------+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------+
|URL|IMG|Meaning |Qualifier |Example |Description | |URL|IMG|Meaning |Qualifier |Example |Description |
...@@ -1017,16 +1018,16 @@ references are not found, if they use different colummnnames or tablenames. ...@@ -1017,16 +1018,16 @@ references are not found, if they use different colummnnames or tablenames.
Mode: table Mode: table
""""""""""" """""""""""
* `table=<table name>` * ``table=<table name>``
* `r=<record id>` * ``r=<record id>``
Deletes the record with id '<record id>' from table '<table name>'. Deletes the record with id '<record id>' from table '<table name>'.
Mode: form Mode: form
"""""""""" """"""""""
* `form=<form name>` * ``form=<form name>``
* `r=<record id>` * ``r=<record id>``
Deletes the record with id '<record id>' from the table specified in form '<form name>' as primary table. Deletes the record with id '<record id>' from the table specified in form '<form name>' as primary table.
Additional action *FormElement* of type *beforeDelete* or *afterDelete* will be fired too. Additional action *FormElement* of type *beforeDelete* or *afterDelete* will be fired too.
...@@ -1044,7 +1045,7 @@ Examples ...@@ -1044,7 +1045,7 @@ Examples
Columns: _Page[X] Columns: _Page[X]
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
* Similar to `_page[X]` * Similar to ``_page[X]``
* Parameter are position dependent and therefore without a qualifier! * Parameter are position dependent and therefore without a qualifier!
:: ::
...@@ -1056,7 +1057,7 @@ Columns: _Page[X] ...@@ -1056,7 +1057,7 @@ Columns: _Page[X]
Column: _Paged Column: _Paged
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
* Similar to `_paged` * Similar to ``_paged``
* Parameter are position dependent and therefore without a qualifier! * Parameter are position dependent and therefore without a qualifier!
:: ::
...@@ -1416,7 +1417,7 @@ Run a php function defined in an external script. ...@@ -1416,7 +1417,7 @@ Run a php function defined in an external script.
* If the function returns an associative array, then the **key-value pairs will be accessible via the VARS store `V`**. * If the function returns an associative array, then the **key-value pairs will be accessible via the VARS store `V`**.
* If the function throws an **exception** then a standard QFQ error message is shown. * If the function throws an **exception** then a standard QFQ error message is shown.
* Text sent to 'stderr' by the php function is not returned at all. * Text sent to 'stderr' by the php function is not returned at all.
* The script has access to the following **qfq functions** using the interface (see examples below): * The script has access to the following **qfq php functions** using the interface (see examples below):
* $qfq::apiCall($method, $url, $data = '', $header = [], $timeout = 5) * $qfq::apiCall($method, $url, $data = '', $header = [], $timeout = 5)
* arguments: * arguments:
* string $method: can be PUT/POST/GET/DELETE * string $method: can be PUT/POST/GET/DELETE
...@@ -1510,9 +1511,9 @@ Most of the other Link-Class attributes can be used to customize the link. :: ...@@ -1510,9 +1511,9 @@ Most of the other Link-Class attributes can be used to customize the link. ::
* Parameter are position independent. * Parameter are position independent.
* *<params>*: see :ref:`download-parameter-files` * *<params>*: see :ref:`download-parameter-files`
* For column `_pdf` and `_zip`, the element sources `p:...`, `U:...`, `u:...`, `F:...` might repeated multiple times. * For column ``_pdf`` and ``_zip``, the element sources ``p:...``, ``U:...``, ``u:...``, ``F:...`` might repeated multiple times.
* For column `_zip`, an optional parameter might define the path and filename inside the ZIP: `F:<orig filename>:<inside ZIP path and filename>` * For column ``_zip``, an optional parameter might define the path and filename inside the ZIP: `F:<orig filename>:<inside ZIP path and filename>`
* To only render the page content without menus add the parameter `type=2`. For example: `U:id=pageToPrint&type=2&_sip=1&r=', r.id` * To only render the page content without menus add the parameter ``type=2``. For example: ``U:id=pageToPrint&type=2&_sip=1&r=', r.id``
* Example:: * Example::
# ... AS _file # ... AS _file
...@@ -1547,8 +1548,8 @@ Column: _savePdf ...@@ -1547,8 +1548,8 @@ Column: _savePdf
Generated PDFs can be stored directly on the server with this functionality. The link query consists of the following parameters: Generated PDFs can be stored directly on the server with this functionality. The link query consists of the following parameters:
* One or more element sources (such as `F:`, `U:`, `p:`, see :ref:`download-parameter-files`), including possible wkhtmltopdf parameters * One or more element sources (such as ``F:``, ``U:``, ``p:``, see :ref:`download-parameter-files`), including possible wkhtmltopdf parameters
* The export filename and path as `d:` - for security reasons, this path has to start with *fileadmin/* and end with *.pdf*. * The export filename and path as ``d:`` - for security reasons, this path has to start with *fileadmin/* and end with *.pdf*.
Tips: Tips:
...@@ -1569,12 +1570,12 @@ Example:: ...@@ -1569,12 +1570,12 @@ Example::
Column: _thumbnail Column: _thumbnail
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
For file `T:<pathFileName>` a thumbnail will be rendered, saved (to be reused) and a HTML `<img>` tag is returned, For file ``T:<pathFileName>`` a thumbnail will be rendered, saved (to be reused) and a HTML ``<img>`` tag is returned,
With the SIP encoded thumbnail. With the SIP encoded thumbnail.
The thumbnail: The thumbnail:
* Size is specified via `W:<dimension>`. The file is only rendered once and subsequent access is delivered via a local QFQ cache. * Size is specified via ``W:<dimension>``. The file is only rendered once and subsequent access is delivered via a local QFQ cache.
* Will be rendered, if the source file is newer than the thumbnail or if the thumbnail dimension changes. * Will be rendered, if the source file is newer than the thumbnail or if the thumbnail dimension changes.
* The caching is done by building the MD5 of pathFileName and thumbnail dimension. * The caching is done by building the MD5 of pathFileName and thumbnail dimension.
* Of multi page files like PDFs, the first page is used as the thumbnail. * Of multi page files like PDFs, the first page is used as the thumbnail.
...@@ -1584,7 +1585,7 @@ used. Office file formats are not supported. Due to speed and quality reasons, S ...@@ -1584,7 +1585,7 @@ used. Office file formats are not supported. Due to speed and quality reasons, S
If a file format is not known, QFQ tries to show a corresponding file type image provided by Typo3 - such an image is not If a file format is not known, QFQ tries to show a corresponding file type image provided by Typo3 - such an image is not
scaled. scaled.
In :ref:`configuration` the exact location of `convert` and `inkscape` can be configured (optional) as well as the directory In :ref:`configuration` the exact location of ``convert`` and ``inkscape`` can be configured (optional) as well as the directory
names for the cached thumbnails. names for the cached thumbnails.
+-------+--------------------------------+----------------------------------------------------------------------------+ +-------+--------------------------------+----------------------------------------------------------------------------+
...@@ -1595,15 +1596,15 @@ names for the cached thumbnails. ...@@ -1595,15 +1596,15 @@ names for the cached thumbnails.
| W | W:200x, W:x100, W:200x100 | Dimension of the thumbnail: '<width>x<height>. Both | | W | W:200x, W:x100, W:200x100 | Dimension of the thumbnail: '<width>x<height>. Both |
| | | parameter are otional. If non is given the default is W:150x | | | | parameter are otional. If non is given the default is W:150x |
+-------+--------------------------------+----------------------------------------------------------------------------+ +-------+--------------------------------+----------------------------------------------------------------------------+
| s | s:1, s:0 | Optional. Default: `s:1`. If SIP is enabled, the rendered URL | | s | s:1, s:0 | Optional. Default: ``s:1``. If SIP is enabled, the rendered URL |
| | | is a link via `api/download.php?..`. Else a direct pathFileName. | | | | is a link via ``api/download.php?..``. Else a direct pathFileName. |
+-------+--------------------------------+----------------------------------------------------------------------------+ +-------+--------------------------------+----------------------------------------------------------------------------+
| r | r:7 | Render Mode. Default 'r:0'. With 'r:7' only the url will be delivered. | | r | r:7 | Render Mode. Default 'r:0'. With 'r:7' only the url will be delivered. |
+-------+--------------------------------+----------------------------------------------------------------------------+ +-------+--------------------------------+----------------------------------------------------------------------------+
The render mode '7' is useful, if the URL of the thumbnail have to be used in another way than the provided html-'<img>' The render mode '7' is useful, if the URL of the thumbnail have to be used in another way than the provided html-'<img>'
tag. Something like `<body style="background-image:url(bgimage.jpg)">` could be solved with tag. Something like ``<body style="background-image:url(bgimage.jpg)">`` could be solved with
`SELECT "<body style="background-image:url(", 'T:fileadmin/file3.pdf' AS _thumbnail, ')">'` ``SELECT "<body style="background-image:url(", 'T:fileadmin/file3.pdf' AS _thumbnail, ')">'``
Example:: Example::
...@@ -1839,7 +1840,7 @@ Example:: ...@@ -1839,7 +1840,7 @@ Example::
10.sql = SELECT CONCAT('p:notes|t:Information: ', QBAR(Note.title), '|b') AS _link FROM Note 10.sql = SELECT CONCAT('p:notes|t:Information: ', QBAR(Note.title), '|b') AS _link FROM Note
In case 'Note.title' contains a '|' (like 'fruit | numbers'), it will confuse the '... AS _link' class. Therefore it's In case 'Note.title' contains a '|' (like 'fruit | numbers'), it will confuse the '... AS _link' class. Therefore it's
necessary to 'escape' (adding a '\' in front of the problematic character) the bar which is done by using `QBAR()`. necessary to 'escape' (adding a '\' in front of the problematic character) the bar which is done by using ``QBAR()``.
.. _qbar-escape-qfq-colon-coma: .. _qbar-escape-qfq-colon-coma:
...@@ -1939,6 +1940,86 @@ Output:: ...@@ -1939,6 +1940,86 @@ Output::
my name is john - end of sentence my name is john - end of sentence
.. _qfq_function:
QFQ Function
------------
QFQ SQL reports can be reused, similar to a function in a regular programming language, including call parameter and return
values.
* Per tt-content record the field 'subheader' (in Typo3 backend) defines the function name. The function
can also referenced by using the tt-content number (`uid`) - but this is less readable.
* The calling report calls the function by defining ``<level>.function = <function name>(var1, var2, ...) => return1, return2, ...``
* STORE_RECORD will be saved before calling the function and will be restored when the function has been finished.
* The function has only access to STORE_RECORD variables which has been explicitly defined in the braces (var1, var2, ...).
* The function return values will be copied to STORE_RECORD after the function finished.
* Inside the QFQ function, all other STORES are fully available.
* If ``<level>.function`` and ``<level>.sql`` are both given, ``<level>.function`` is processed first.
* If ``<level>.function`` is given, but ``<level>.sql`` not, the values of ``shead, stail, althead`` are even processed.
* If a function outputs something, this is *not* shown.
* The output of a QFQ function is accessible via ``{{_output:R}}``.
* It is possible to call functions inside of a function.
* If ``render = api`` is defined in the function, both tt-content records can be saved on the *same* page and won't interfere.
Example tt-content record for the function::
Subheader: getFirstName
Code:
#
# {{pId:R}}
#
render = api
100 {
  sql = SELECT p.firstName AS _firstName
               , NOW() AS now, CONCAT('p:{{pageAlias:T}}&form=person&r=', p.id ) AS '_pagee|_hide|myLink'            
          FROM Person AS p
          WHERE p.id={{pId:R}}
}                       
Example tt-content record for the calling report::
#
# Example how to use `<level>.function = ...`
#
10 {
  sql = SELECT p.id AS _pId, p.name FROM Person AS p ORDER BY p.name
  head = <table class="table"><tr><th>Name</th><th>Firstname</th><th>Link (final)</th><th>Link (source)</th><th>NOW() (via Output)</th></tr>
  tail = </table>
  rbeg = <tr>
  renr = </tr>
  fbeg = <td>
  fend = </td>
                                                                    
  20 {
    function = getFirstName(pId) => firstName, myLink    
  }
                                                                    
  30 {
    sql = SELECT '{{firstName:R}}', "{{myLink:R}}", "{{&myLink:R}}", '{{_output:R}}'
    fbeg = <td>
    fend = </td>
  }
}                                                                    
Explanation:
* Level 10 iterates over all `person`.
* Level 10.20 calls QFQ function `getFirstName()` by delivering the `pId` via STORE_RECORD. The function expects the return
value `firstName` and `myLink`.
* The function selects in level 100 the person given by ``{{pId:R}}``. The `firstName` is not printed but a hidden column.
Column ``now`` is printed. Column 'myLink' is a rendered link, but not printed.
* Level 10.30 prints the return values ``firstName`` and ``myLink`` (as rendered link and as source definition). The last
column is the output of the function - the value of ``NOW()``
.. tip::
If there are STORE_RECORD variables which can't be replaced: typically they have been not defined as function parameter
or return values.
.. _download: .. _download:
Download Download
...@@ -1974,29 +2055,29 @@ The rest of this section applies only to `Persistent Link` and `Secure Link`. Do ...@@ -1974,29 +2055,29 @@ The rest of this section applies only to `Persistent Link` and `Secure Link`. Do
* ZIP archive - filled with several files ('uploaded' or 'HTML to PDF'-converted). * ZIP archive - filled with several files ('uploaded' or 'HTML to PDF'-converted).
* Excel - created from scratch or fill a template xlsx with database values. * Excel - created from scratch or fill a template xlsx with database values.
By using the `_link` column name: By using the ``_link`` column name:
* the option `d:...` initiate creating the download link and optional specifies * the option ``d:...`` initiate creating the download link and optional specifies
* in `SIP` mode: an export filename (), * in ``SIP`` mode: an export filename (),
* in `persistent link` mode: path download script (optional) and key(s) to identify the record with the PathFilename * in ``persistent link`` mode: path download script (optional) and key(s) to identify the record with the PathFilename
information (see below). information (see below).
* the optional `M:...` (Mode) specifies the export type (file, pdf, zip, export), * the optional ``M:...`` (Mode) specifies the export type (file, pdf, zip, export),
* the alttext `a:...` specifies a message in the download popup. * 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` By using ``_pdf``, ``_Pdf``, ``_file``, ``_File``, ``_zip``, ``_Zip``, ``_excel`` as column name, the options `d`, `M` and `s`
will be set. will be set.
All files will be read by PHP - therefore the directory might be protected against direct web access. This is the 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. preferred option to offer secure downloads via QFQ. Check `secure-direct-file-access`_.
.. _download-parameter-files: .. _download-parameter-files:
Parameter and (element) sources Parameter and (element) sources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* mode `secure link` (s:1) - *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>'. * *exportFilename* = <filename for save as> - Name, offered in the 'File save as' browser dialog. Default: 'output.<ext>'.
...@@ -2049,34 +2130,34 @@ Parameter and (element) sources ...@@ -2049,34 +2130,34 @@ Parameter and (element) sources
Link: https://example.com/dl.php/doe/john 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. * *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>` * *mode*: ``M:<mode>``
* *mode* = <file | pdf | zip | excel> * *mode* = <file | pdf | zip | excel>
* If `M:file`, the mime type is derived dynamically from the specified file. In this mode, only one element source * If ``M:file``, the mime type is derived dynamically from the specified file. In this mode, only one element source
is allowed per download link (no concatenation). is allowed per download link (no concatenation).
* In case of multiple element sources, only `pdf`, `zip` and `excel` (template mode) is supported. * In case of multiple element sources, only `pdf`, `zip` and `excel` (template mode) is supported.
* If `M:zip` is used together with `p:...`, `U:...` or `u:..`, those HTML pages will be converted to PDF. Those files * If ``M:zip`` is used together with `p:...`, `U:...` or `u:..`, those HTML pages will be converted to PDF. Those files
get generic filenames inside the archive. get generic filenames inside the archive.
* If not specified, the **default** 'Mode' depends on the number of specified element sources (=file or web page): * If not specified, the **default** 'Mode' depends on the number of specified element sources (=file or web page):
* If only one `file` is specified, the default is `file`. * If only one `file` is specified, the default is `file`.
* If there is a) a page defined or b) multiple elements, the default is `pdf`. * If there is a) a page defined or b) multiple elements, the default is `pdf`.
* *element sources* - for `M:pdf` or `M:zip`, all of the following element sources may be specified multiple times. * *element sources* - for ``M:pdf`` or ``M:zip``, all of the following element sources may be specified multiple times.
Any combination and order of these options are allowed. Any combination and order of these options are allowed.
* *file*: `F:<pathFileName>` - relative or absolute pathFileName offered for a) download (single), or to be concatenated * *file*: ``F:<pathFileName>`` - relative or absolute pathFileName offered for a) download (single), or to be concatenated
in a PDF or ZIP. in a PDF or ZIP.
* *page*: `p:id=<t3 page>&<key 1>=<value 1>&<key 2>=<value 2>&...&<key n>=<value n>`. * *page*: ``p:id=<t3 page>&<key 1>=<value 1>&<key 2>=<value 2>&...&<key n>=<value n>``.
* By default, the options given to wkhtml will *not* be encoded by a SIP! * By default, the options given to wkhtml will *not* be encoded by a SIP!
* To encode the parameter via SIP: Add '_sip=1' to the URL GET parameter. * To encode the parameter via SIP: Add '_sip=1' to the URL GET parameter.
E.g. `p:id=form&_sip=1&form=Person&r=1`. E.g. ``p:id=form&_sip=1&form=Person&r=1``.
In that way, specific sources for the `download` might be SIP encrypted. In that way, specific sources for the `download` might be SIP encrypted.
...@@ -2085,13 +2166,31 @@ Parameter and (element) sources ...@@ -2085,13 +2166,31 @@ Parameter and (element) sources
* If there are trouble with accessing FE_GROUP protected content, please check :ref:`wkhtmltopdf<wkhtml>`. * If there are trouble with accessing FE_GROUP protected content, please check :ref:`wkhtmltopdf<wkhtml>`.
* *url*: `u:<url>` - any URL, pointing to an internal or external destination. * *url*: ``u:<url>`` - any URL, pointing to an internal or external destination.
* *uid*: `uid:<tt-content record id>` - the tt_content.uid of a QFQ PageContent record (shown on hover in the backend). This will render * *uid*: ``uid:<function name>`` - the output is treated as HTML (will be converted to PDF) or EXCEL data.
only the specified QFQ content record, without any Typo3 layout elements (Menu, Body,...)
QFQ will retrieve the tt-content's bodytext from the Typo3 database, parse it, and render it as a PDF. Parameters can be * The called tt-content record is identified by `function name`, specified in the subheader field. Optional
passed: `uid:<tt-content record id>[&arg1=value1][&arg2=value2][...]` and will be available in the SIP store for the QFQ PageContent, the numeric id of the tt-content record (=uid) can be given.
or passed as wkhtmltopdf arguments, if applicable. * Only the specified QFQ content record will be rendered, without any Typo3 layout elements (Menu, Body,...)
* QFQ will retrieve the tt-content's bodytext from the Typo3 database, parse it, and render it as a PDF or Execl data.
* Parameters can be passed: ``uid:<tt-content record id>[&arg1=value1][&arg2=value2][...]`` and will be available via
STORE_SIP in the QFQ PageContent, or passed as wkhtmltopdf arguments, if applicable.
* For more obviously structuring, put the additional tt-content record on the same Typo3 page (where the QFQ
tt-content record is located which produces the link) and specify ``render = api`` (`report-render`_).
* *source*: ``source:<function name>[&arg1=value1][&arg2=value2][&...]`` - (similar to a `uid`) the output is treated
as further sources. Example result reported by *function name* might be: ``F:file.pdf1|uid:myData&arg=2|...``
* Use this functionality to define a *central managed download* function, which can be reused anywhere by just specify the
*function name* and required arguments.
* The called tt-content record is identified by `function name`, specified in the subheader field. Optional
the numeric id of the tt-content record (=uid) can be given.
* The output of the tt-content record will be treated as further source arguments. Nothing else than valid source
references should be printed. Separate the references as usual by '|'.
* The supplied arguments are available via STORE_SIP (this is different from `qfq_function`_).
* Tip: For more obviously structuring, put the additional tt-content record on the same Typo3 page (where the QFQ
tt-content record is located which produces the link) and specify ``render = api`` (`report-render`_).
* *WKHTML Options* for `page`, `urlParam` or `url`: * *WKHTML Options* for `page`, `urlParam` or `url`:
...@@ -2127,6 +2226,12 @@ Example `_link`: :: ...@@ -2127,6 +2226,12 @@ Example `_link`: ::
# One source and a header file. Note: the parameter to the header URL is escaped with double backslash. # One source and a header file. Note: the parameter to the header URL is escaped with double backslash.
SELECT "d:complete.pdf|s|t:Complete PDF|p:id=detail2&r=1&--orientation=Landscape&--header={{URL:R}}?indexp.php?id=head\\&L=1|F:fileadmin/pdf/test.pdf" AS _link SELECT "d:complete.pdf|s|t:Complete PDF|p:id=detail2&r=1&--orientation=Landscape&--header={{URL:R}}?indexp.php?id=head\\&L=1|F:fileadmin/pdf/test.pdf" AS _link
# One indirect source reference
SELECT "d:complete.pdf|s|t:Complete PDF|source:centralPdf&pId=1234" AS _link
An additional tt-content record is defined with `sub header: centralPdf`. One or multiple attachments might be concatenated.
10.sql = SELECT '|F:', a.pathFileName FROM Attachments AS a WHERE a.pId={{pId:S}}
.. ..
Example `_pdf`, `_zip`: :: Example `_pdf`, `_zip`: ::
...@@ -2306,13 +2411,13 @@ Setup ...@@ -2306,13 +2411,13 @@ Setup
* Create a T3 PageContent which delivers the content. * Create a T3 PageContent which delivers the content.
* It is recommended to use the `uid:<tt-content record id>` syntax for excel imports, because there should be no html code on the * It is recommended to use the ``uid:<tt-content record id>`` syntax for excel imports, because there should be no html code on the
resulting content. QFQ will retrieve the PageContent's bodytext from the Typo3 database, parse it, and pass the resulting content. QFQ will retrieve the PageContent's bodytext from the Typo3 database, parse it, and pass the
result as the instructions for filling the excel file. result as the instructions for filling the excel file.
* Parameters can be passed: `uid:<tt-content record id>?param=<value1>&param2=<value2>` and will be accessible in the SIP Store (S) in the * Parameters can be passed: ``uid:<tt-content record id>?param=<value1>&param2=<value2>`` and will be accessible in the SIP Store (S) in the
QFQ PageContent. QFQ PageContent.
* Use the regular QFQ Report syntax to create output. * Use the regular QFQ Report syntax to create output.
* The newline at the end of every line needs to be CHAR(10). To make it simpler, the special column name `... AS _XLS` * The newline at the end of every line needs to be CHAR(10). To make it simpler, the special column name ``... AS _XLS``
(see _XLS, _XLSs, _XLSb, _XLSn) can be used. (see _XLS, _XLSs, _XLSb, _XLSn) can be used.
* One option per line. * One option per line.
* Empty lines will be skipped. * Empty lines will be skipped.
...@@ -2440,18 +2545,21 @@ This defines a menu (three vertical buttons) - a click on it shows two menu entr ...@@ -2440,18 +2545,21 @@ This defines a menu (three vertical buttons) - a click on it shows two menu entr