Commit fa29573c authored by Marc Egger's avatar Marc Egger
Browse files

add a lot of documentation.

parent fe15d0eb
Pipeline #4048 failed with stages
in 4 minutes and 37 seconds
......@@ -92,6 +92,8 @@ General
* With the `Dynamic` option, it's easily possible to use one Typo3 page and display different forms on that specific
page.
* Forms are synced between the database and form files. See :ref:`formAsfile`.
Form process order
------------------
......@@ -3459,6 +3461,8 @@ Table: Person
Import/merge form
-----------------
* ATTENTION * : This currently does not work. To copy merge forms you may just copy/merge the form files. See :ref:`formAsFile`.
The form `copyFormFromExt` copies a form from table `ExtForm / ExtFormElement` to `Form / FormElement`. The import/merge
form:
......@@ -3481,4 +3485,13 @@ If there are several T3/QFQ instances and if forms should be imported frequently
'import Forms from db xyz' like: ::
10.sql = CREATE OR REPLACE table ExtForm SELECT * FROM <db xyz>.Form
20.sql = CREATE OR REPLACE table ExtFormElement SELECT * FROM <db xyz>.FormElement
\ No newline at end of file
20.sql = CREATE OR REPLACE table ExtFormElement SELECT * FROM <db xyz>.FormElement
.. _`formAsFile`
Form As File
------------
* Forms are synced between the database and form files located in the form directory contained in the qfq project directory. See: :ref:`qfq-project-path-php`
* **ATTENTION** : Form and FormElement changes in the database are only registered if they are performed by the form editor. Otherwise they might get overwritten during the next file sync!
......@@ -202,9 +202,10 @@ Setup
* If the Extension Manager stops after importing: check your memory limit in php.ini.
* Copy/rename the file *<site path>/typo3conf/ext/qfq/config-example.qfq.php* to *<site path>/typo3conf/config.qfq.php*.
* Copy/rename the file *<site path>/typo3conf/ext/qfq/example.qfq.json* to *<site path>/fileadmin/protected/qfqProject/qfq.json*.
Configure the necessary settings :ref:`configuration`
The configuration file is outside of the extension directory, to not loose it during de-install and install again.
* When the QFQ Extension is called the first time on the Typo3 frontend, the file *<ext_dir>/Classes/Sql/formEditor.sql* will
played and fills the database with the *Form editor* records. This also happens automatically after each update of QFQ.
* Configure Typoscript to include Bootstrap, jQuery, QFQ javascript and CSS files.
......@@ -325,10 +326,38 @@ Installation: Check List
Configuration
-------------
.. _config-qfq-php:
.. _qfq-project-path-php
config.qfq.php
^^^^^^^^^^^^^^
qfq.project.path.php
^^^^^^^^^^^^^^^^^^^^
* The file `qfq.project.path.php` is located/created in the root directory of the application. (Where index.php is located)
* This file only returns the path to the qfq project directory where logs, config (`qfq.json`), report files and form files are located.
* If the file does not exist, it is created and the project path is set as follows:
* Does the deprecated config file typo3conf/config.qfq.php exist? Then set the qfq project path to `fileadmin/protected/qfqProject` (config is migrated automatically to qfqProject).
* If not, does `fileadmin/protected exist`? Then set the qfq project path to `fileadmin/protected/qfqProject`.
* If not, then set qfq project path to `../` (i.e. outside the app directory where index.php is located)
Example: *typo3conf/config.qfq.php*: ::
<?php
/**
QFQ project path configuration
!! ATTENTION !!: The files in the project directory should NOT be served by your http server!
Only exception: The app directory inside the project directory may be served.
*/
return 'fileadmin/protected/qfqProject'; // path relative to app directory (i.e. location of this file).
.. _qfq.json
qfq.json
^^^^^^^^
* Additionally to the keywords bellow one can also override the configuration values defined in the Typo3 extension manager: :ref:`extension-manager-qfq-configuration`
* e.g. if `qfq.json` contains `"flagProduction":"no"` then this value is taken instead of the one set in the extension manager.
+-------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
| Keyword | Example | Description |
......@@ -345,38 +374,36 @@ config.qfq.php
| LDAP_1_PASSWORD | LDAP_1_PASSWORD='mySecurePassword' | |
+-------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
Example: *fileadmin/protected/qfqProject/qfq.json*: ::
Example: *typo3conf/config.qfq.php*: ::
<?php
{
"DB_1_USER": "<DBUSER>",
"DB_1_SERVER": "<DBSERVER>",
"DB_1_PASSWORD": "<DBPW>",
"DB_1_NAME": "<DB>",
// QFQ configuration
//
// Save this file as: <site path>/typo3conf/config.qfq.php
"DB_2_USER": "<OPTIONAL DBUSER>",
"DB_2_SERVER": "<OPTIONAL DBSERVER>",
"DB_2_PASSWORD": "<OPTIONAL DBPW>",
"DB_2_NAME": "<OPTIONAL DB>",
return [
'DB_1_USER' => '<DBUSER>',
'DB_1_SERVER' => '<DBSERVER>',
'DB_1_PASSWORD' => '<DBPW>',
'DB_1_NAME' => '<DB>',
"LDAP_1_RDN": "<OPTIONAL> ou=Admin,ou=example,dc=com",
"LDAP_1_PASSWORD": "<OPTIONAL> mySecurePassword"
}
//DB_2_USER => <DBUSER>
//DB_2_SERVER => <DBSERVER>
//DB_2_PASSWORD => <DBPW>
//DB_2_NAME => <DB>
.. _config-qfq-php:
// DB_n ...
// ...
config.qfq.php
^^^^^^^^^^^^^^
// LDAP_1_RDN => 'ou=Admin,ou=example,dc=com'
// LDAP_1_PASSWORD => 'mySecurePassword'
];
**DEPRECATED** : use `qfq.json` as described above. :ref:`qfq.json`
.. _extension-manager-qfq-configuration:
Extension Manager: QFQ Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* These configuration values can be overwritten by `qfq.json`. :ref:`qfq.json`
+-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
| Keyword | Default / Example | Description |
......@@ -418,6 +445,8 @@ Extension Manager: QFQ Configuration
| documentation | 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 |
+-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
| reportAsFileAutoExport | no | Auto export of qfq reports to files. See :ref:`reportAsFile` |
+-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
| Dynamic |
+-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
| fillStoreSystemBySql1/2/3 | SELECT s.id AS ... | Specific values read from the database to fill the system store during QFQ |
......
......@@ -2824,6 +2824,34 @@ Example::
]}'>
</div>
.. _reportAsFile:
Report As File
--------------
* If the toplevel token `file` is present inside the body of a QFQ tt-content element then the given report file is loaded and rendered.
* The tt-content body is ignored in that case.
* The path to the report file must be given relative to the report directory inside the qfq project directory. See :ref:`qfq-project-path-php`
* If the QFQ setting `reportAsFileAutoExport` (see :ref:`extension-manager-qfq-configuration`) is enabled, then every QFQ tt-content element which does not contain the `file` keyword is exported automatically when the report is rendered the first time.
* The path of the created file is given by the typo3 page structure
* The tt-content element body is replaced with `file=<path-to-new-file>`
Example tt-content body::
file=Home/myPage/qfq-report.qfqr
# Everything else is ignored!!
10.sql = SELECT 'This is ignored!!'
Example Home/myPage/qfq-report.qfqr::
# Some comment
10.sql = SELECT 'The file content is executed.'
Example of rendered report::
The file content is executed.
Report Examples
---------------
......
......@@ -48,7 +48,8 @@ class Path
// QFQ Project dir
private static $appToProject = null;
private const APP_TO_PROJECT_DEFAULT = '../';
private const APP_TO_PROJECT_MIGRATE = 'fileadmin/protected/qfqProject';
private const APP_TO_PROJECT_IN_PROTECTED = 'fileadmin/protected/qfqProject';
private const APP_TO_PROTECTED = 'fileadmin/protected';
const PROJECT_TO_FORM = 'form';
const FORM_TO_FORM_BACKUP = '_backup';
const PROJECT_DIR_TO_REPORT = 'report';
......@@ -426,10 +427,17 @@ class Path
// does the deprecated config.qfq.php exist? => migrate to qfq.json
} elseif (HelperFile::isReadableException(self::cwdToApp(self::APP_TO_TYPO3_CONF, CONFIG_QFQ_PHP))) {
self::setAppToProject(self::APP_TO_PROJECT_MIGRATE);
self::setAppToProject(self::APP_TO_PROJECT_IN_PROTECTED);
self::writeProjectPathPhp();
Config::migrateConfigPhpToJson();
// does fileadmin/protected exist? => set fileadmin/protected/qfqProject as project path
} elseif (file_exists(self::cwdToApp(self::APP_TO_PROTECTED))) {
$cwdToProject = self::cwdToApp(self::APP_TO_PROJECT_IN_PROTECTED);
HelperFile::createPathRecursive($cwdToProject);
self::setAppToProject($cwdToProject);
self::writeProjectPathPhp();
// create qfq.project.path.php at default location
} else {
self::setAppToProject(self::APP_TO_PROJECT_DEFAULT);
......@@ -450,11 +458,7 @@ class Path
/**
QFQ project path configuration
******************************************************-----********************************
* ATTENTION: The files in the project directory should NOT be served by your http server! *
******************************************************-----********************************
!! ATTENTION !!: The files in the project directory should NOT be served by your http server!
Only exception: The app directory inside the project directory may be served.
*/
......
{
"DB_1_USER": "<DBUSER>",
"DB_1_SERVER": "<DBSERVER>",
"DB_1_PASSWORD": "<DBPW>",
"DB_1_NAME": "<DB>",
"DB_2_USER": "<OPTIONAL DBUSER>",
"DB_2_SERVER": "<OPTIONAL DBSERVER>",
"DB_2_PASSWORD": "<OPTIONAL DBPW>",
"DB_2_NAME": "<OPTIONAL DB>",
"LDAP_1_RDN": "<OPTIONAL> ou=Admin,ou=example,dc=com",
"LDAP_1_PASSWORD": "<OPTIONAL> mySecurePassword"
}
\ No newline at end of file
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