Skip to content
GitLab
Commit 2b295e97 authored by Carsten Rose's avatar Carsten Rose
Browse files

Manual.rst: reformat all sql code to use the t3sphinx lexer

parent 5091176a
Pipeline #1561 passed with stage
in 2 minutes and 17 seconds
Hide whitespace changes
Inline Side-by-side
extension/Documentation/Manual.rst
View file @ 2b295e97
......@@ -1002,7 +1002,9 @@ Mail Log page
-------------
For debugging purposes you may like to add a Mail Log page in the frontend.
The following QFQ code could be used for that purpose (put it in a QFQ PageContent element): ::
The following QFQ code could be used for that purpose (put it in a QFQ PageContent element):
.. code-block:: mysql
# Page parameters
1.sql = SELECT @grId := '{{grId:C0:digit}}' AS _grId
......@@ -1050,7 +1052,9 @@ Form Submit Log page
--------------------
For debugging purposes you may like to add a Form Submit Log page in the frontend.
The following QFQ code could be used for that purpose (put it in a QFQ PageContent element): ::
The following QFQ code could be used for that purpose (put it in a QFQ PageContent element):
.. code-block:: mysql
# Filters
20.shead = <form onchange='this.submit()' class='form-inline'><input type='hidden' name='id' value='{{pageAlias:T0}}'>
......@@ -2554,7 +2558,9 @@ Optional it might be defined via *Form.parameter* ::
Than, e.g. an action-FormElement 'afterSave' can be used to detect the final submit situation and do some extra stuff,
necessary for the final submit.
The following shows the same *Form* in the `regular`, `readonly` and `requiredOff` mode::
The following shows the same *Form* in the `regular`, `readonly` and `requiredOff` mode:
.. code-block:: mysql
10.sql = SELECT CONCAT('p:{{pageAlias:T}}&form=person&r=', p.id, '|Regular') as _pagee,
CONCAT('p:{{pageAlias:T}}&form=person&formModeGlobal=readonly&r=', p.id, '|Readonly') as _pagee,
......@@ -2828,7 +2834,9 @@ FE: 'Report' notation
^^^^^^^^^^^^^^^^^^^^^
The FE fields 'value' and 'note' understand the `Report`_ syntax. Nested SQL queries as well as links with SIP encoding
are possible. To distinguish between 'Form' and 'Report' syntax, the first line has to be `#!report` ::
are possible. To distinguish between 'Form' and 'Report' syntax, the first line has to be `#!report`:
.. code-block:: mysql
#!report
......@@ -4503,7 +4511,9 @@ If *showDebugInfo* is enabled, a full stacktrace and variable contents are displ
Form search
^^^^^^^^^^^
QFQ content record::
QFQ content record:
.. code-block:: mysql
# Creates a small form that redirects back to this page
10 {
......@@ -4683,7 +4693,7 @@ Chart
* Don't nest the HTML & JavaScript code - bad workaround, this is not human readable.
* Select different nesting token, e.g. '<' (check the first line on the following example).
::
.. code-block:: mysql
# <
......@@ -4925,9 +4935,7 @@ Table: Person
* Type: text
* Label: Name
* Parameter::
typeAheadSql = SELECT name FROM Person WHERE name LIKE ? OR firstName LIKE ? LIMIT 100
* Parameter: ``typeAheadSql = SELECT name FROM Person WHERE name LIKE ? OR firstName LIKE ? LIMIT 100``
Typeahead: LDAP with additional values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -5038,7 +5046,8 @@ A simple example
^^^^^^^^^^^^^^^^
Assume that the database has a table person with columns firstName and lastName. To create a simple list of all persons, we can do the following:
::
.. code-block:: mysql
10.sql = SELECT id AS pId, CONCAT(firstName, " ", lastName, " ") AS name FROM person
......@@ -5046,29 +5055,25 @@ The '10' indicates a *root level* of the report (see section `Structure`_). The
for the specific level. When the query is executed, it will return a result having one single column name containing first and last name
separated by a space character.
The HTML output, displayed on the page, resulting from only this definition, could look as follows:
::
The HTML output, displayed on the page, resulting from only this definition, could look as follows::
John DoeJane MillerFrank Star
..
I.e., QFQ will simply output the content of the SQL result row after row for each single level.
However, we can modify (wrap) the output by setting the values of various keys for each level: 10.rsep=<br/> for example
tells QFQ to separate the rows of the result by a HTML-line break. The final result in this case is:
::
.. code-block:: mysql
10.sql = SELECT id AS personId, CONCAT(firstName, " ", lastName, " ") AS name FROM person
10.rsep = <br>
HTML output:
::
HTML output::
John Doe<br>Jane Miller<br>Frank Star
..
.. _`syntax-of-report`:
......@@ -5167,7 +5172,7 @@ of person records from your person table, you can use the SQL query on the secon
See the example below:
::
.. code-block:: mysql
10.sql = SELECT id AS _pId, CONCAT(firstName, " ", lastName, " ") AS name FROM person
10.rsep = <br>
......@@ -5176,17 +5181,13 @@ See the example below:
10.10.rbeg = (
10.10.rend = )
..
This would result in
::
This would result in::
John Doe (3004 Bern)
Jane Miller (8008 Zürich)
Frank Star (3012 Bern)
..
Text across several lines
^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -5199,7 +5200,9 @@ be appended to the last keyword line. 'Keyword' lines are detected on:
* {
* <level>[.<sub level] {
Example::
Example:
.. code-block:: mysql
10.sql = SELECT 'hello world'
FROM mastertable
......@@ -5218,10 +5221,12 @@ Join mode: SQL
This is the default. All lines are joined with a *space* in between. E.g.: ::
.. code-block:: mysql
10.sql = SELECT 'hello world'
FROM mastertable
Results to: `10.sql = SELECT 'hello world' FROM mastertable`
Results to: ``10.sql = SELECT 'hello world' FROM mastertable``
Notice the space between "...world'" and "FROM ...".
......@@ -5229,17 +5234,21 @@ Join mode: strip whitespace
'''''''''''''''''''''''''''
Ending a line with a '\\' strips all leading and trailing whitespaces of that line joins the line directly (no extra
space in between). E.g.: ::
space in between). E.g.:
.. code-block:: mysql
10.sql = SELECT 'hello world', 'd:final.pdf \
|p:id=export \
|t:Download' AS _pdf \
Results to: `10.sql = SELECT 'hello world', 'd:final.pdf|p:id=export|t:Download' AS _pdf`
Results to: ``10.sql = SELECT 'hello world', 'd:final.pdf|p:id=export|t:Download' AS _pdf``
Note: the '\\' does not force the joining, it only removes the whitespaces.
To get the same result, the following is also possible: ::
To get the same result, the following is also possible:
.. code-block:: mysql
10.sql = SELECT 'hello world', CONCAT('d:final.pdf'
'|p:id=export',
......@@ -5248,7 +5257,9 @@ To get the same result, the following is also possible: ::
Nesting of levels
^^^^^^^^^^^^^^^^^
Levels can be nested. E.g.: ::
Levels can be nested. E.g.:
.. code-block:: mysql
10 {
sql = SELECT ...
......@@ -5258,7 +5269,9 @@ Levels can be nested. E.g.: ::
}
}
This is equal to: ::
This is equal to:
.. code-block:: mysql
10.sql = SELECT ...
10.5.sql = SELECT ...
......@@ -5268,7 +5281,9 @@ Leading / trailing spaces
^^^^^^^^^^^^^^^^^^^^^^^^^
By default, leading or trailing whitespaces are removed from strings behind '='. E.g. 'rend = test ' becomes 'test' for
rend. To prevent any leading or trailing spaces, surround them by using single or double ticks. Example: ::
rend. To prevent any leading or trailing spaces, surround them by using single or double ticks. Example:
.. code-block:: mysql
10.sql = SELECT name FROM Person
10.rsep = ' '
......@@ -5280,7 +5295,9 @@ Braces character for nesting
By default, curly braces '{}' are used for nesting. Alternatively angle braces '<>', round braces '()' or square
braces '[]' are also possible. To define the braces to use, the **first line** of the bodytext has to be a comment line and the
last character of that line must be one of '{[(<'. The corresponding braces are used for that QFQ record. E.g.: ::
last character of that line must be one of '{[(<'. The corresponding braces are used for that QFQ record. E.g.:
.. code-block:: mysql
# Specific code. >
10 <
......@@ -5300,7 +5317,9 @@ Per QFQ tt-content record, only one type of nesting braces can be used.
Be careful to:
* write nothing else than whitespaces/newline behind an **open brace**
* the **closing brace** has to be alone on a line. ::
* the **closing brace** has to be alone on a line:
.. code-block:: mysql
10.sql = SELECT 'Yearly Report'
......@@ -5343,7 +5362,9 @@ The STORE_RECORD will always be merged with previous content. The Level Keys are
Multiple columns, with the same column name, can't be accessed individually. Only the last column is available.
Retrieving the *final* value of `special-column-names`_ is possible via '{{&<column>:R}}. Example: ::
Retrieving the *final* value of `special-column-names`_ is possible via '{{&<column>:R}}. Example:
.. code-block:: mysql
10.sql = SELECT 'p:home&form=Person|s|b:success|t:Edit' AS _link
10.20.sql = SELECT '{{link:R}}', '{{&link:R}}'
......@@ -5351,7 +5372,9 @@ Retrieving the *final* value of `special-column-names`_ is possible via '{{&<col
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>'.
Example STORE_RECORD: ::
Example STORE_RECORD:
.. code-block:: mysql
10.sql= SELECT p.id AS _pId, p.name FROM Person AS p
10.5.sql = SELECT adr.city, 'dummy' AS _pId FROM Address AS adr WHERE adr.pId={{pId:R}}
......@@ -5362,7 +5385,9 @@ The line '10.10' will output 'dummy' in cases where there is at least one corres
If there are no addresses (all persons) it reports the person id.
If there is at least one address, it reports 'dummy', cause that's the last stored content.
Example 'level': ::
Example 'level':
.. code-block:: mysql
10.sql= SELECT p.id AS _pId, p.name FROM Person AS p
10.5.sql = SELECT adr.city, 'dummy' AS _pId FROM Address AS adr WHERE adr.pId={{10.pId}}
......@@ -5388,7 +5413,9 @@ Notes to the level:
| | *30.5.1* will be executed as many times as *30.5* has row numbers. |
+-------------+------------------------------------------------------------------------------------------------------------------------+
Report Example 1: ::
Report Example 1:
.. code-block:: mysql
# Displays current date
10.sql = SELECT CURDATE()
......@@ -5607,7 +5634,7 @@ render mode might dynamically control the rendered link.
|7 | pure url |pure url | |no link, pure url |
+------------+---------------------+--------------------+------------------+---------------------------------------------------------------------------+
::
.. code-block:: mysql
10.sql = SELECT CONCAT('u:', p.homepage, IF(p.showHomepage='yes', '|r:0', '|r:5') ) AS _link FROM Person AS p
......@@ -5724,7 +5751,7 @@ The colum name is composed of the string *page* and a trailing character to spec
**Syntax**
::
.. code-block:: mysql
10.sql = SELECT "[options]" AS _page[<link type>]
......@@ -5732,7 +5759,7 @@ The colum name is composed of the string *page* and a trailing character to spec
<link type> = c,d,e,h,i,n,s
..
+---------------+-----------------------------------------------+-------------------------------------+----------------------------------------------+
| column name | Purpose |default value of question parameter | Mandatory parameters |
......@@ -5792,7 +5819,7 @@ These column offers a link, with a confirmation question, to delete one record (
**Syntax**
::
.. code-block:: mysql
10.sql = SELECT "U:table=<tablename>&r=<record id>|q:<question>|..." AS _paged
10.sql = SELECT "U:form=<formname>&r=<record id>|q:<question>|..." AS _paged
......@@ -5824,7 +5851,7 @@ Additional action *FormElement* of type *beforeDelete* or *afterDelete* will be
Examples:
'''''''''
::
.. code-block:: mysql
10.sql = SELECT 'U:table=Person&r=123|q:Do you want delete John Doe?' AS _paged
10.sql = SELECT 'U:form=person-main&r=123|q:Do you want delete John Doe?' AS _paged
......@@ -5864,7 +5891,7 @@ Render text vertically. This is useful for tables with limited column width. The
**Syntax**
::
.. code-block:: mysql
10.sql = SELECT "<text>|[<angle>]" AS _vertical
......@@ -5883,7 +5910,7 @@ This works best for angles close to 270 or 90.
**Minimal Example**
::
.. code-block:: mysql
10.sql = SELECT "Hallo" AS _vertical
......@@ -5901,7 +5928,7 @@ Easily create Email links.
**Syntax**
::
.. code-block:: mysql
10.sql = SELECT "<email address>|[<link text>]" AS _mailto
......@@ -5924,30 +5951,25 @@ Easily create Email links.
**Minimal Example**
::
.. code-block:: mysql
10.sql = SELECT "john.doe@example.com" AS _mailto
..
**Advanced Example**
::
.. code-block:: mysql
10.sql = SELECT "john.doe@example.com|John Doe" AS _mailto
..
.. _column_sendmail:
Column: _sendmail
^^^^^^^^^^^^^^^^^
Format: ::
Format::
t:<TO:email[,email]>|f:<FROM:email>|s:<subject>|b:<body>
[|c:<CC:email[,email]]>[|B:<BCC:email[,email]]>[|r:<REPLY-TO:email>]
......@@ -5955,7 +5977,7 @@ Format: ::
[|e:<subject encode: encode/decode/none>][E:<body encode: encode/decode/none>][|mode:html]
[|C][d:<filename of the attachment>][|F:<file to attach>][|u:<url>][|p:<T3 uri>]
The following parameters can also be written as complete words for ease of use: ::
The following parameters can also be written as complete words for ease of use::
to:<email[,email]>|from:<email>|subject:<subject>|body:<body>
[|cc:<email[,email]]>[|bcc:<email[,email]]>[|reply-to:<email>]
......@@ -5966,7 +5988,7 @@ Send emails. Every mail will be logged in the table `mailLog`. Attachments are s
**Syntax**
::
.. code-block:: mysql
10.sql = SELECT "t:john@doe.com|f:jane@doe.com|s:Reminder tomorrow|b:Please dont miss the meeting tomorrow" AS _sendmail
10.sql = SELECT "t:john@doe.com|f:jane@doe.com|s:Reminder tomorrow|b:Please dont miss the meeting tomorrow|A:off|g:1|x:2|y:3|z:4" AS _sendmail
......@@ -6041,23 +6063,19 @@ Send emails. Every mail will be logged in the table `mailLog`. Attachments are s
**Minimal Example**
::
.. code-block:: mysql
10.sql = SELECT "t:john.doe@example.com|f:company@example.com|s:Latest News|b:The new version is now available." AS _sendmail
..
This will send an email with subject *Latest News* from company@example.com to john.doe@example.com.
**Advanced Examples**
::
.. code-block:: mysql
10.sql = SELECT "t:customer1@example.com,Firstname Lastname <customer2@example.com>, Firstname Lastname <customer3@example.com>| \\
f:company@example.com|s:Latest News|b:The new version is now available.|r:sales@example.com|A:on|g:101|x:222|c:ceo@example.com|B:backup@example.com" AS _sendmail
..
This will send an email with subject *Latest News* from company@example.com to customer1, customer2 and customer3 by
using a realname for customer2 and customer3 and suppress generating of OoO answer if any receiver is on vacation.
Additional the CEO as well as backup will receive the mail via CC and BCC.
......@@ -6099,7 +6117,9 @@ Any combination (incl. repeating them) are possible. Any source will be added as
Optional any number of sources can be concatenated to a single PDF file: 'C|F:<file1>|F:<file2>|p:export&a=123'.
Examples in Report::
Examples in Report:
.. code-block:: mysql
# One file attached.
10.sql = SELECT "t:john.doe@example.com|f:company@example.com|s:Latest News|b:The new version is now available.|F:fileadmin/summary.pdf" AS _sendmail
......@@ -6131,14 +6151,10 @@ Renders images. Allows to define an alternative text and a title attribute for t
**Syntax**
::
.. code-block:: mysql
10.sql = SELECT "<path to image>|[<alt text>]|[<title text>]" AS _img
..
+-------------+-------------------------------------------------------------------------------------------+---------------------------+
|**Parameter**|**Description** |**Default value/behaviour**|
......@@ -6153,19 +6169,14 @@ Renders images. Allows to define an alternative text and a title attribute for t
**Minimal Example**
::
.. code-block:: mysql
10.sql = SELECT "fileadmin/img/img.jpg" AS _img
..
**Advanced Examples**
::
.. code-block:: mysql
10.sql = SELECT "fileadmin/img/img.jpg|Aternative Text" AS _img # alt="Alternative Text, no title
20.sql = SELECT "fileadmin/img/img.jpg|Aternative Text|" AS _img # alt="Alternative Text, no title
......@@ -6176,7 +6187,6 @@ Renders images. Allows to define an alternative text and a title attribute for t
70.sql = SELECT "fileadmin/img/img.jpg||Title Text" AS _img # empty alt, title="Title Text"
80.sql = SELECT "fileadmin/img/img.jpg||" AS _img # empty alt, no title
..
.. _column_exec:
......@@ -6205,13 +6215,11 @@ Runs batch files or executables on the webserver. In case of an error, returncod
**Minimal Examples**
::
.. code-block:: mysql
10.sql = SELECT "ls -s" AS _exec
20.sql = SELECT "./batchfile.sh" AS _exec
..
.. _column_pdf:
......@@ -6220,7 +6228,9 @@ Column: _pdf | _file | _zip
Detailed explanation: download_
Most of the other Link-Class attributes can be used to customize the link. ::
Most of the other Link-Class attributes can be used to customize the link.
.. code-block:: mysql
10.sql = SELECT "[options]" AS _pdf, "[options]" AS _file, "[options]" AS _zip
......@@ -6230,7 +6240,9 @@ Most of the other Link-Class attributes can be used to customize the link. ::
* Parameter are position independent.
* *<params>*: see `download-parameter-files`_
* For column `_pdf` and `_zip`, the element sources `p:...`, `U:...`, `u:...`, `F:...` might repeated multiple times.
* Example: ::
* Example:
.. code-block:: mysql
10.sql = SELECT "F:fileadmin/test.pdf" as _pdf, "F:fileadmin/test.pdf" as _file, "F:fileadmin/test.pdf" as _zip
10.sql = SELECT "p:id=export&r=1" as _pdf, "p:id=export&r=1" as _file, "p:id=export&r=1" as _zip
......@@ -6260,7 +6272,9 @@ Tips:
* If the target file already exists it will be overwriten. To save individual files, choose a new filename,
for example by adding a timestamp.
Examples: ::
Examples:
.. code-block:: mysql
SELECT "d:fileadmin/result.pdf|F:fileadmin/_temp_/test.pdf" AS _savePdf
SELECT "d:fileadmin/result.pdf|F:fileadmin/_temp_/test.pdf|U:id=test&--orientation=landscape" AS _savePdf
......@@ -6307,7 +6321,10 @@ The render mode '7' is useful, if the URL of the thumbnail have to be used in an
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, ')">'`
Example: ::
Example:
.. code-block:: mysql
# SIP protected, IMG tag, thumbnail width 150px
10.sql = SELECT 'T:fileadmin/file3.pdf' AS _thumbnail
......@@ -6376,7 +6393,9 @@ Column: _monitor
Detailed explanation: monitor_
**Syntax** ::
**Syntax**
.. code-block:: mysql
10.sql = SELECT 'file:<filename>|tail:<number of last lines>|append:<0 or 1>|interval:<time in ms>|htmlId:<id>' AS _monitor
......@@ -6405,7 +6424,9 @@ Copy to clipboard
| F:<pathFileName> | F:fileadmin/protected/data.R | pathFileName in DocumentRoot |
+-------------------+--------------------------------+----------------------------------------------------------------------------+
Example: ::
Example:
.. code-block:: mysql
10.sql = SELECT 'y:hello world (yank)|t:content direct (yank)' AS _yank,
'y:hello world (link)|t:content direct (link)' AS _link,
......@@ -6634,7 +6655,9 @@ Best practice:
#. Create a) a link (Report) to the PDF letter or b) attach the PDF (on the fly rendered) to a mail. Both will call the
`wkhtml` via the `download` mode and forwards the necessary parameter.
Use in `report`: ::
Use in `report`:
.. code-block:: mysql
sql = SELECT CONCAT('d:Letter.pdf|t:',p.firstName, ' ', p.name,
'|p:id=letterbody&pId=', p.id, '&_sip=1&--margin-top=50mm&--margin-bottom=20mm&',
......@@ -6648,7 +6671,9 @@ Sendmail. Parameter: ::
sendMailAttachment={{SELECT 'd:Letter.pdf|t:', p.firstName, ' ', p.name, '|p:id=letterbody&pId=', p.id, '&_sip=1&--margin-top=50mm&--margin-bottom=20mm&--header-html={{BASE_URL_PRINT:Y}}?id=letterheader&--footer-right="Seite: [page]/[toPage]"&--footer-font-size=8&--footer-spacing=10' FROM Person AS p WHERE p.id={{id:S}} }}
Replace the static content elements from 2. and 3. by QFQ Content elements as needed: ::
Replace the static content elements from 2. and 3. by QFQ Content elements as needed:
.. code-block:: mysql
10.sql = SELECT '<div class="letter-receiver"><p>', p.name AS '_+br', p.street AS '_+br', p.city AS '_+br', '</p>'
FROM Person AS p WHERE p.id={{pId:S}}
......@@ -6750,7 +6775,9 @@ Create a output like this: ::
This fills D11, E11, F11, D12
In Report Syntax: ::
In Report Syntax:
.. code-block:: mysql
# With ... AS _XLS (token explicit given)
10.sql = SELECT 'position=D10' AS _XLS,
......@@ -6776,7 +6803,9 @@ In Report Syntax: ::
.. _`excel-export-sample`:
Excel export samples: ::
Excel export samples:
.. code-block:: mysql
# From scratch (both are the same, one with '_excel' the other with '_link')
SELECT CONCAT('d:new.xlsx|t:Excel (new)|uid:54') AS _excel
......@@ -6835,7 +6864,9 @@ A `<div>` example HTML output (HTML send to the browser): ::
</div>
A typical QFQ report which generates those `<div>` HTML: ::
A typical QFQ report which generates those `<div>` HTML:
.. code-block:: mysql
10 {
sql = SELECT '<div id="anytag-', n.id,'" data-dnd-id="', n.id,'">' , n.note, '</div>'
......@@ -6865,7 +6896,9 @@ which is the same column width as the outer table. ::
</tbody>
</table>
A typical QFQ report which generates this HTML: ::
A typical QFQ report which generates this HTML:
.. code-block:: mysql
10 {
sql = SELECT '<tr id="anytag-', n.id,'" data-dnd-id="', n.id,'" data-columns="3">' , n.id AS '_+td', n.note AS '_+td', n.ord AS '_+td', '</tr>'
......@@ -6886,7 +6919,9 @@ predefined html id has to be assigned them. After an update, all changed order n
be updated via AJAX.
The html id per element is defined by `qfq-dnd-ord-id-<id>` where `<id>` is the record id. Same example as above, but
with an updated `n.ord` column: ::
with an updated `n.ord` column:
.. code-block:: mysql
10 {
sql = SELECT '<tr id="anytag-', n.id,'" data-dnd-id="', n.id,'" data-columns="3">' , n.id AS '_+td', n.note AS '_+td',
......@@ -6959,12 +6994,16 @@ Bootstrap
* Table > hover: `table-hover`
* Table > condensed: `table-condensed`
E.g.::
Example:
.. code-block:: mysql
10.sql = SELECT id, name, firstName, ...
10.head = <table class='table table-condensed qfq-table-50'>
* `qfq-100`, `qfq-left` - makes e.g. a button full width and aligns the text left. ::
* `qfq-100`, `qfq-left` - makes e.g. a button full width and aligns the text left.
.. code-block:: mysql
10.sql = SELECT "p:home&r=0|t:Home|c:qfq-100 qfq-left" AS _pagev