Manual.rst: update Drag and Drop documentation.

extension/Documentation/Manual.rst

@@ -6236,6 +6236,7 @@ E.g.::
 
     10.sql = SELECT "p:home&r=0|t:Home|c:qfq-100 qfq-left" AS _pagev
 
+.. _drag_and_drop:
 
 Drag and drop
 -------------
@@ -6243,14 +6244,16 @@ Drag and drop
 Sort/order elements
 ^^^^^^^^^^^^^^^^^^^
 
-Manually sorting and ordering of elements via `HTML5 drag and drop` is supported via QFQ. Any sortable element
+Manually sorting and ordering of elements via `HTML5 drag and drop` is supported via QFQ. Any element to sort
 should be represented by a database record with an order column. If the elements are unordered, they will be ordered after
 the first 'drag and drop' move of an element.
 
 Functionality is divided into:
 
 * Display list: the records will be displayed via QFQ/report.
-* Update database: updates of the order column are managed by a specific 'drag and drop' definition form.
+* Sort records: updates of the order column are managed by a specific definition form. The form is not a regular form
+  (e.g. there are no FormElements), instead it's only a container to held the SQL update query as well as providing
+  access control via SIP. The form is automatically called via AJAX.
 
 Part 1: Display list
 ''''''''''''''''''''
@@ -6259,7 +6262,7 @@ Display the list of elements via a regular QFQ content record. All 'drag and dro
 element:
 
 * With `class="qfq-dnd-sort"`.
-* With an automatically SIP protected form name: `{{'form=<form name>' AS _data-dnd-api}}`
+* With a form name: `{{'form=<form name>' AS _data-dnd-api}}`
 * Only direct children of such element can be dragged.
 * Every children needs a unique identifier `data-dnd-id="<unique>"`. Typically this is the corresponding record id.
 * The record needs a dedicated order column, which will be updated through API calls in time.
@@ -6293,7 +6296,7 @@ A typical QFQ report which generates those `<div>` HTML: ::
 
 
 A `<table>` based setup is also possible. Note the attribute  `data-columns="3"` - those generates a dropzone
-which is the same width as the outer table. ::
+which the same width as the outer table. ::
 
     <table>
         <tbody class="qfq-dnd-sort" data-dnd-api="typo3conf/ext/qfq/qfq/api/dragAndDrop.php?s=badcaffee1234" data-columns="3">
@@ -6321,10 +6324,10 @@ A typical QFQ report which generates those HTML: ::
       tail = </tbody><table>
     }
 
-Part 2: Update database
-'''''''''''''''''''''''
+Part 2: Sort records
+''''''''''''''''''''
 
-A dedicated `Form`, without any `FormElements`, is needed to define the database update definition.
+A dedicated `Form`, without any `FormElements`, is used to define the database update definition.
 
 Fields:
 
@@ -6345,7 +6348,7 @@ Fields:
 | ORDER BY n.ord}}                                      | The columns `id` and `ord` are *mandatory.*                  |
 +-------------------------------------------------------+--------------------------------------------------------------+
 
-The form related to the example of part 1: ::
+The form related to the example of part 1 ('div' or 'table'): ::
 
   Form.name: dndSortNote
   Form.table: Note
@@ -6353,6 +6356,15 @@ The form related to the example of part 1: ::
   Form.parameter: orderColumn = ord
   Form.parameter: dragAndDropOrderSql = {{!SELECT n.id AS id, n.ord AS ord FROM Note AS n WHERE n.grId={{grId:S0}} ORDER BY n.ord}}
 
+QFQ iterates over the result set of `dragAndDropOrderSql`. The value of column `id` have to correspond to the dragged HTML
+ (given by `data-dnd-id`). Reordering always start with `orderInterval` and is incremented by `orderInterval` with each
+ record of the result set. The client reports the id of the dragged HTML element, the id of the hovered element and if
+ it is above or below the hovered element. This information is compared to the result set and applied where appropriate.
+ Only changes are applied.
+
+ Take care that the query of part 1 (display list) does a) select the same records and b) in the same order as the query
+ defined in part 2 (sort records) via `dragAndDropOrderSql`.
+
 Report Examples
 ---------------