Commit 223f4ff3 authored by Carsten  Rose's avatar Carsten Rose
Browse files

Manual.rst: update Drag and Drop documentation.

parent 21ef7453
......@@ -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
---------------
......
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