Twig new

During the last two days I implemented a few improvments:

• Doku
• first Base-Templates
• add stores to context
• Bug: 10.twig = must start with single quote only
• Bug: vars passed to twig are not availabel TS afterwards

Unittests would still be nice to have, but I think it's better to integrate this now and improve later then to wait any longer.

Documentation/Manual.rst

@@ -730,6 +730,8 @@ Insert one or more QFQ content elements on a Typo3 page. Specify column and lang
 The title of the QFQ content element will not be rendered on the frontend. It's only visible to the webmaster in the
 backend for orientation.
 
+.. _qfq_keywords:
+
 QFQ Keywords (Bodytext)
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -787,6 +789,8 @@ QFQ Keywords (Bodytext)
  +-------------------+---------------------------------------------------------------------------------+
  | <level>.sql       | SQL Query                                                                       |
  +-------------------+---------------------------------------------------------------------------------+
+ | <level>.twig      | Twig Template                                                                   |
+ +-------------------+---------------------------------------------------------------------------------+
  | <level>.althead   | If <level>.sql is empty, these token will be rendered.                          |
  +-------------------+---------------------------------------------------------------------------------+
  | <level>.altsql    | If <level>.sql is empty, these query will be fired. No sub queries.             |
@@ -794,6 +798,8 @@ QFQ Keywords (Bodytext)
  +-------------------+---------------------------------------------------------------------------------+
  | <level>.content   | | *show* (default): content of current and sub level are directly shown.        |
  |                   | | *hide*: content of current and sub levels are stored and not shown.           |
+ |                   | | *hideLevel*: content of current and sub levels are stored and only sub levels |
+ |                   | | are shown.                                                                    |
  |                   | | *store*: content of current and sub levels are stored and shown.              |
  |                   | | To retrieve the content: `{{<level>.line.content}}`. See `syntax-of-report`_  |
  +-------------------+---------------------------------------------------------------------------------+
@@ -5170,7 +5176,7 @@ A simple example
 
 Assume that the database has a table person with columns firstName and lastName. To create a simple list of all persons, we can do the following::
 
-    10.sql = SELECT id AS pId, CONCAT(firstName, " ", lastName, " ") AS name FROM person
+    10.sql = SELECT firstName, lastName FROM person
 
 The '10' indicates a *root level* of the report (see section `Structure`_). The expresssion '10.sql' defines a SQL query
 for the specific level. When the query is executed, it will return a result having one single column name containing first and last name
@@ -5178,21 +5184,65 @@ separated by a space character.
 
 The HTML output, displayed on the page, resulting from only this definition, could look as follows::
 
-    John DoeJane MillerFrank Star
+    JohnDoeJaneMillerFrankStar
 
 
 I.e., QFQ will simply output the content of the SQL result row after row for each single level.
 
-However, we can modify (wrap) the output by setting the values of various keys for each level: 10.rsep=<br/> for example
-tells QFQ to separate the rows of the result by a HTML-line break. The final result in this case is::
+Format output: mix style and content
+""""""""""""""""""""""""""""""""""""
 
-    10.sql = SELECT id AS personId, CONCAT(firstName, " ", lastName, " ") AS name FROM person
-    10.rsep = <br>
+Variant 1: pure SQL
+;;;;;;;;;;;;;;;;;;;
+
+To format the upper example, just create additional columns::
+
+    10.sql = SELECT firstName, ", ", lastName, "<br>" FROM person
+
+HTML output::
+
+    Doe, John<br>
+    Miller, Jane<br>
+    Star, Frank<br>
+
+Variant 2: SQL plus QFQ helper
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+QFQ provides several helper functions to wrap rows and columns, or to separate them. In this example 'fsep'='field
+separate and 'rend' = row end:
+
+    10.sql = SELECT firstName, lastName FROM person
+    10.fsep = ', '
+    10.rend = <br>
+
+HTML output::
+
+    Doe, John<br>
+    Miller, Jane<br>
+    Star, Frank<br>
+
+Check out all QFQ helpers under qfq_keywords_.
+
+Due to mixing style and content, this becomes harder to maintain with more complex layout.
+
+Format output: separate style and content
+"""""""""""""""""""""""""""""""""""""""""
+
+The result of the query can be passed to the `Twig template engine <https://twig.symphony.com/>`_
+in order to fill a template with the data.::
+
+    10.sql = SELECT firstName, lastName FROM person
+    10.twig = {% for row in result %}
+        {{ row.lastName }}, {{ row.firstName }<br />
+    {% endfor %}
 
 HTML output::
 
-    John Doe<br>Jane Miller<br>Frank Star
+    Doe, John<br>
+    Miller, Jane<br>
+    Star, Frank<br>
 
+Check out using-twig_.
 
 .. _`syntax-of-report`:
 
@@ -5257,8 +5307,103 @@ Processing of the resulting rows and columns:
 
 There are extensive ways to wrap columns and rows. See :ref:`wrapping-rows-and-columns`
 
+.. _`using-twig`:
+
+Using Twig
+----------
+
+How to write Twig templates is documented by the `Twig Project <https://twig.symphony.com/>`_.
+
+QFQ passes the result of a given query to the corresponding Twig template using the Twig variable
+`result`. So templates need to use this variable to access the result of a query.
+
+Specifying a Template
+^^^^^^^^^^^^^^^^^^^^^
+By default the string passed to the **twig**-key is used as template directly,
+as shown in the simple example above::
+
+   10.twig = {% for row in result %}
+       {{ row.lastName }}, {{ row.firstName }<br />
+   {% endfor %}
+
+However, if the string starts with **file:**, the template is read from the
+file specified.::
+
+   10.twig = file:table_sortable.html.twig
+
+The file is searched relative to *<site path>* and if the file is not found there, it's searched relative to
+QFQ's *twig_template* folder where the included base templates are stored.
+
+The following templates are available:
+
+``tables/default.html.twig``
+  A basic table with column headers, sorting and column filters using tablesorter and bootstrap.
+
+``tables/single_vertical.html.twig``
+  A template to display the values of a single record in a vertical table.
+
+Links
+^^^^^
+The link syntax described in column-link_ is available inside Twig templates
+using the `qfqlink` filter::
+
+  {{ "u:http://www.example.com" | qfqlink }}
+
+will render a link to *http://www.example.com*.
+
+Available Store Variables
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+QFQ also provides access to the following stores via the template context.
+
+  * record
+  * sip
+  * typo3
+  * user
+  * system
+
+All stores are accessed using their lower case name as attribute of the
+context variable `store`. The active Typo3 front-end user is therefore available as::
+
+  {{ store.typo3.feUser }}
+
+A realistic example
+^^^^^^^^^^^^^^^^^^^
+The following block shows a more realistic example of a QFQ report.
+
+*10.sql* selects all users who have been assigned files in our file tracker.
+
+.. TODO use content = hide instead of _user once this is implemented
+
+*10.10* then selects all files belonging to this user, prints the username as header
+and then displays the files in a nice table with links to the files.
+
+::
+
+      10.sql = SELECT assigned_to AS _user FROM file_tracker
+      WHERE assigned_to IS NOT NULL
+      GROUP BY _user
+      ORDER BY _user
+
+      10.10.sql = SELECT id, path_scan FROM file_tracker
+      WHERE assigned_to = '{{user:R}}'
+      10.10.twig = <h2>{{ store.record.user }}</h2>
+      <table id="file-list" class="table table-hover tablesorter">
+        <thead><tr><th>ID</th><th>File</th></tr></thead>
+        <tbody>
+        {% for row in result %}
+          <tr>
+            <td>{{ row.id }}</td>
+            <td>{{ ("d:|M:pdf|s|t:"~ row.path_scan ~"|F:" ~ row.path_scan ) | qfqlink }}</td>
+          </tr>
+        {% endfor %}
+        </tbody>
+      </table>
+
+
 Debug the bodytext
 ------------------
+
 The parsed bodytext could be displayed by activating 'showDebugInfo' (:ref:`debug`) and specifying
 
 ::
@@ -5546,6 +5691,11 @@ Processing of columns in the SQL result
 Special column names
 --------------------
 
+.. note::
+
+    Twig: respect that the 'special column name'-columns are rendered before Twig becomes active. The recommended
+    way by using Twig is *not to use* special column names at all. Use the Twig version *qfqLink*.
+
 QFQ typically don't care about the content of any SQL-Query - it just copy the content to the output (=Browser).
 
 One exception are columns, whose name starts with '_'.  E.g.::