Manural.rst: refactor header line token. start to document FE annotation element.

extension/Documentation/Manual.rst

@@ -3,7 +3,7 @@
 .. ==
 ..  --
 ..   ^^
-..    ''
+..    ""
 ..     ;;
 ..      ,,
 ..
@@ -120,12 +120,12 @@ If there are problems with converting/downloading FE_GROUP protected pages, chec
 
 
 HTML to PDF conversion
-''''''''''''''''''''''
+""""""""""""""""""""""
 
 `wkhtmltopdf` converts a website (local or remote) to a (multi)-page PDF file. It's mainly used in `download`_.
 
 Print
-'''''
+"""""
 
 Different browser prints the same page in different variations. To prevent this, QFQ implements a small PHP wrapper
 `print.php` with uses `wkhtmltopdf` to convert HTML to PDF.
@@ -587,7 +587,7 @@ error message: ::
 .. _`periodId`:
 
 periodId
-''''''''
+""""""""
 
 This is
 
@@ -837,14 +837,14 @@ Multi Database
 ^^^^^^^^^^^^^^
 
 Base: T3 & QFQ
-''''''''''''''
+""""""""""""""
 
 QFQ typically interacts with one database, the QFQ database. The database used by Typo3 is typically a separate one.
 Theoretically it might be the same (never tested), but it's strongly recommended to use a separated QFQ database to have
 no problems on Typo3 updates and to have a clean separation between Typo3 and QFQ.
 
 QFQ: System & Data
-''''''''''''''''''
+""""""""""""""""""
 
 QFQ itself can be separated in 'QFQ system' (see `system-tables`_) and 'QFQ data' databases (even more than one are
 possible). The 'QFQ system' stores the forms, record locking, log tables and so on - `QFQ data` is for the rest.
@@ -852,7 +852,7 @@ possible). The 'QFQ system' stores the forms, record locking, log tables and so
 A `Multi Database` setup is given, if 'QFQ system' is different from 'QFQ data'.
 
 Data: Data1, Data2, ..., Data n
-'''''''''''''''''''''''''''''''
+"""""""""""""""""""""""""""""""
 
 Every database needs to be configured via `configuration`_ with it's own `index`.
 
@@ -1321,13 +1321,13 @@ SQL variables
 * The number of variables inside an input field or a SQL statement is not limited.
 
 Result: string
-''''''''''''''
+""""""""""""""
 
 A result of a SQL statement will be imploded over all: concat all columns of a row, concat all rows - there is no
 glue string.
 
 Result: row
-'''''''''''
+"""""""""""
 
 A few functions needs more than a returned string, instead separate columns are necessary. To indicate an array
 result, specify those with an '!': ::
@@ -1338,7 +1338,7 @@ This manual will specify the individual QFQ elements, who needs an array instead
 a string where an array is needed and vice versa.
 
 Database index
-''''''''''''''
+""""""""""""""
 
 To access different databases in a `multi-database`_  setup, the database index can be specified after the opening curly
 braces. ::
@@ -1354,7 +1354,7 @@ If no dbIndex is given, `{{indexData:Y}}` is used.
 
 
 Example
-'''''''
+"""""""
 
 ::
 
@@ -1368,7 +1368,7 @@ Example
 .. _`row-column-variables`:
 
 Row column variables
-^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""
 
 Syntax:  *{{<level>.<column>}}*
 
@@ -2285,7 +2285,7 @@ Forward: Save / Close
 ^^^^^^^^^^^^^^^^^^^^^
 
 Forward (=forwardMode)
-''''''''''''''''''''''
+""""""""""""""""""""""
 
 After the user presses *Save*, *Close*, *Delete* or *New*, different actions are possible where the browser redirects to.
 
@@ -2306,7 +2306,7 @@ After the user presses *Save*, *Close*, *Delete* or *New*, different actions are
 Only with `Forward` == `url` | `url-skip-history`, the definition of `Forward URL / Page` becomes active.
 
 Forward URL / Page (=forwardPage)
-'''''''''''''''''''''''''''''''''
+"""""""""""""""""""""""""""""""""
 
 Format: [<url>] or [<mode>|<url>]
 
@@ -2468,7 +2468,7 @@ Parameter
 .. _submitButtonText:
 
 submitButtonText
-''''''''''''''''
+""""""""""""""""
 
 If specified and non empty, display a regular submit button at the bottom of the page with the given text.
 This gives the form a ordinary HTML-form look'n' feel. With this option, the standard buttons on the top right border
@@ -2478,7 +2478,7 @@ should be hided to not confuse the user.
 * Default: Empty
 
 class
-'''''
+"""""
 
 * Optional.
 * Default: `container`
@@ -2490,7 +2490,7 @@ class
   * Expand the form over the whole area: `container-fluid`
 
 classPill
-'''''''''
+"""""""""
 
 * Optional.
 * Default: `qfq-color-grey-1`
@@ -2502,7 +2502,7 @@ classPill
 * `classPill` is only visible on forms with container elements of type 'Pill'.
 
 classBody
-'''''''''
+"""""""""
 
 * Optional.
 * Default: `qfq-color-grey-2`
@@ -2517,7 +2517,7 @@ classBody
   `qfq-color-blue-1` (dark), `qfq-color-blue-2`. (light)
 
 extraDeleteForm
-'''''''''''''''
+"""""""""""""""
 
 Depending on the database definition, it might be necessary to delete the primary record *and* corresponding slave records.
 To not repeat such 'slave record delete definition', an 'extraDeleteForm' can be specified. If the user opens a record
@@ -2533,7 +2533,7 @@ See also: `delete-record`_.
 .. _form-mode-global:
 
 Form mode global
-''''''''''''''''
+""""""""""""""""
 
 The Form global mode `mode` is given by default with `{{formModeGlobal:SE:alnumx}}`.
 
@@ -2678,14 +2678,14 @@ The placeholder `%d` can also be used in the *FormElement.label*
 Example of styling the Add/ Delete Button: :ref:`example_class_template_group`
 
 Column: primary record
-''''''''''''''''''''''
+""""""""""""""""""""""
 
 If the columns `<name>%d` are real columns on the primary table, saving and delete (=empty string) are done automatically.
 E.g. if there are up to five elements `grade1, ..., grade5` and the user inputs only the first three, the remaining will be set
 to an empty string.
 
 Column: non primary record
-''''''''''''''''''''''''''
+""""""""""""""""""""""""""
 
 Additional logic is required to load, update, insert and/or delete slave records.
 
@@ -2975,7 +2975,8 @@ See also at specific *FormElement* definitions.
  * `s/d/n`: string or date or number.
 
 Native *FormElements*
-'''''''''''''''''''''
+"""""""""""""""""""""
+
 * Like 'input', 'checkbox', ...
 
 .. _`input-option-autofocus`:
@@ -3173,7 +3174,7 @@ Type: text
 .. _`input-typeahead`:
 
 Type Ahead
-''''''''''
+""""""""""
 
 Activating `typeahead` functionality offers an instant lookup of data and displaying them to the user, while the user is
 typing, a drop-down box offers the results. As datasource the regular SQL connection or a LDAP query can be used.
@@ -3264,23 +3265,73 @@ Type: editor
 Type: annotate
 ^^^^^^^^^^^^^^
 
-The `Formelement`.type=`annotate` is a simple grafic editor which, for example, can be used to annotate images. All modifications to
-an image are saved as a JSON fabric.js data string in the current FormElement column.
+Annotate image or text. Typically the image or text has been uploaded during a previous step. The annotation will be
+saved in *FormElement.name* column of the current record. The uploaded file itself will not be modified. The annotations
+can be shown in edit or readonly mode and modified again.
+
+Two modes are available:
+
+image
+    A simple grafic editor to paint on top of the image (best by a tablet with pen or grafic tablet). The uploaded image
+    is shown in the background. All drawings are saved as a JSON fabric.js data string. Supported file types:
+    **png, svg**. PDF files can be easily divided into per page SVG files during upload - see `split-pdf-upload`_
+
+text
+    Per code line, annotation(s) can be added. Different users can add individual annotations. A user can only edit the
+    own annotations. The annotations are saved as QFQ internal JSON string.
+
+
+.. note::
+
+    Drawing with fabric.js might produce a lot data. Take care the column type/size is big enough (>=64kB).
+
+
+Image
+"""""
 
 An image, specified by `FormElement.parameter`: imageSource={{pathFileName}}, will be displayed in the background. On
 form load, both, the image and an optional already given JSON fabric.js data string, will be displayed. The image is SIP
 protected and will be loaded on demand.
 
-The original image file is not modified. The user drawings are stored in the fabric.js data string.
+**Form.parameter**
 
-* *FormElement.parameter*:
++-------------------+-----------------------+----------------------------------------------------------------------------------+
+| Attribute         | Value                 | Description                                                                      |
++===================+=======================+==================================================================================+
+| annotateType      | grafic                | *grafic|text*. Default is *grafic*. Select mode.                                 |
++-------------------+-----------------------+----------------------------------------------------------------------------------+
+| imageSource       | {{pathFileName2}}     | Background image. E.g. `fileadmin/images/scan.png`                               |
++-------------------+-----------------------+----------------------------------------------------------------------------------+
+| defaultPenColor   |  <rgb hex value>      | Pen default color, after loading the fabric element. Default is '0000FF' (blue). |
++-------------------+----------------------------------------------------------------------------------------------------------+
 
-  * *imageSource* ={{pathFileName2}} -  Background image. E.g. `fileadmin/images/scan.jpg`.
-  * *defaultPenColor* = <rgb hex value> -  Pen default color, after loading the fabric element. Default is '0000FF' (blue).
+.. note::
 
-By using the the `FormElement` `annotate`, the JS code `fabric.min.js` and `qfq.fabric.min.js` has to be included.
+    By using the the `FormElement` `annotate`, the JS code `fabric.min.js` and `qfq.fabric.min.js` has to be included.
 See setup-css-js_.
 
+Code
+""""
+
+**Form.parameter**
+
++-------------------+-----------------------+----------------------------------------------------------------------------------+
+| Attribute         | Value                 | Description                                                                      |
++===================+=======================+==================================================================================+
+| annotateType      | text                  | *grafic|text*. Default is *grafic*. Select mode.                                 |
++-------------------+-----------------------+----------------------------------------------------------------------------------+
+| textSource       | {{pathFileName2}}     | Background image. E.g. `fileadmin/images/scan.png`                               |
++-------------------+-----------------------+----------------------------------------------------------------------------------+
+| defaultPenColor   |  <rgb hex value>      | Pen default color, after loading the fabric element. Default is '0000FF' (blue). |
++-------------------+----------------------------------------------------------------------------------------------------------+
+
+annotateType=grafic|text
+textSource (vergleichbar mit imageSource fuer fabric Elemente)
+annotateUserName, annotateUserUid, annotateUserAvatar
+highlight=off,auto,javascript,qfq,python,matlab
+
+
+
 Type: imageCut
 ^^^^^^^^^^^^^^
 
@@ -3701,7 +3752,7 @@ The maximum size is defined by the minimum of `upload_max_filesize`, `post_max_s
 In case of broken uploads, please also check `max_input_time` in php.ini.
 
 Deleting a record and the referenced file
-'''''''''''''''''''''''''''''''''''''''''
+"""""""""""""""""""""""""""""""""""""""""
 
 If the user deletes a record (e.g. pressing the delete button on a form) which contains reference(s) to files, such files
 are deleted too. Slave records, which might be also deleted through a 'delete'-form, are *not* checked for file references
@@ -3716,7 +3767,7 @@ have multiple references to a single file. Therefore this check is just a fallba
 .. _Upload simple mode:
 
 Upload simple mode
-''''''''''''''''''
+""""""""""""""""""
 
 Requires: *'upload'-FormElement.name = 'column name'* of an column in the primary table.
 
@@ -3734,7 +3785,7 @@ Multiple 'upload'-FormElements per form are possible. Each of it needs an own ta
 .. _Upload advanced mode:
 
 Upload advanced mode
-''''''''''''''''''''
+""""""""""""""""""""
 
 Requires: *'upload'-FormElement.name* is unknown as a column in the primary table.
 
@@ -3779,7 +3830,7 @@ A typical name for such an 'upload'-FormElement, to show that the name does not
 .. _split-pdf-upload:
 
 Split PDF Upload
-''''''''''''''''
+""""""""""""""""
 
 Additional to the upload, it's possible to split the uploaded file (only PDF files) into several SVG or JPEG files, one
 file per PDF page. The split is done via http://www.cityinthesky.co.uk/opensource/pdf2svg/ or Image Magick `convert`.
@@ -3849,7 +3900,7 @@ Types:
 .. _sqlValidate:
 
 Parameter: sqlValidate
-''''''''''''''''''''''
+""""""""""""""""""""""
 
   Perform checks by fireing a SQL query and expecting a predefined number of selected records.
 
@@ -3875,7 +3926,7 @@ Parameter: sqlValidate
 .. _slave-id:
 
 Parameter: slaveId
-''''''''''''''''''
+""""""""""""""""""
 
 *FormElement.parameter*:
 
@@ -3896,7 +3947,7 @@ Note:
   * After an INSERT the `last_insert_id()` becomes the *slaveId*).
 
 Parameter: sqlBefore / sqlInsert / sqlUpdate / sqlDelete / sqlAfter
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
   * Save values of a form to different record(s), optionally on different table(s).
   * Typically useful on 'afterSave' - be careful when using it earlier, e.g. beforeLoad.
@@ -3925,7 +3976,7 @@ Parameter: sqlBefore / sqlInsert / sqlUpdate / sqlDelete / sqlAfter
 
 
 Example
-'''''''
+"""""""
 
 Situation 1: master.xId=slave.id (1:1)
 
@@ -4032,7 +4083,7 @@ from the www.example.com and ?export (with the attachment filename 'personal.pdf
   sendMailAttachmemt = F:fileadmin/file1.pdf|d:readme.pdf|C|u:http://www.example.com|p:?id=export&r=123&_sip=1|d:personal.pdf
 
 Type: paste
-'''''''''''
+"""""""""""
 
 See also `copy-form`_.
 
@@ -4222,7 +4273,7 @@ Examples
 * Master FormElement 'music' is a radio/enum of 'classic', 'jazz', 'pop'.
 
 Content of a select list
-''''''''''''''''''''''''
+""""""""""""""""""""""""
 
 * Slave FormElement 'interpret' is 'select'-list, depending of 'music'
 
@@ -4231,7 +4282,7 @@ Content of a select list
    sql={{!SELECT name FROM interpret WHERE music={{music:FE:alnumx}} ORDER BY name}}
 
 Show / Hide a *FormElement*
-'''''''''''''''''''''''''''
+"""""""""""""""""""""""""""
 
 * Slave 'interpret' is displayed only for 'pop'. Field 'modeSql':
 
@@ -4451,7 +4502,7 @@ Custom default value only for 'new records'
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Method 1
-''''''''
+""""""""
 
 On `Form.parameter` define a `fillStoreVar` query with a column name equal to a form field. That's all.
 
@@ -4464,7 +4515,8 @@ What we use here is the default STORE prio FSRVD. If the form loads with r=0, 'F
 If r>0, than 'F' and 'S' are empty and 'R' is filled.
 
 Method 2
-''''''''
+""""""""
+
 In the specific `FormElement` set `value={{columnName:RSE}}`. The link to the form should be rendered with
 '"...&columnName=<data>&..." AS _page'. The trick is that the STORE_RECORD is empty for new records, and therefore the
 corresponding value from STORE_SIP will be returned. Existing records will use the already saved value.
@@ -4530,7 +4582,7 @@ Requirement: new records should automatically get the highest number plus 10 for
 should not be altered.
 
 Version 1
-'''''''''
+"""""""""
 
 Compute the next 'ord' in advance in the subrecord field of the primary form. Submit that value to the new record
 via SIP parameter to the secondary form.
@@ -4551,7 +4603,7 @@ unchanged.
    `{{ord:RS0}}`.
 
 Version 2
-'''''''''
+"""""""""
 
 Compute the next 'ord' as default value direct inside the secondary form. No change is needed for the primary form.
 
@@ -5196,7 +5248,7 @@ Example::
     20.tail = </h3>
 
 Join mode: SQL
-''''''''''''''
+""""""""""""""
 
 This is the default. All lines are joined with a *space* in between. E.g.::
 
@@ -5208,7 +5260,7 @@ Results to: ``10.sql = SELECT 'hello world' FROM mastertable``
 Notice the space between "...world'" and "FROM ...".
 
 Join mode: strip whitespace
-'''''''''''''''''''''''''''
+"""""""""""""""""""""""""""
 
 Ending a line with a '\\' strips all leading and trailing whitespaces of that line joins the line directly (no extra
 space in between). E.g.::
@@ -5783,7 +5835,7 @@ file is multiple times referenced, than the file is not deleted (it would break
 references are not found, if they use different colummnnames or tablenames.
 
 Mode: table
-'''''''''''
+"""""""""""
 
 * `table=<table name>`
 * `r=<record id>`
@@ -5791,7 +5843,7 @@ Mode: table
 Deletes the record with id '<record id>' from table '<table name>'.
 
 Mode: form
-''''''''''
+""""""""""
 
 * `form=<form name>`