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
| 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 |
+-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+
| 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 |
| | | load. See `VariablesAddBySql`_ for a usecase. |
| 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 `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_B_ID | | |
......@@ -445,7 +445,9 @@ Example: *typo3conf/config.qfq.ini*
; 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
;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_LABEL = english
......@@ -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}}
.. _`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.
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.
Existing variables will be overwritten. Be carefull not to overwrite needed values.
A specified SELECT statement in `config.qfq.ini`_ in variable `FILL_STORE_SYSTEM_BY_SQL_1` (or `FILL_STORE_SYSTEM_BY_SQL_2`,
or `FILL_STORE_SYSTEM_BY_SQL_3`) will be fired. The query should have 0 (nothing happens) or 1 row. All columns will be
**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.
Access such variables as usual via `{{<varname>:Y}}`.
This option is useful to make generic custom values, saved in the database, accessible to all QFQ Report and Forms.
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`:
......@@ -493,23 +501,21 @@ periodId
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).
After a full QFQ installation, three things are prepared:
* a table `Period` (extend / change it to your needs, fill them with your periods),
* 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
*current* period. One way is a) to mark the current period and b) to change the marker every time when the next period
becomes current.
The QFQ approach works without a marker and without manual intervention: the whished index will be computed during QFQ load.
*current* period.
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}}`.
To get the name and current period: ::
......@@ -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}} }}
* 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`_
......@@ -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 ...
* 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
efficient to specify the base parameter *ldapServer*, *ldapBaseDn* in *Form.parameter* and the rest on the current
*FormElement*.
......@@ -1549,7 +1555,7 @@ E.g.::
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.
......@@ -2256,7 +2262,7 @@ Fields:
| | 'disabled' ) | *Readonly*: user can't change any data. Data not saved. |
| | | *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' }} |
+---------------------+-----------------------------+-----------------------------------------------------------------------------------------------------+
|Class | enum('native', 'action', | Details below. |
......@@ -3255,7 +3261,7 @@ Parameter: sqlBefore / sqlInsert / sqlUpdate / sqlDelete / sqlAfter
* *sqlBefore*: always fired (before any *sqlInsert*, *sqlUpdate*, ..)
* *sqlInsert*: fired if *slaveId* == `0` or *slaveId* == `''`.
* *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.
* *sqlAfter*: always fired (after *sqlInsert*, *sqlUpdate* or *sqlDelete*).
* *sqlHonorFormElements*: list of *FormElement* names (this parameter is optional).
......@@ -4262,19 +4268,13 @@ FAQ
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 is used by configuring Typo3 content elements. Insert one or more QFQ content elements on a Typo3 page.
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.
The QFQ extension is activated through tt-content records. One or more tt-content records per page are necessary to render
*forms* and *reports*. Specify column and language per content record as wished.
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.
......@@ -4323,15 +4323,18 @@ Syntax of `report`
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:
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}}
......@@ -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}} = ...`
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
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
accessed later on in another query via the {{level.columnname}} variable. To suppress printing of a column, use a
underscore as column name prefix.
* On a per column base, printing of columns can be suppressed by starting the columnname with an underscore '_'. E.g. `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 `{{level.columnname}}` variable. To suppress printing of a column, use a
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
------------------
......@@ -4966,7 +4968,7 @@ is allowed to access: ::
page.10.value = Please access from localhost or log in as 'admin' user.
[global]
..
.. _column_pageX:
Columns: _page[X]
^^^^^^^^^^^^^^^^^
......@@ -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 |
+-------------+-------------------------------------------------------------------------------------------------+----------------------------------------------------------+---------------------------------------------------------------+
.. _column_paged:
Column: _paged
^^^^^^^^^^^^^^
......@@ -5079,6 +5083,8 @@ Examples:
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
.. _column_PageX:
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.
..
.. _column_Paged:
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.
"[form=<form name>&r-<record id>[&param=value&...] | [text] | [tooltip] | [question parameter] | [class] | [render mode]" as _Paged.
..
.. _column_vertical:
Column: _vertical
^^^^^^^^^^^^^^^^^
......@@ -5154,7 +5160,7 @@ angle.
..
.. _column_mailto:
Column: _mailto
^^^^^^^^^^^^^^^
......@@ -5203,6 +5209,7 @@ Easily create Email links.
..
.. _column_sendmail:
Column: _sendmail
^^^^^^^^^^^^^^^^^
......@@ -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`_.
.. _column_img:
Column: _img
^^^^^^^^^^^^
......@@ -5336,7 +5344,7 @@ Renders images. Allows to define an alternative text and a title attribute for t
..
.. _column_exec:
Column: _exec
^^^^^^^^^^^^^
......@@ -5371,6 +5379,7 @@ Runs batch files or executables on the webserver. In case of an error, returncod
..
.. _column_pdf:
Column: _pdf | _file | _zip
^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -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
..
.. _column_Pdf:
Column: _Pdf | _File | _Zip
^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -5421,6 +5430,7 @@ A limited set of attributes is supported: ::
..
.. _column_F:
Column: _F
^^^^^^^^^^
......
......@@ -211,7 +211,7 @@ class Database {
} elseif ($count === 0) {
$result = array();
} 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;
case ROW_EXPECT_GE_1:
if ($count > 0) {
......
Supports Markdown
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