Commit 7a609638 authored by Carsten  Rose's avatar Carsten Rose
Browse files

Sphinx: extended doc

parent e8f5c37e
......@@ -34,7 +34,6 @@ How should the extension be set up? E.g. is there a static template to include?
List of extensions within the Extension Manager also shortend as "EM" (legend of the image)
FAQ
^^^
......
......@@ -15,7 +15,7 @@ QFQ Extension
.. only:: html
:Classification:
extension_key
qfq
:Version:
|release|
......@@ -24,19 +24,21 @@ QFQ Extension
en
:Description:
enter description.
The extension offers support to
a) create HTML Forms by clicking them together,
b) create reports based an SQL queries. The SQL can be nested and offers support for any kind of tags.
:Keywords:
comma,separated,list,keywords
Quick Form Query, Form, Report, SQL, Query, Generator
:Copyright:
2016
:Author:
Rafael Ostertag
Carsten Rose
:Email:
author@example.com
carsten.rose@math.uzh.ch
:License:
This document is published under the Open Publication License
......@@ -57,5 +59,6 @@ QFQ Extension
Introduction/Index
UsersManual/Index
AdministratorManual/Index
UsersManual/Form
UsersManual/Report
Links
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
.. _start:
=============================================================
QFQ Extension (Deutsch)
=============================================================
.. only:: html
:Klassifikation:
extension_key
:Version:
|release|
:Sprache:
de
:Beschreibung:
Geben Sie eine Beschreibung ein.
:Schlüsselwörter:
komma-getrennte,Liste,von,Schlüsselwörtern
:Copyright:
2016
:Autor:
Rafael Ostertag
:E-Mail:
author@example.com
:Lizenz:
Dieses Dokument wird unter der Open Content License, siehe
http://www.opencontent.org/opl.shtml veröffentlicht.
:Gerendert:
|today|
Der Inhalt dieses Dokuments bezieht sich auf TYPO3,
ein GNU/GPL CMS-Framework auf `www.typo3.org <https://typo3.org/>`__.
**Inhaltsverzeichnis**
.. toctree::
:maxdepth: 3
:titlesonly:
.. Introduction/Index
.. UsersManual/Index
.. AdministratorManual/Index
How to translate
================
This directory contains the German translation of your documentation.
This is a complete Sphinx project but you may reuse assets from the
main documentation under Documentation/.
If you plan to translate your documentation to German, you should
rename this directory and remove the suffix ".tmpl":
Localization.de_DE.tmpl -> Localization.de_DE
As this file is not needed either, feel free to delete it as well.
Supported languages
===================
Please visit http://sphinx-doc.org/latest/config.html#intl-options for a
list of languages supported by Sphinx.
Please note however that TYPO3 is using locales so you may need to
extend the language code from Sphinx into a proper locale to be used
by TYPO3.
# This is the project specific Settings.yml file.
# Place Sphinx specific build information here.
# Settings given here will replace the settings of 'conf.py'.
---
conf.py:
copyright: 2016
project: QFQ Extension (Deutsch)
version: 0.1
release: 0.1.0
latex_documents:
- - Index
- qfq.tex
- QFQ Extension
- Rafael Ostertag
- manual
latex_elements:
papersize: a4paper
pointsize: 10pt
preamble: \usepackage{typo3}
...
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
.. _start:
=============================================================
QFQ Extension (Français)
=============================================================
.. only:: html
:Classification:
extension_key
:Version:
|release|
:Langue:
fr
:Description:
entrez une description.
:Mots-clés:
list,mots-clés,séparés,par,virgules
:Copyright:
2016
:Auteur:
Rafael Ostertag
:E-mail:
author@example.com
:Licence:
Ce document est publié sous la licence de contenu libre
disponible sur http://www.opencontent.org/opl.shtml
:Généré:
|today|
Le contenu de ce document est en relation avec TYPO3,
un CMS/Framework GNU/GPL disponible sur `www.typo3.org <https://typo3.org/>`__.
**Sommaire**
.. toctree::
:maxdepth: 3
:titlesonly:
.. Introduction/Index
.. UsersManual/Index
.. AdministratorManual/Index
How to translate
================
This directory contains the French translation of your documentation.
This is a complete Sphinx project but you may reuse assets from the
main documentation under Documentation/.
If you plan to translate your documentation to French, you should
rename this directory and remove the suffix ".tmpl":
Localization.fr_FR.tmpl -> Localization.fr_FR
As this file is not needed either, feel free to delete it as well.
Supported languages
===================
Please visit http://sphinx-doc.org/latest/config.html#intl-options for a
list of languages supported by Sphinx.
Please note however that TYPO3 is using locales so you may need to
extend the language code from Sphinx into a proper locale to be used
by TYPO3.
# This is the project specific Settings.yml file.
# Place Sphinx specific build information here.
# Settings given here will replace the settings of 'conf.py'.
---
conf.py:
copyright: 2016
project: QFQ Extension (Français)
version: 0.1
release: 0.1.0
latex_documents:
- - Index
- qfq.tex
- QFQ Extension
- Rafael Ostertag
- manual
latex_elements:
papersize: a4paper
pointsize: 10pt
preamble: \usepackage{typo3}
...
......@@ -12,7 +12,7 @@ conf.py:
- - Index
- qfq.tex
- QFQ Extension
- Rafael Ostertag
- Carsten Rose
- manual
latex_elements:
papersize: a4paper
......
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
.. _users-manual-form:
Form
----
* Every form consist of a `Form` record and multiple `FormElement` records.
* Forms will be created by using the `Form editor`.
* A form is assigned to `table`, called `primary table`.
* If a form saves values to more than one table, use the `addNupdate` FormElements.
Form specification
------------------
Most fields of a form specification might contain:
* ''constants'' (=strings), this is the standard use case.
* ''variables'' retrieved from the stores (see below),
* ''SQL statements'' (limited set of),
* or any combination of the above.
Variable (incl. mixed SQL Statement)
------------------------------------
* A variable (or SQL) statement is surrounded by curely braces:
`{{VarName[:<store / prio>[:<sanitize class>]]}}`
* Example:
`{{recordid}}`
`{{SELECT name FROM person WHERE id=1234}}`
`{{SELECT name FROM person WHERE id={{recordid}} }}`
`{{SELECT name FROM person WHERE id={{key1:C:ALNUMX}} }}`
* Leading and tailing spaces inside curly braces are removed.
* `{{ SELECT "_1" }}` is equal to `{{SELECT "_1"}}`
* `{{ varname }}` is equal to `{{varname}}`
* There are several stores, from where to retrieve the value. If a value is not found in one store, take the next store, until a value has been found.
* If there is an empty string found, this '''is''' a value: value found >> stop search.
* If no value is found, the value is an <empty string>.
URL Parameter
-------------
* URL (=GET) Parameter can be used in forms as variables.
* Every parameter should be defined in 'Form.url_parameter_type', together with a sanitize class.
* Parameter without a definition are classified as `digit`. Broken validation will clear the variable (empty string).
Sanitize class
--------------
* All values in Store `C` (Client) and store `F` (Form) will be sanitized with one of three classes:
* **digit**: [0-9].-+
* **alnumx**: [A-Za-z][0-9]@-_.,; /()
* **all**: no sanitizing
* All :ref:`predefined-variable-names` have a specific default sanitize class.
* All other variables (Store: C, F) get by default the sanitize class 'digit'.
* A default sanitize class can be overwritten by individual definition: `{{a:C:all}}`
Store / prio
------------
Only variables, which are known in a specified store, can be substituted.
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
|Name |Description | Content |
+=====+========================================================================================+======================================================================+
| F | Form: data still not saved in database. | All native form elements. Recent values from the Browser. |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| S | SIP: Client parameter 's' will indicate the current SIP, which will be loaded from the | sip, r (record_id), form |
| | SESSION repo to the SIP-Store. | |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| R | Record - the one who will be edited. For new records: empty. | All columns of the current record from the current table |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| P | Parent record. E.g.: on multi forms the current record of the outer query | All columns of the MultiSQL Statement from the for the current row |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| D | The `table.column` specified `default value`. | |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| M | The `table.column` specified `type` | |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| C | Client: POST variable, if not found: GET variable | Parameter send from the Client (=Browser). |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| T | Typo3: a) Bodytext (ttcontent record), b) Typo3 internal varibles like fe_user_uid, ...| See Typo3 tt_content record configuration |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| 0 | Value: 0, might helpfull if variable is empty but used in an SQL statement, which | All possible keys |
| | might produce a SQL error otherwise if substituted with an empty string | |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
| Y | System: a) Database credentials, b) helper vars for logging/debugging: | |
| | SYSTEM_SQL_RAW ... SYSTEM_FORM_ELEMENT_COLUMN | |
+-----+----------------------------------------------------------------------------------------+----------------------------------------------------------------------+
* Default `<prio>`: `FSRD` - Form / SIP / Record / Table definition.
* Hint: Preferable, parameter should be submitted by SIP, not by Client (=URL).
* SIPs can only be defined by using `Report`.
* Data submitted via 'Client' can be easily spoofed and altered.
* Data submitted via SIP never leaves the server, cannot be spoofed or altered by the user.
* QFQ generated internal links are automatically 'SIP'ed.
* If are URL parameter needed, specifying 'C' inside `<prio>` is necessary as well as specifying them in `Form.permitUrlParameter`.
.. _predefined-variable-names:
Predefined variable names
-------------------------
Store: `CLIENT` - C
^^^^^^^^^^^^^^^^^^^
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Explanation |
+===============+==========================================================================================================================================+
| s | =SIP |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| r | record id. Typically stored in SIP, rarely specified on the URL |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| keySemId | always current Semester Id |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| keySemIdUser | `{{keySemIdUser}}`, may be changed by user |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| pageId | current T3 page Id |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| pageType | T3 GET Parameter 'type' |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| pageLanguage | T3 GET Parameter 'L' |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HTTP_HOST | current HTTP HOST |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| REMOTE_ADDR | Client IP address |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| '$_SERVER[*]' | All other variables accessable by `$_SERVER[]`. Only the often used have a pre defined sanitize class. |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| form | Unique name of current form |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| random | random string with length of 32 chars, alphanum |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| ANREDE | `{{sex}}` == male >> Sehr geehrter Herr, `{{sex}}` == female Sehr geehrte Frau |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
| EANREDE | `{{sex}}` == male >> Dear Mr., `{{sex}}` == female >> Dear Mrs. |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------+
Store: `TYPO3` (Bodytext) - T
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------+-------------------------------------------------------------------+
| Name | Explanation |
+===============+===================================================================+
| form | Formname defined in ttcontent record bodytext |
| | * fix. E.g.: `form = person` |
| | * via SIP. E.g. `form = {{form}} |
+---------------+-------------------------------------------------------------------+
| debugShowStack| Any exception will show the call stack. E.g. `debugShowStack = 1` |
+---------------+-------------------------------------------------------------------+
| debugLoad | Debug Level for 'load', defined in ttcontent record bodytext |
+---------------+-------------------------------------------------------------------+
| debugSave | Debug Level for 'save', defined in ttcontent record bodytext |
+---------------+-------------------------------------------------------------------+
| fe_user | Logged in Typo3 FE User |
+---------------+-------------------------------------------------------------------+
| fe_user_uid | Logged in Typo3 FE User uid |
+---------------+-------------------------------------------------------------------+
| fe_user_group | FE groups of logged in Typo3 FE User |
+---------------+-------------------------------------------------------------------+
Store: `FORM` - F
^^^^^^^^^^^^^^^^^
* Represents the values in the form, typically before saving them.
* Used for:
* Formelements who will be rerendered, after a parent element has been changed by the user.
* Formelement actions, before saving the form.
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Explanation |
+====================+============================================================================================================================================+
| FormElement name | Name of native formelement. To get, exactly and only, the specified form element(for 'p_id'): `{{p_id:F}}` |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
Store: `RECORD` - R
^^^^^^^^^^^^^^^^^^^
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Explanation |
+====================+============================================================================================================================================+
| record column name | Name of a column of the primary table (as defined in the current form). To get, exactly and only, the specified form element: `{{p_id:R}}` |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
SQL detection
~~~~~~~~~~~~~
* The detection of an SQL command is case *insensitive*.
+-------------+---------------------------------------+
| Name | Explanation |
+=============+=======================================+
| SELECT ... | reserved and indicates a SQL Statememt|
+-------------+---------------------------------------+
| INSERT ... | reserved and indicates a SQL Statememt|
+-------------+---------------------------------------+
| UPDATE ... | reserved and indicates a SQL Statememt|
+-------------+---------------------------------------+
| DELETE ... | reserved and indicates a SQL Statememt|
+-------------+---------------------------------------+
| SHOW ... | reserved and indicates a SQL Statememt|
+-------------+---------------------------------------+
SQL
---
* SQL Statement::
{{[!]SELECT ...|UPDATE ...|INSERT ...|SHOW ...|LAST_INSERT_ID ...}}
* Example::
{{SELECT ... id, name, ... [<PARAM1>] ... FROM person ... [<PARAM2>] [...]}}
* A SQL Statement might contain parameter, including additional SQL statements. Inner SQL queries will be fired first.
* All variables will be substituted one by one from inner to outer.
* Maximum recursion depth: 5 (a recursion depth of 2 is sometimes used for mailing with templates, 3 and more probably confuses too much and are therefore not practicable, but supported until depth of 5)
* The number of variables inside an input field or a SQL statement is not limited.
* A resultset of a SQL statement will be imploded over all (concat all columns of a row, concat all rows - there is no glue string).
* Array: `{{!SELECT ...}}`
* Only possible for the most outer SELECT.
Form
----
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
| Name | Explanation | Description |
+========================+==========================================================+=========================================================================================+
|id | int, autoincrement | created by by MySQL |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|name | string | unique and speaking name of the form. Form will be identified by this name |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|title | string / query | Title, shown on/above the form. |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|noteInternal | textarea | Internal notes: special functionality, used variables, ... |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|tableName | string | Primay table of the form |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|permitNew | enum('sip', 'logged_in', 'logged_out', 'always', 'never')| Default: sip |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|permitEdit | enum('sip', 'logged_in', 'logged_out', 'always', 'never')| Default: sip |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|permitUrlParameter | textarea | Braucht es das wircklich? per line one GET-'parameter name' with a class DIGIT, ALNUMX, |
| | | ALL. F.e.: `email:ALPHANUM \n postalcode:DIGIT` |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|render | enum('plain','table', 'bootstrap') | Default bootstrap |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|multiMode | enum('none','horizontal','vertical') | Default 'none' |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|multiSql |text | Optional. SQL Query which selects all records to edit. |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|multiDetailForm | string | Optional. Form to open, if a record is selected to edit (double click on record line) |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|multiDetailFormParameter| string | Optional. Translated Parameter submitted to detailform (like subrecord parameter) |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|forwardMode | string: 'auto|no|page'. | |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|forwardPage | string / query | If $forward=="page": page to jump to |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|bsLabelColumns | string | title: default number of 'bootstrap 12grid' columns |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|bsInputColumns | string | input: default number of 'bootstrap 12grid' columns |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|bsNoteColumns | string | note: default number of 'bootstrap 12grid' columns |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|parameter | text | Misc additional parameters. See 'Form.parameter' |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|deleted | string | 'yes'|'no'. |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|modified | timestamp | updated autmatically throught stored procedure |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
|created | datetime | set once through QFQ |
+------------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------+
* Former columns used in `form2`, maybe usefull in QFQ:
* gr_id_section / int / Assign form to a user defineable list of sections. Supports administration of tables.
* form_delete / string / form.name of a 'delete' form. Deletes primary record(s) and dependent records
* typ / enum / Not necessary in the first version of QFQ - may be later.
* Columns used in `form2`, probably not used anymore in QFQ.
* col_id_background / int / done by CSS
* col_id_font / int / done by CSS
* col_id_border / int / done by CSS
* section_unused
* color_css / enum('yes', 'no')
Form.parameter
--------------
+------------------------+--------+---------------------------------------------------------------------------------------------------+
| Name | Type | Description |
+========================+========+===================================================================================================+
| maxVisiblePill | int | Show pills upto <maxVisiblePill> as button, all further in a dropdown menu. Eg.: maxVisiblePill=3 |
+------------------------+--------+---------------------------------------------------------------------------------------------------+
| class | string | HTML div with given class, surrounding the whole form. Eg.: class=container-fluid |
+------------------------+--------+---------------------------------------------------------------------------------------------------+
FormElement
-----------
* Ordering and grouping: Native Form-Elements and Container-Elements, both with feIdContainer=0 will ordered by 'ord'.
* Inside of a container, all nested elements will be displayed.
Class: Container
----------------
* Pill's are container for 'fieldset' and 'native' Form-Elements.
* Fieldsets are container for 'native' Form-Elements
Type: fieldset
^^^^^^^^^^^^^^
* Native Formelements might be assigned to a fieldset.
* name: technical name, used as HTML identifier.
* label: Shown title of the fieldset.
Type: pill
^^^^^^^^^^