Add picker widget (#1040)

* add documentation for picker widget * add link
contao · May 15, 2022 · 91b9c29 · 91b9c29
1 parent 66ed78b
commit 91b9c29
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 3 deletions.
diff --git a/docs/dev/reference/dca/fields.md b/docs/dev/reference/dca/fields.md
@@ -37,7 +37,7 @@ $GLOBALS['TL_DCA']['tl_example']['fields']['myfield'] = [
 | filter               | true/false (`bool`)                             | If true the field will be included in the filter menu (see "sorting records" -> "panelLayout").                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | flag                 | Sorting mode (`integer`)                        | **1** Sort by initial letter ascending <br>**2** Sort by initial letter descending <br>**3** Sort by initial X letters ascending (see length) <br>**4** Sort by initial X letters descending (see length) <br>**5** Sort by day ascending <br>**6** Sort by day descending <br>**7** Sort by month ascending <br>**8** Sort by month descending <br>**9** Sort by year ascending <br>**10** Sort by year descending <br>**11** Sort ascending <br>**12** Sort descending<br><br><i>Note:</i> flags 5 through 10 will also enable formatting of timestamps in the back end when used as a label somewhere.                                                                                                                                                                        |
 | length               | Sorting length (`integer`)                      | Allows to specify the number of characters that are used to build sorting groups (flag **3** and **4**).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| inputType            | Field type (`string`)                           | [`checkbox`][CheckboxWidget] Checkbox <br>`checkboxWizard` Checkbox Wizard <br>`chmod` CHMOD table <br>`fileTree` File tree <br>`imageSize` Two text fields with drop-down menu (creates an [Image Size Array](/framework/image-processing/image-sizes/#size-array)) <br>`inputUnit` Text field with small unit drop-down menu <br>`keyValueWizard` Key » Value wizard <br>[`listWizard`][ListWizardWidget] List wizard <br>`metaWizard` Used for setting meta information in the file manager <br>`moduleWizard` Module wizard <br>`optionWizard` Option wizard <br>`pageTree` Page tree <br>`password` Password field <br>`picker` General purpose picker <br>`radio` Radio button <br>`radioTable` Table with images and radio buttons <br>`sectionWizard` Used for defining sections in the page layout <br>[`select`][SelectWidget] Drop-down menu <br>`serpPreview` Search Engine Result Preview (SERP) widget <br>`tableWizard` Table wizard <br>`text` Text field <br>`textStore` Text field that will not display its current value <br>`textarea` Textarea <br>`timePeriod` Text field with drop-down menu <br>`trbl` Four text fields with a small unit drop-down menu |
+| inputType            | Field type (`string`)                           | [`checkbox`][CheckboxWidget] Checkbox <br>`checkboxWizard` Checkbox Wizard <br>`chmod` CHMOD table <br>`fileTree` File tree <br>`imageSize` Two text fields with drop-down menu (creates an [Image Size Array](/framework/image-processing/image-sizes/#size-array)) <br>`inputUnit` Text field with small unit drop-down menu <br>`keyValueWizard` Key » Value wizard <br>[`listWizard`][ListWizardWidget] List wizard <br>`metaWizard` Used for setting meta information in the file manager <br>`moduleWizard` Module wizard <br>`optionWizard` Option wizard <br>`pageTree` Page tree <br>`password` Password field <br>[`picker`][PickerWidget] General purpose picker <br>`radio` Radio button <br>`radioTable` Table with images and radio buttons <br>`sectionWizard` Used for defining sections in the page layout <br>[`select`][SelectWidget] Drop-down menu <br>`serpPreview` Search Engine Result Preview (SERP) widget <br>`tableWizard` Table wizard <br>`text` Text field <br>`textStore` Text field that will not display its current value <br>`textarea` Textarea <br>`timePeriod` Text field with drop-down menu <br>`trbl` Four text fields with a small unit drop-down menu |
 | options              | Options (`array`)                               | Options of a drop-down menu or radio button menu.<br />Specify as `['opt1', 'opt2', 'opt3']` or `['value1' => 'label1', 'value2' => 'label2']`.<br />Special case **ambiguous numerical value/index**: `[0 => 'label1', 1 => 'label2']` or `['0' => 'label1', '1' => 'label2']`: If option values are integers and starting with 0, the label will also be used as value. Use the eval option `isAssociative` to prevent this.                                                                                                                                                                                                                  |
 | [options_callback](../callbacks/#fields-field-options)         | Callback function (`array`)                     | Callback function that returns an array of options. Please specify as `['Class', 'Method']`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | foreignKey           | table.field (`string`)                          | Get options from a database table. Returns ID as key and the field you specify as value. The field can be a complete SQL expression, e.g.: `tl_member.CONCAT(firstname,' ',lastname)`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -316,4 +316,5 @@ the Doctrine Database Abstraction Layer.
 [TranslationDomain]: /framework/translations/#domains
 [CheckboxWidget]: /reference/widgets/checkbox/
 [ListWizardWidget]: /reference/widgets/list-wizard/
+[PickerWidget]: /reference/widgets/picker/
 [SelectWidget]: /reference/widgets/select/
diff --git a/docs/dev/reference/widgets/images/picker_content_element.png b/docs/dev/reference/widgets/images/picker_content_element.png
diff --git a/docs/dev/reference/widgets/images/picker_news.png b/docs/dev/reference/widgets/images/picker_news.png
diff --git a/docs/dev/reference/widgets/picker.md b/docs/dev/reference/widgets/picker.md
@@ -1,6 +1,101 @@
 ---
 title: "Picker"
-description: General purpose picker (not yet documented)
+description: General purpose picker.
 ---
 
-{{< widget-notice >}}
+This widget allows you to pick elements from arbitray data containers. The selected element will then be rendered in its back end view.
+
+This is used to pick a record for the "Content element" content element for example:
+
+![A content element picker](../images/picker_content_element.png?classes=shadow)
+
+When picking the element, a back end view will be rendered in the popup which allows you to switch between page articles, news articles,
+calendars etc. where you will be able to go into one of the parents to select a content element from there. The preview is then rendered via 
+the `child_record_callback` of `tl_content` in this case.
+
+You could also select news articles for example:
+
+![A news article picker](../images/picker_news.png?classes=shadow)
+
+The picker popup will show you the regular back end view of the news archives in this case which allows you to then select a news article
+from any of these archives.
+
+
+## Options
+
+This table only shows the options relevant to the core functionality of this widget. See the DCA reference for a [full field reference](../../dca/fields).
+
+| Key   | Value | Description
+| ----- | ----- | --------------- |
+| `inputType` | `picker` | |
+| `foreignKey` | `string` | Reference another table to pick from (can also be done via `relation`) |
+| `relation` | `array` | Reference another table to pick from via `'table' => 'tl_foobar'` |
+| `eval.multiple` | true/false (default) `bool` | Set this to true if you want to be able to select multiple values. |
+
+
+## Column Definition
+
+Depending on the widget configuration, the widget persists different values to the database. You have to take care of the correct SQL column 
+definition yourself. A **single** record will be saved as an integer, the primary key reference. **Multiple** selected values are stored as 
+a serialized array. Since you do not know the length in advance, a blob column is preferred. 
+
+
+## Examples
+
+{{< tabs >}}
+
+{{% tab name="News article" %}}
+
+```php
+// ...
+'myNewsReference' => [
+    'label' => ['Referenced news', 'Help text'],
+    'inputType' => 'picker',
+    'sql' => [
+        'type' => 'integer',
+        'unsigned' => true,
+        'default' => 0,
+    ],
+    'relation' => [
+        'type' => 'hasOne',
+        'load' => 'lazy',
+        'table' => 'tl_news',
+    ],
+],
+// ...
+```
+
+{{% /tab %}}
+
+{{% tab name="Multiple content elements" %}}
+
+```php
+// ...
+'myContentElements' => [
+    'label' => ['Referenced elements', 'Help text'],
+    'inputType' => 'picker',
+    'eval' => [
+        'multple' => true,
+    ],
+    'sql' => [
+        'type' => 'blob',
+        'notnull' => false,
+    ],
+    'relation' => [
+        'type' => 'hasMany',
+        'load' => 'lazy',
+        'table' => 'tl_content',
+    ],
+],
+// ...
+```
+
+{{% /tab %}}
+
+{{< /tabs >}}
+
+
+## Usage in Contao
+
+This picker is used for content element and article include content element as well as the article teaser content element in order to pick 
+and preview the referenced element or article.