Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add picker widget #1040

Merged
merged 2 commits into from
May 15, 2022
Merged

Add picker widget #1040

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e43d710
add documentation for picker widget
fritzmg May 14, 2022
85c1af6
add link
fritzmg May 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/dev/reference/dca/fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)` |
Expand Down Expand Up @@ -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/
Binary file added docs/dev/reference/widgets/images/picker_content_element.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/dev/reference/widgets/images/picker_news.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
99 changes: 97 additions & 2 deletions docs/dev/reference/widgets/picker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.