From 4d46add8e2ef663665da37f64c46b475ee6113ab Mon Sep 17 00:00:00 2001
From: crose <carsten.rose@math.uzh.ch>
Date: Wed, 20 Feb 2019 18:06:26 +0100
Subject: [PATCH] Manual.rst: test some markup styles
---
extension/Documentation/Manual.rst | 95 +++++++++++++++++-------------
1 file changed, 55 insertions(+), 40 deletions(-)
diff --git a/extension/Documentation/Manual.rst b/extension/Documentation/Manual.rst
index f5b7e17d9..2bd919bd8 100644
--- a/extension/Documentation/Manual.rst
+++ b/extension/Documentation/Manual.rst
@@ -12,6 +12,9 @@
.. External Links: `Bootstrap <http://getbootstrap.com/>`_:
.. Add Images: https://wiki.typo3.org/ReST_Syntax#Images ...
..
+.. Admonitions (https://docs.typo3.org/typo3cms/drafts/github/xperseguers/RstPrimer/#admonitions)
+.. .. note:: .. important:: .. tip:: .. warning::
+..
.. -*- coding: utf-8 -*- with BOM.
@@ -384,7 +387,7 @@ Extension Manager: QFQ Configuration
+-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
| formSubmitLogMode | all | | *all*: every form submission will be logged. |
| | | | *none*: no logging. |
-| | | | See `Form Submit Log page`_ for example QFQ code to display the log. |
+| | | | See `form-submit-log-page`_ for example QFQ code to display the log. |
+-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
| redirectAllMailTo | john@doe.com | If set, redirect all QFQ generated mails (Form, Report) to the specified. |
+-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
@@ -610,7 +613,8 @@ To get the name and current period: ::
Typically, it's necessary to offer a 'previous' / 'next' link. In this example, the STORE SIP holds the new periodId: ::
- SELECT CONCAT('p:{{pageAlias:T}}&periodId=', {{periodId:SY0}}-1, '|Next') AS _page, ' ', name, ' ', CONCAT('p:{{pageAlias:T}}&periodId=', {{periodId:SY0}}+1, '|Next') AS _page FROM Period AS s WHERE s.id={{periodId:SY0}}
+ SELECT CONCAT('p:{{pageAlias:T}}&periodId=', {{periodId:SY0}}-1, '|Next') AS _page, ' ', name, ' ',
+ CONCAT('p:{{pageAlias:T}}&periodId=', {{periodId:SY0}}+1, '|Next') AS _page FROM Period AS s WHERE s.id={{periodId:SY0}}
Take care for minimum and maximum indexes (do not render the links if out of range).
@@ -823,7 +827,7 @@ System tables
| Split | Persistent | Data |
+---------------+------------+------------+
-See `Mail Log page`_ and `Form Submit Log page`_ for some Frontend views for these tables.
+See `mail-log-page`_ and `form-submit-log-page`_ for some Frontend views for these tables.
* Check Bug #5459 - support of system tables in different DBs not supported.
@@ -922,7 +926,7 @@ Debug
SQL Logging
-----------
-configuration_
+Setup in configuration_
.. _SQL_LOG:
@@ -970,14 +974,14 @@ configuration_
* *download*:
* During a download (especially by using wkhtml), temporary files are not deleted automatically. Also the
- `wkhtmltopdf` and `pdftk` commandlines will be logged to `SQL_LOG`_. Use this only to debug problems on download.
+ ``wkhtmltopdf`` and ``pdftk`` commandlines will be logged to `SQL_LOG`_. Use this only to debug problems on download.
.. _REDIRECT_ALL_MAIL_TO:
Redirect all mail to (catch all)
--------------------------------
-configuration_
+Setup in configuration_
* *redirectAllMailTo=john@doe.com*
@@ -990,7 +994,7 @@ configuration_
* Clear 'CC' and 'Bcc'
* Write a note and the original configured receiver at the top of the email body.
-_`Mail Log page`
+_`mail-log-page`
Mail Log page
-------------
@@ -1008,7 +1012,8 @@ The following QFQ code could be used for that purpose (put it in a QFQ PageConte
FROM gGroup AS gr
INNER JOIN MailLog AS ml ON ml.grId = gr.id
GROUP BY gr.id
- head = <form onchange='this.submit();' class='form-inline'><input type='hidden' name='id' value='{{pageAlias:T0}}'>Filter By Group: <select name='grId' class='form-control'><option value=''></option>
+ head = <form onchange='this.submit();' class='form-inline'><input type='hidden' name='id' value='{{pageAlias:T0}}'>
+ Filter By Group: <select name='grId' class='form-control'><option value=''></option>
rbeg = <option value='
rend = </option>
tail = </select>
@@ -1024,17 +1029,20 @@ The following QFQ code could be used for that purpose (put it in a QFQ PageConte
sql = SELECT id, '</td><td>', grId, '</td><td>', xId, '</td><td>',
REPLACE(receiver, ',', '<br>'), '</td><td>', REPLACE(sender, ',', '<br>'), '</td><td>',
DATE_FORMAT(modified, '%d.%m.%Y<br>%H:%i:%s'), '</td><td style="word-break:break-word;">',
- CONCAT('<b>', subject, '</b><br>', IF(@summary = 'true', CONCAT(SUBSTR(body, 1, LEAST(IF(INSTR(body, '\n') = 0, 50, INSTR(body, '\n')), IF(INSTR(body, '<br>') = 0, 50, INSTR(body, '<br>')))-1), ' ...'), CONCAT('<br>', REPLACE(body, '\n', '<br>'))) )
+ CONCAT('<b>', subject, '</b><br>', IF(@summary = 'true', CONCAT(SUBSTR(body, 1,
+ LEAST(IF(INSTR(body, '\n') = 0, 50, INSTR(body, '\n')), IF(INSTR(body, '<br>') = 0, 50,
+ INSTR(body, '<br>')))-1), ' ...'), CONCAT('<br>', REPLACE(body, '\n', '<br>'))) )
FROM MailLog WHERE (grId = @grId OR @grId = 0)
ORDER BY modified DESC
LIMIT 100
- head = <table class="table table-condensed table-hover"><tr><th>Id</th><th>grId</th><th>xId</th><th>To</th><th>From</th><th>Date</th><th>E-Mail</th></tr>
+ head = <table class="table table-condensed table-hover"><tr>
+ <th>Id</th><th>grId</th><th>xId</th><th>To</th><th>From</th><th>Date</th><th>E-Mail</th></tr>
tail = </table>
rbeg = <tr><td>
rend = </td></tr>
}
-_`Form Submit Log page`
+_`form-submit-log-page`
Form Submit Log page
--------------------
@@ -7464,7 +7472,8 @@ to edit `AutoCron` jobs: ::
10 {
# Table header.
- sql = SELECT CONCAT('p:{{pageAlias:T}}&form=cron') AS _pagen, 'id', 'Next run','Frequency','Comment','Last run','In progress', 'Status' FROM (SELECT 1) AS fake WHERE '{{form:SE}}'=''
+ sql = SELECT CONCAT('p:{{pageAlias:T}}&form=cron') AS _pagen, 'id', 'Next run','Frequency','Comment',
+ 'Last run','In progress', 'Status' FROM (SELECT 1) AS fake WHERE '{{form:SE}}'=''
head = <table class='table table-hover qfq-table-50'>
tail = </table>
rbeg = <thead><tr>
@@ -7605,31 +7614,31 @@ QFQ offers an API endpoint for GET (and later POST,PUT,DELETE) operations. ::
<domain>/typo3conf/ext/qfq/Source/api/rest.php/<level1>/<id1>/<level2>/<id2>/.../?<var1>=<value1>&...
-Append level names and ids after 'rest.php/...', separated by '/' each.
+Append level names and ids after `rest.php/...`, separated by '/' each.
E.g.:
-a) List of all persons: <domain>/typo3conf/ext/qfq/Source/api/rest.php/person
-b) Data of person 123: <domain>/typo3conf/ext/qfq/Source/api/rest.php/person/123
-c) Adresses of person 123: <domain>/typo3conf/ext/qfq/Source/api/rest.php/person/123/address
-d) Adress details of address 45 from person 123: <domain>/typo3conf/ext/qfq/Source/api/rest.php/person/123/address/45
+1. List of all persons: `<domain>/typo3conf/ext/qfq/Source/api/rest.php/person`
+2. Data of person 123: `<domain>/typo3conf/ext/qfq/Source/api/rest.php/person/123`
+3. Adresses of person 123: `<domain>/typo3conf/ext/qfq/Source/api/rest.php/person/123/address`
+4. Adress details of address 45 from person 123: `<domain>/typo3conf/ext/qfq/Source/api/rest.php/person/123/address/45`
QFQ 'Forms' are used as a 'container' to configure all necessary export/import details per 'level'.
Each 'level' is represented by a QFQ Form.
-Only the last <level> of an URI will be processed. The former ones are just to fullfil a good looking REST API.
+Only the last <level> of an URI will be processed. The former ones are just to fulfil a good looking REST API.
Important: the level name is the QFQ form name.
-Each level name (=form name) is available via STORE_CLIENT and name '_formX'. E.g. in example
-d) '{{_form1:C:alnumx}}'='person' and '{{_form2:C:alnumx}}'='address'.
+Each level name (=form name) is available via STORE_CLIENT and name `_formX`. E.g. in example
+(1) `{{_form1:C:alnumx}}=person` and `{{_form2:C:alnumx}}=address`.
-Each level id is available via STORE_CLIENT and name '_idX'. E.g. in example
-d) '{{_id1:C}}'='123' and '{{_id2:C}}'='45'.
+Each level id is available via STORE_CLIENT and name `_idX`. E.g. in example
+(2) `{{_id1:C}}=123` and `{{_id2:C}}=45`.
-Also the 'id' after the last 'level' in the URI path (123 in example b), and 45 in example d) ) is copied to
-variable 'r' in STORE_TYPO3, access it via '{{r:T}}'.
+Also the `id` after the last `level` in the URI path, 123 in example (2) and 45 in example (4), is copied to
+variable `r` in STORE_TYPO3, access it via `{{r:T}}`.
Export (GET)
@@ -7639,17 +7648,19 @@ All data is exported in JSON notation.
A REST (GET) form has two modes: ::
- a) data: specific content to a given id. Defined via 'form.parameter.restSqlData'. This mode is selected
- if there is an id>0 given.
+data
+ Specific content to a given id. Defined via 'form.parameter.restSqlData'. This mode is selected if there is an
+ id>0 given.
- b) list: a list of records will be exported. Defined via 'form.parameter.restSqlList'. This mode is selected if there
- is no id or id=0.
+list
+ A list of records will be exported. Defined via 'form.parameter.restSqlList'. This mode is selected if there is no
+ id or id=0.
There are *no* FormElements.
To simplify access to id parameter of the URI, a mapping is possible via 'form.parameter.restParam'.
-E.g. 'restParam=pId,adrId' with example d) makes '{{pId:C}}=123' and '{{adrId:C}}=45'. The order of variable
-names corresponds to the position in the URI. _id1 is always mapped to the first parameter name, _id2 to
+E.g. `restParam=pId,adrId` with example d) makes `{{pId:C}}=123` and `{{adrId:C}}=45`. The order of variable
+names corresponds to the position in the URI. `_id1` is always mapped to the first parameter name, `_id2` to
the second one and so on.
GET Variables provided via URL are available via STORE_CLIENT as usual.
@@ -7673,18 +7684,18 @@ Form.parameter:
| Attribute | Description |
+===================+==============================================================================+
| restSqlData | SQL query selects content shown in data mode. |
-| | restSqlData={{!SELECT id, name, gender FROM Person WHERE id='{{r:T0}}'' }} |
+| | `restSqlData={{!SELECT id, name, gender FROM Person WHERE id='{{r:T0}}'' }}` |
+-------------------+------------------------------------------------------------------------------+
| restSqlList | SQL query selects content shown in data mode. |
-| | restSqlData={{!SELECT id, name FROM Person }} |
+| | `restSqlData={{!SELECT id, name FROM Person }}` |
+-------------------+------------------------------------------------------------------------------+
-| restParam | Optional. CSV list of variable names. E.g.: restParam=pId,adrId |
+| restParam | Optional. CSV list of variable names. E.g.: `restParam=pId,adrId` |
+-------------------+------------------------------------------------------------------------------+
| restToken | Optional. User defined string. For dynamic token see below. |
+-------------------+------------------------------------------------------------------------------+
-There are no `special-column-names`_ available in 'restSqlData' or 'restSqlList'. Also there are no
+There are no `special-column-names`_ available in `restSqlData` or `restSqlList`. Also there are no
SIPs possible, cause REST typically does not offer sessions/cookies (which are necessary for SIPs).
Authorization
@@ -7698,8 +7709,8 @@ QFQ internal 'HTTP header token based authorization'.
Token based authorization
'''''''''''''''''''''''''
-A form will require a 'token based authorization', as soon as there is a 'form.parameter.restToken' defined.
-Therefore the HTTP Header 'Authorization' has to be set with 'token=<secret token>'. The 'secret token' will
+A form will require a 'token based authorization', as soon as there is a `form.parameter.restToken` defined.
+Therefore the HTTP Header 'Authorization' has to be set with `token=<secret token>`. The 'secret token' will
be checked against the server. Using HTTPS, such token can't be sniffed and will typically not be logged in
any server logs.
@@ -7709,17 +7720,19 @@ Example: ::
Test via commandline: curl -X GET -H 'Authorization: Token token=myCrypticString0123456789' "http://localhost/qfq/typo3conf/ext/qfq/Source/api/rest.php/person/123/address/"
-The static setup with 'form.parameter.restToken=myCrypticString0123456789' is fine, as long as only one token
+The static setup with `form.parameter.restToken=myCrypticString0123456789 is fine, as long as only one token
exist. In case of multiple tokens, replace the static string against a SQL query.
-General: The HTML Header Authorization token is available in STORE_CLIENT via '{{Authorization:C:alnumx}}'.
+General: The HTML Header Authorization token is available in STORE_CLIENT via '`{{Authorization:C:alnumx}}`.
For example all created tokens are saved in a table 'Auth' with a column 'token'. Define: ::
form.parameter.restToken={{SELECT a.token FROM Auth AS a WHERE a.token='{{Authorization:C:alnumx}}' }}
To restrict access to a subset of data, just save the limitations inside the Auth record and update the query
-to check it: ::
+to check it:
+
+.. code-block:: pmysql
form.parameter.restToken={{SELECT a.token FROM Auth AS a WHERE a.token='{{Authorization:C:alnumx}}'}}
form.parameter.restSqlList={{!SELECT p.id, p.name, p.email FROM Person AS p, Auth AS a WHERE a.token='{{Authorization:C:alnumx}}' AND a.attribute=p.attribute}}
@@ -7748,7 +7761,9 @@ Report
------
Any HTML output can be extended by a tag - that's done by the webmaster. For QFQ generated links, an attribute like
-'data-reference' might be injected via token 'A' (attribute). ::
+'data-reference' might be injected via token 'A' (attribute).
+
+.. code-block:: mysql
SELECT 'p:personedit&form=person&r=1|b|s|A:data-reference="person-edit"|t:Edit person' AS _link
--
GitLab