Commit 504d8ace authored by Carsten  Rose's avatar Carsten Rose
Browse files

Manual.rst: Update the manual

Database.php: fix wrong error message.
parent 6827cb93
...@@ -353,8 +353,8 @@ config.qfq.ini ...@@ -353,8 +353,8 @@ config.qfq.ini
| DOCUMENTATION_QFQ | DOCUMENTATION_QFQ=http://docs.typo3.org... | Link to the online documentation of QFQ. Every QFQ installation also | | DOCUMENTATION_QFQ | DOCUMENTATION_QFQ=http://docs.typo3.org... | Link to the online documentation of QFQ. Every QFQ installation also |
| | | contains a local copy: typo3conf/ext/qfq/Documentation/html/Manual.html | | | | contains a local copy: typo3conf/ext/qfq/Documentation/html/Manual.html |
+-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+ +-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+
| VAR_ADD_BY_SQL | VAR_ADD_BY_SQL = {{!SELECT s.id AS ... | Specific values read from the database to fill the system store during QFQ | | FILL_STORE_SYSTEM_BY_SQL | FILL_STORE_SYSTEM_BY_SQL = {{!SELECT s.id AS ...| Specific values read from the database to fill the system store during QFQ |
| | | load. See `VariablesAddBySql`_ for a usecase. | | | | load. See `fillStoreSystemBySql`_ for a usecase. |
+-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+ +-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+
| FORM_LANGUAGE_A_ID | FORM_LANGUAGE_A__ID = 1 | In Typo3 configured pageLanguage id. The number after the 'L' parameter. | | FORM_LANGUAGE_A_ID | FORM_LANGUAGE_A__ID = 1 | In Typo3 configured pageLanguage id. The number after the 'L' parameter. |
| FORM_LANGUAGE_B_ID | | | | FORM_LANGUAGE_B_ID | | |
...@@ -445,7 +445,9 @@ Example: *typo3conf/config.qfq.ini* ...@@ -445,7 +445,9 @@ Example: *typo3conf/config.qfq.ini*
; Local Documentation (doc fits to installed version): typo3conf/ext/qfq/Documentation/html/Manual.html ; Local Documentation (doc fits to installed version): typo3conf/ext/qfq/Documentation/html/Manual.html
;DOCUMENTATION_QFQ = https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-053/Manual.html ;DOCUMENTATION_QFQ = https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-053/Manual.html
;VAR_ADD_BY_SQL = 'SELECT s.id AS _periodId FROM Period AS s WHERE s.start<=NOW() ORDER BY s.start DESC LIMIT 1' ;FILL_STORE_SYSTEM_BY_SQL_1 = 'SELECT s.id AS periodId FROM Period AS s WHERE s.start<=NOW() ORDER BY s.start DESC LIMIT 1'
; Important: only define an error message, if QFQ should stop running in case of an error or not exact 1 record.
;FILL_STORE_SYSTEM_BY_SQL_ERROR_MSG_1 = No current period found
;FORM_LANGUAGE_A_ID = 1 ;FORM_LANGUAGE_A_ID = 1
;FORM_LANGUAGE_A_LABEL = english ;FORM_LANGUAGE_A_LABEL = english
...@@ -474,17 +476,23 @@ E.g. to setup a contact address and reuse the information inside your installati ...@@ -474,17 +476,23 @@ E.g. to setup a contact address and reuse the information inside your installati
{{ADMINISTRATIVE_CONTACT:Y}}, {{ADMINISTRATIVE_ADDRESS:Y}}, {{ADMINISTRATIVE_NAME}} {{ADMINISTRATIVE_CONTACT:Y}}, {{ADMINISTRATIVE_ADDRESS:Y}}, {{ADMINISTRATIVE_NAME}}
.. _`VariablesAddBySql`: .. _`fillStoreSystemBySql`:
Variables add by SQL Fill STORE_SYSTEM by SQL
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
A specified SELECT statement in `config.qfq.ini`_ in variable `VAR_ADD_BY_SQL` fill be fired after filling the SYSTEM STORE. A specified SELECT statement in `config.qfq.ini`_ in variable `FILL_STORE_SYSTEM_BY_SQL_1` (or `FILL_STORE_SYSTEM_BY_SQL_2`,
The query should have 0 (nothing happens) or 1 row. The column names and column values will be added as variables to the SYSTEM_STORE. or `FILL_STORE_SYSTEM_BY_SQL_3`) will be fired. The query should have 0 (nothing happens) or 1 row. All columns will be
Existing variables will be overwritten. Be carefull not to overwrite needed values. **added** to the existing STORE_SYSTEM. Existing variables will be overwritten. Be careful not to overwrite system values.
This option is usefull to make generic custom values, saved in the database, accessible to all QFQ Report and Forms. This option is useful to make generic custom values, saved in the database, accessible to all QFQ Report and Forms.
Access such variables as usual via `{{<varname>:Y}}`. Access such variables via `{{<varname>:Y}}`.
In case QFQ should stop working if a given query does not select exact one record (e.g. a missing period), define an
error message: ::
FILL_STORE_SYSTEM_BY_SQL_1 = "SELECT name FROM Person WHERE name='Doe'"
FILL_STORE_SYSTEM_BY_SQL_ERROR_MSG_1 = Too many or to few "Doe's" in our database
.. _`periodId`: .. _`periodId`:
...@@ -493,23 +501,21 @@ periodId ...@@ -493,23 +501,21 @@ periodId
This is This is
* a usecase, implemented via `VariablesAddBySql`_, * a usecase, implemented via `fillStoreSystemBySql`_,
* a way to access `Period.id` with respect to the current period (the period itself is custom defined). * a way to access `Period.id` with respect to the current period (the period itself is custom defined).
After a full QFQ installation, three things are prepared: After a full QFQ installation, three things are prepared:
* a table `Period` (extend / change it to your needs, fill them with your periods), * a table `Period` (extend / change it to your needs, fill them with your periods),
* one sample record in table `Period`, * one sample record in table `Period`,
* in `config.qfq.ini`_ the default definition of `VAR_ADD_BY_SQL` will set the variable `periodId` during QFQ load. * in `config.qfq.ini`_ the default definition of `FILL_STORE_SYSTEM_BY_SQL_1` will set the variable `periodId` during QFQ load.
Websites, delivering semester data, schoolyears schedules, or any other type or periods, often need an index to the Websites, delivering semester data, schoolyears schedules, or any other type or periods, often need an index to the
*current* period. One way is a) to mark the current period and b) to change the marker every time when the next period *current* period.
becomes current.
The QFQ approach works without a marker and without manual intervention: the whished index will be computed during QFQ load.
In `config.qfq.ini`: :: In `config.qfq.ini`: ::
VAR_ADD_BY_SQL = 'SELECT id AS periodId FROM Period WHERE start<=NOW() ORDER BY start DESC LIMIT 1' FILL_STORE_SYSTEM_BY_SQL_1 = 'SELECT id AS periodId FROM Period WHERE start<=NOW() ORDER BY start DESC LIMIT 1'
a variable 'periodId' will automatically computed and filled in STORE SYSTEM. Access it via `{{periodId:Y0}}`. a variable 'periodId' will automatically computed and filled in STORE SYSTEM. Access it via `{{periodId:Y0}}`.
To get the name and current period: :: To get the name and current period: ::
...@@ -1324,7 +1330,7 @@ depending of if they exist in the given statement. E.g.: :: ...@@ -1324,7 +1330,7 @@ depending of if they exist in the given statement. E.g.: ::
fillStoreVar = {{!SELECT p.name, p.email FROM Person AS p WHERE p.id={{pId:S}} }} fillStoreVar = {{!SELECT p.name, p.email FROM Person AS p WHERE p.id={{pId:S}} }}
* After filling the store, the values can be retrieved via `{{name:v}}` and `{{email:V}}`. * After filling the store, the values can be retrieved via `{{name:v}}` and `{{email:V}}`.
* Be carefull by specifying general purpose variables like `id`, `r`, `pageId` and so on. This might conflict with existing variables. * Be careful by specifying general purpose variables like `id`, `r`, `pageId` and so on. This might conflict with existing variables.
* `fillStoreVar` can be used in `form-parameter`_ and `fe-parameter-attributes`_ * `fillStoreVar` can be used in `form-parameter`_ and `fe-parameter-attributes`_
...@@ -1421,7 +1427,7 @@ Server configurations. ...@@ -1421,7 +1427,7 @@ Server configurations.
To decide which Parameter should be placed on *Form.parameter* and which on *FormElement.parameter*: If LDAP access is ... To decide which Parameter should be placed on *Form.parameter* and which on *FormElement.parameter*: If LDAP access is ...
* only necessary in one *FormElement*, most usefull setup is to specify all values in that specific *FormElement*, * only necessary in one *FormElement*, most useful setup is to specify all values in that specific *FormElement*,
* needed on multiple *FormElement*s (of the same *Form*, e.g. one *input* with *typeAhead*, one *note* and one *action*), it's more * needed on multiple *FormElement*s (of the same *Form*, e.g. one *input* with *typeAhead*, one *note* and one *action*), it's more
efficient to specify the base parameter *ldapServer*, *ldapBaseDn* in *Form.parameter* and the rest on the current efficient to specify the base parameter *ldapServer*, *ldapBaseDn* in *Form.parameter* and the rest on the current
*FormElement*. *FormElement*.
...@@ -1549,7 +1555,7 @@ E.g.:: ...@@ -1549,7 +1555,7 @@ E.g.::
Result: (& (|(a=*X*)(b=*X*)) (|(a=*Y*)(b=*Y*)) Result: (& (|(a=*X*)(b=*X*)) (|(a=*Y*)(b=*Y*))
Attention: this option is only usefull in specific environments. Only use it, if it is really needed. The query becomes Attention: this option is only useful in specific environments. Only use it, if it is really needed. The query becomes
much more cpu / IO intensive. much more cpu / IO intensive.
...@@ -2256,7 +2262,7 @@ Fields: ...@@ -2256,7 +2262,7 @@ Fields:
| | 'disabled' ) | *Readonly*: user can't change any data. Data not saved. | | | 'disabled' ) | *Readonly*: user can't change any data. Data not saved. |
| | | *Disabled*: *FormElement* is not visible. | | | | *Disabled*: *FormElement* is not visible. |
+---------------------+-----------------------------+-----------------------------------------------------------------------------------------------------+ +---------------------+-----------------------------+-----------------------------------------------------------------------------------------------------+
|Mode sql | `SELECT` statement with | A value given here overwrites the setting from `mode`. Most usefull with :ref:`dynamic-update`. | |Mode sql | `SELECT` statement with | A value given here overwrites the setting from `mode`. Most useful with :ref:`dynamic-update`. |
| | a value like in `mode` | E.g.: {{SELECT IF( '{{otherFunding:FR:alnumx}}'='yes' ,'show', 'hidden' }} | | | a value like in `mode` | E.g.: {{SELECT IF( '{{otherFunding:FR:alnumx}}'='yes' ,'show', 'hidden' }} |
+---------------------+-----------------------------+-----------------------------------------------------------------------------------------------------+ +---------------------+-----------------------------+-----------------------------------------------------------------------------------------------------+
|Class | enum('native', 'action', | Details below. | |Class | enum('native', 'action', | Details below. |
...@@ -3255,7 +3261,7 @@ Parameter: sqlBefore / sqlInsert / sqlUpdate / sqlDelete / sqlAfter ...@@ -3255,7 +3261,7 @@ Parameter: sqlBefore / sqlInsert / sqlUpdate / sqlDelete / sqlAfter
* *sqlBefore*: always fired (before any *sqlInsert*, *sqlUpdate*, ..) * *sqlBefore*: always fired (before any *sqlInsert*, *sqlUpdate*, ..)
* *sqlInsert*: fired if *slaveId* == `0` or *slaveId* == `''`. * *sqlInsert*: fired if *slaveId* == `0` or *slaveId* == `''`.
* *sqlUpdate*: fired if *slaveId* > `0`. * *sqlUpdate*: fired if *slaveId* > `0`.
* *sqlDelete*: fired if *slaveId* > `0`, after *sqlInsert* or *sqlUpdate*. Be carefull not to delete filled records! * *sqlDelete*: fired if *slaveId* > `0`, after *sqlInsert* or *sqlUpdate*. Be careful not to delete filled records!
Always add a check, if values given, not to delete the record! *sqlHonorFormElements* helps to skip such checks. Always add a check, if values given, not to delete the record! *sqlHonorFormElements* helps to skip such checks.
* *sqlAfter*: always fired (after *sqlInsert*, *sqlUpdate* or *sqlDelete*). * *sqlAfter*: always fired (after *sqlInsert*, *sqlUpdate* or *sqlDelete*).
* *sqlHonorFormElements*: list of *FormElement* names (this parameter is optional). * *sqlHonorFormElements*: list of *FormElement* names (this parameter is optional).
...@@ -4262,19 +4268,13 @@ FAQ ...@@ -4262,19 +4268,13 @@ FAQ
Report Report
====== ======
The QFQ extension is activated through tt-content records. One or more tt-content records per page are necessary to render
*forms* and *reports*.
QFQ content element QFQ content element
------------------- -------------------
QFQ is used by configuring Typo3 content elements. Insert one or more QFQ content elements on a Typo3 page. The QFQ extension is activated through tt-content records. One or more tt-content records per page are necessary to render
Specify column and language per content record as wished. *forms* and *reports*. Specify column and language per content record as wished.
The title of the QFQ content element will not be rendered. It's only visible in the backend for orientation.
General The title of the QFQ content element will not be rendered. It's only visible in the backend for orientation of the webmaster.
-------
To display a report on any given TYPO3 page, create a content element of type 'QFQ Element' (plugin) on that page. To display a report on any given TYPO3 page, create a content element of type 'QFQ Element' (plugin) on that page.
...@@ -4323,15 +4323,18 @@ Syntax of `report` ...@@ -4323,15 +4323,18 @@ Syntax of `report`
For **each** row of a query (this means *all* queries), all subqueries will be fired once. For **each** row of a query (this means *all* queries), all subqueries will be fired once.
* E.g. if the outer query selects 5 rows, and a nested query always select 3 rows, than the total number of rows are 5 x 3 = 15 rows. * E.g. if the outer query selects 5 rows, and a nested query select 3 rows, than the total number of rows are 5 x 3 = 15 rows.
There is a set of **variables** that will get replaced before the SQL-Query gets executed: There is a set of **variables** that will get replaced before the SQL-Query gets executed:
Column values of the recent rows: {{<level>.<columnname>}} Variables from specific stores: {{<name>[:<store/s>[:...]]}}
Global variables: {{global.<name>}} STORE_RECORD is automatically merged with the existing STORE_RECORD content and the current row. Use the STORE_RECORD
to access outer level values.
Variables from specific stores: {{<name>[:<store/s>[:<sanitize class>]]}} Column values of a given row: {{<level>.<columnname>}}
Global variables: {{global.<name>}}
Current row index: {{<level>.line.count}} Current row index: {{<level>.line.count}}
...@@ -4344,22 +4347,21 @@ Syntax of `report` ...@@ -4344,22 +4347,21 @@ Syntax of `report`
Be aware that line.count / line.total have to be known before the query is fired. E.g. `10.sql = SELECT {{10.line.count}}, ... WHERE {{10.line.count}} = ...` Be aware that line.count / line.total have to be known before the query is fired. E.g. `10.sql = SELECT {{10.line.count}}, ... WHERE {{10.line.count}} = ...`
won't work as expected. `{{10.line.count}}` can't be replaced before the query is fired, but will be replaced during processing the result! won't work as expected. `{{10.line.count}}` can't be replaced before the query is fired, but will be replaced during processing the result!
Different types of SQL queries are possible: SELECT, INSERT, UPDATE, DELETE, SHOW Different types of SQL queries are possible: SELECT, INSERT, UPDATE, DELETE, SHOW
Only SELECT and SHOW queries will fire subqueries. Only SELECT and SHOW queries will fire subqueries.
* Processing of the resulting rows and columns: 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. This might be useful to select values which will be * On a per column base, printing of columns can be suppressed by starting the columnname with an underscore '_'. E.g. `SELECT id AS _id`.
accessed later on in another query via the {{level.columnname}} variable. To suppress printing of a column, use a 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. underscore as column name prefix. E.g. `SELECT id AS _id`
Reserved column names have a special meaning and will be processed in a special way. See `Processing of columns in the SQL result`_ for details. Reserved column names have a special meaning and will be processed in a special way. See `Processing of columns in the SQL result`_ for details.
There are extensive ways to wrap columns and rows automatically. See :ref:`wrapping-rows-and-columns` There are extensive ways to wrap columns and rows automatically. See :ref:`wrapping-rows-and-columns`
Debug the bodytext Debug the bodytext
------------------ ------------------
...@@ -4966,7 +4968,7 @@ is allowed to access: :: ...@@ -4966,7 +4968,7 @@ is allowed to access: ::
page.10.value = Please access from localhost or log in as 'admin' user. page.10.value = Please access from localhost or log in as 'admin' user.
[global] [global]
.. .. _column_pageX:
Columns: _page[X] Columns: _page[X]
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
...@@ -5034,6 +5036,8 @@ The colum name is composed of the string *page* and a trailing character to spec ...@@ -5034,6 +5036,8 @@ The colum name is composed of the string *page* and a trailing character to spec
|<create sip> |s | |'s': create a SIP | |<create sip> |s | |'s': create a SIP |
+-------------+-------------------------------------------------------------------------------------------------+----------------------------------------------------------+---------------------------------------------------------------+ +-------------+-------------------------------------------------------------------------------------------------+----------------------------------------------------------+---------------------------------------------------------------+
.. _column_paged:
Column: _paged Column: _paged
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
...@@ -5079,6 +5083,8 @@ Examples: ...@@ -5079,6 +5083,8 @@ Examples:
SELECT 'U:table=Person&r=123|q:Do you want delete John Doe?' AS _paged SELECT 'U:table=Person&r=123|q:Do you want delete John Doe?' AS _paged
SELECT 'U:form=person-main&r=123|q:Do you want delete John Doe?' AS _paged SELECT 'U:form=person-main&r=123|q:Do you want delete John Doe?' AS _paged
.. _column_PageX:
Columns: _Page[X] Columns: _Page[X]
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
...@@ -5089,7 +5095,7 @@ Columns: _Page[X] ...@@ -5089,7 +5095,7 @@ Columns: _Page[X]
"[<page id|alias>[&param=value&...]] | [text] | [tooltip] | [question parameter] | [class] | [target] | [render mode]" as _Pagee. "[<page id|alias>[&param=value&...]] | [text] | [tooltip] | [question parameter] | [class] | [target] | [render mode]" as _Pagee.
.. .. _column_Paged:
Column: _Paged Column: _Paged
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
...@@ -5102,7 +5108,7 @@ Column: _Paged ...@@ -5102,7 +5108,7 @@ Column: _Paged
"[table=<table name>&r-<record id>[&param=value&...] | [text] | [tooltip] | [question parameter] | [class] | [render mode]" as _Paged. "[table=<table name>&r-<record id>[&param=value&...] | [text] | [tooltip] | [question parameter] | [class] | [render mode]" as _Paged.
"[form=<form name>&r-<record id>[&param=value&...] | [text] | [tooltip] | [question parameter] | [class] | [render mode]" as _Paged. "[form=<form name>&r-<record id>[&param=value&...] | [text] | [tooltip] | [question parameter] | [class] | [render mode]" as _Paged.
.. .. _column_vertical:
Column: _vertical Column: _vertical
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
...@@ -5154,7 +5160,7 @@ angle. ...@@ -5154,7 +5160,7 @@ angle.
.. ..
.. _column_mailto:
Column: _mailto Column: _mailto
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
...@@ -5203,6 +5209,7 @@ Easily create Email links. ...@@ -5203,6 +5209,7 @@ Easily create Email links.
.. ..
.. _column_sendmail:
Column: _sendmail Column: _sendmail
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
...@@ -5278,6 +5285,7 @@ Additional the CEO as well as backup will receive the mail via CC and BCC. ...@@ -5278,6 +5285,7 @@ Additional the CEO as well as backup will receive the mail via CC and BCC.
For debugging, please check `REDIRECT_ALL_MAIL_TO`_. For debugging, please check `REDIRECT_ALL_MAIL_TO`_.
.. _column_img:
Column: _img Column: _img
^^^^^^^^^^^^ ^^^^^^^^^^^^
...@@ -5336,7 +5344,7 @@ Renders images. Allows to define an alternative text and a title attribute for t ...@@ -5336,7 +5344,7 @@ Renders images. Allows to define an alternative text and a title attribute for t
.. ..
.. _column_exec:
Column: _exec Column: _exec
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
...@@ -5371,6 +5379,7 @@ Runs batch files or executables on the webserver. In case of an error, returncod ...@@ -5371,6 +5379,7 @@ Runs batch files or executables on the webserver. In case of an error, returncod
.. ..
.. _column_pdf:
Column: _pdf | _file | _zip Column: _pdf | _file | _zip
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
...@@ -5398,7 +5407,7 @@ Most of the other Link-Class attributes can be used to customize the link. ...@@ -5398,7 +5407,7 @@ Most of the other Link-Class attributes can be used to customize the link.
SELECT "d:complete.pdf|t:Download PDF|f:fileadmin/test.pdf|U:id=export&r=1|u:www.w3c.org" AS _pdf SELECT "d:complete.pdf|t:Download PDF|f:fileadmin/test.pdf|U:id=export&r=1|u:www.w3c.org" AS _pdf
.. .. _column_Pdf:
Column: _Pdf | _File | _Zip Column: _Pdf | _File | _Zip
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
...@@ -5421,6 +5430,7 @@ A limited set of attributes is supported: :: ...@@ -5421,6 +5430,7 @@ A limited set of attributes is supported: ::
.. ..
.. _column_F:
Column: _F Column: _F
^^^^^^^^^^ ^^^^^^^^^^
......
...@@ -211,7 +211,7 @@ class Database { ...@@ -211,7 +211,7 @@ class Database {
} elseif ($count === 0) { } elseif ($count === 0) {
$result = array(); $result = array();
} else } else
throw new DbException($specificMessage . "Expected no record, got $count rows: $sql", ERROR_DB_TOO_MANY_ROWS); throw new DbException($specificMessage . "Expected zero or one record, got $count records: $sql", ERROR_DB_TOO_MANY_ROWS);
break; break;
case ROW_EXPECT_GE_1: case ROW_EXPECT_GE_1:
if ($count > 0) { if ($count > 0) {
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment