Commit 1a3338c5 authored by Carsten  Rose's avatar Carsten Rose
Browse files

Manual.rst: extend the SIP explanations. More details about form setup.

parent 9723404b
...@@ -319,8 +319,26 @@ Preparation for Ubuntu 16.04:: ...@@ -319,8 +319,26 @@ Preparation for Ubuntu 16.04::
Concept Concept
======= =======
The QFQ extension is activated through `tt-content` records of type `QFQ`. One (or more) tt-content records per Typo3 SIPs
page are necessary to render *forms* and *reports*. ----
The following is a technical background information. Not needed to just use QFQ.
The SIPs are uniq timestamps, created/registered on the fly for a specific browser session (=user). Every SIP is
registered on the server (= stored in a PHP Session) and contains one or more key/value pairs. The key/value pairs never leave
the server. The SIPs will be used:
* to protect values not to be spoofed by anyone,
* to protect values not to be altered by anyone,
* to grant access, e.g.:
* load and save forms,
* upload files,
* download files,
* PHP AJAX pages.
SIPs becomes invalid, as soon as the current browser session is destroyed. The client (= user) can't manipulate the content
of SIPs - it's only possible to reuse already registered SIPs by the user, who already owns the session.
Access privileges Access privileges
----------------- -----------------
...@@ -334,8 +352,8 @@ The Typo3 FE Groups can be used to implement access privileges. Such groups are ...@@ -334,8 +352,8 @@ The Typo3 FE Groups can be used to implement access privileges. Such groups are
This will be used for general page structure privileges. This will be used for general page structure privileges.
A `record base` privileges controlling (e.g. which user can edit A `record base` privileges controlling (e.g. which user can edit
which person record) will be implizit configured, by the way that records are viewable / editable (or not) through which person record) will be implicit configured, by the way that records are viewable / editable (or not) through
SQL in the specifiq QFQ tt-content statements. SQL in the specific QFQ tt-content statements.
Typo3 QFQ content element Typo3 QFQ content element
------------------------- -------------------------
...@@ -517,6 +535,7 @@ Sanitize class ...@@ -517,6 +535,7 @@ Sanitize class
| **all** | Form | Query | no sanitizing | | **all** | Form | Query | no sanitizing |
+------------------+------+-------+-----------------------------------------------------------------------------------------+ +------------------+------+-------+-----------------------------------------------------------------------------------------+
Security Security
======== ========
...@@ -549,13 +568,13 @@ Get Parameter ...@@ -549,13 +568,13 @@ Get Parameter
* GET parameter might contain urlencoded content (%xx). Therefore all GET parameter will be processed by 'urldecode()'. * GET parameter might contain urlencoded content (%xx). Therefore all GET parameter will be processed by 'urldecode()'.
As a result a text like '%nn' in GET variables will always be decoded. It's not possible to transfer '%nn' itself. As a result a text like '%nn' in GET variables will always be decoded. It's not possible to transfer '%nn' itself.
* GET variables are limited to SECURITY_GET_MAX_LENGTH chars - any violation will break QFQ. * GET variables are limited to SECURITY_GET_MAX_LENGTH chars - any violation will stop QFQ.
Post Parameter Post Parameter
-------------- --------------
Per `FormElement` (HTML input) the default is to `htmlspecialchars()` the input. This means &<>'" will be encoded as htmlentity Per `FormElement` (HTML input) the default is to `htmlspecialchars()` the input. This means &<>'" will be encoded as htmlentity
and saved as a htmlentity in the database. In case any of therse characters (e.g. for HTML tags) are and saved as a htmlentity in the database. In case any of these characters (e.g. for HTML tags) are
required, the encoding can be disabled per FormElement: `encode=none` (default is `specialchar`). required, the encoding can be disabled per FormElement: `encode=none` (default is `specialchar`).
During Form load, htmlentities are decoded again. During Form load, htmlentities are decoded again.
...@@ -563,14 +582,15 @@ During Form load, htmlentities are decoded again. ...@@ -563,14 +582,15 @@ During Form load, htmlentities are decoded again.
$_SERVER $_SERVER
-------- --------
All $_SERVER vars are htmlentities (all, not only specialchars!) encoded. All $_SERVER vars are htmlentities encoded (all, not only specialchars!) .
Honeypot Honeypot
-------- --------
Every QFQ Form contains 'honeypot'-HTML input elements (hidden & readonly). Which to use is configured in `config.qfq.ini`_ Every QFQ Form contains 'honeypot'-HTML input elements (HTML: hidden & readonly). Which of them to use is configured in
(default: 'username', 'password' and 'email'). Independet of the QFQ Form, on every start of QFQ, these variables are `config.qfq.ini`_ (default: 'username', 'password' and 'email'). On every start of QFQ (form, report, save, ...),
tested if they are non-empty. these variables are tested if they are non-empty. If any of the default configured are needed, an explicit variable name
list have to be unconfigured in `config.qfq.ini`_.
**QFQ security restriction**: **QFQ security restriction**:
...@@ -582,7 +602,7 @@ Violation ...@@ -582,7 +602,7 @@ Violation
On any violation, QFQ will sleep SECURITY_ATTACK_DELAY seconds (`config.qfq.ini`_) and than exit the running PHP process. On any violation, QFQ will sleep SECURITY_ATTACK_DELAY seconds (`config.qfq.ini`_) and than exit the running PHP process.
A detected attack leads to a complete white (=empty) page. A detected attack leads to a complete white (=empty) page.
If SECURITY_SHOW_MESSAGE = true (`config.qfq.ini`_), a message is displayed. If SECURITY_SHOW_MESSAGE = true (`config.qfq.ini`_), at least a message is displayed.
Client Parameter via SIP Client Parameter via SIP
------------------------ ------------------------
...@@ -1111,7 +1131,8 @@ Form ...@@ -1111,7 +1131,8 @@ Form
==== ====
* Forms will be created by using the *QFQ Form Editor* on the Typo3 frontend (HTML form). * Forms will be created by using the *QFQ Form Editor* on the Typo3 frontend (HTML form).
* The Formeditor itself consist of two predefined QFQ forms: *form* and *formElement* * The Formeditor itself consist of two predefined QFQ forms: *form* and *formElement* - these forms are often updated
during the installation of new QFQ versions.
* Every form consist of a) a *Form* record and b) multiple *FormElement* records. * Every form consist of a) a *Form* record and b) multiple *FormElement* records.
* A form is assigned to a *table*. Such a table is called the *primary table* for this form. * A form is assigned to a *table*. Such a table is called the *primary table* for this form.
* There are three types of forms which can roughly categorized into: * There are three types of forms which can roughly categorized into:
...@@ -1122,13 +1143,39 @@ Form ...@@ -1122,13 +1143,39 @@ Form
* *Advanced* form: the form acts on multiple records, stored in more than one table. * *Advanced* form: the form acts on multiple records, stored in more than one table.
* Fields of the primary table acts like a *simple* form, all other fields have to be specified with *addNupdate* records. * Fields of the primary table acts like a *simple* form, all other fields have to be specified with *action/afterSave* records.
* *Multi* form: the form acts simultanously on more than one record. All records use the same *FormElements*. * *Multi* form: the form acts simultanously on more than one record. All records use the same *FormElements*.
* The *FormElements* are defined as a regular *simple* / or *advanced* form, plus a SQL Query, which selects and * The *FormElements* are defined as a regular *simple* / or *advanced* form, plus a SQL Query, which selects and
iterates over all records. Those records will be loaded at the same time. iterates over all records. Those records will be loaded at the same time.
* Form mode: The parameter 'r' (given via URL or via SIP) decide if the form is in mode:
* `New`:
* Missing parameter 'r' or 'r=0'
* On form load, no record is displayed.
* Saving the form creates a new primary record.
* E.g.: `http://example.com/index.php?id=home&form=Person` or `http://example.com/index.php?id=home&form=Person&r=0`
* `Edit`:
* Parameter 'r>0'
* On form load, the specified record (<tablename>.id= <r>) will be loaded and displayed.
* Saving the form will update the existing record.
* E.g.: `http://example.com/index.php?id=home&form=Person&r=123`
* Display a form:
* Create a QFQ tt_content record on a Typo 3 page.
* Inside the QFQ record: `form = <formname>`. E.g.:
* Static: `form = Person`
* Dynamic: `form = {{form:S}}` (the left `form` is a keyword for QFQ, the right `form` is a free chooseable variable name)
* With the `Dynamic` option, it's easily possible to use one Typo3 page and display different forms on that specific
page. This is nice to configure few Typo 3 pages. The disadvantage is that the user might loose the navigation.
.. _form-main: .. _form-main:
...@@ -1185,6 +1232,56 @@ Definition ...@@ -1185,6 +1232,56 @@ Definition
|created | datetime | set once through QFQ | |created | datetime | set once through QFQ |
+-------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+ +-------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
permitNew & permitEdit
^^^^^^^^^^^^^^^^^^^^^^
Depending on `r`, the following access permission will be taken:
* `r=0` - permitNew
* `r>0` - permitEdit
+------------+---------------------------------------------------------------------------------------------------+
| Option | Description |
+============+===================================================================================================+
| sip | The parameter 'form' and 'r' must be supplied via SIP or hard coded in the QFQ tt_content record. |
+------------+---------------------------------------------------------------------------------------------------+
| logged_in | The form will only be shown if the current User is logged in as a FE User |
+------------+---------------------------------------------------------------------------------------------------+
| logged_out | The form will only be shown if the current User is *not* logged in as a FE User |
+------------+---------------------------------------------------------------------------------------------------+
| always | No access restriction, the form will always be shown |
+------------+---------------------------------------------------------------------------------------------------+
| never | The form will never be shown |
+------------+---------------------------------------------------------------------------------------------------+
* `sip` is *always* the preferred way. With 'sip' it's not necessary to differ between logged in or not, cause the SIP
only exist and is only valid, if it's created via QFQ/report earlier. This means 'creating' the SIP implies
'access granted'. The grant will be revoked when the QFQ session is destroyed - this happens when a user loggs out or
the webbrowser is closed.
* `logged_id` / `logged_out`: for forms which might be displayed without a SIP, but maybe on a protected or even unprotected
page. *The option is probably not often used.*
* `always`: such a form is always allowed to be loaded.
* `permitNew=always`: Public accessible forms (e.g. for registration) will allow users to fill and save
the form.
* `permitEdit=always`: Public accessible forms will allow users to update existing data. This
is dangerous, cause the URL paramater (recordId) 'r' might be changed by the user (URL manipulating) and therefore
the user might see and/or change data from other users. *The option is probably not often used.*
* `never`: such a form is not allowed to be loaded.
* `permitNew=never`: Public accessible forms. It's not possible to create new records.
* `permitEdit=none`: Public accessible forms. It's not possible to update records.
showButton showButton
^^^^^^^^^^ ^^^^^^^^^^
......
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