Add widget reference and document checkbox widget (#732)

* Add widget reference and document checkbox widget

* use short code for notice

* add eol

Co-authored-by: fritzmg <fmg@inspiredminds.at>

docs/dev/reference/widgets/_index.md

@@ -0,0 +1,16 @@
+---
+title: "Widgets"
+description: "Developer Reference for the Core widgets."
+aliases:
+  - /reference/widgets/
+---
+
+This section explains the Core widgets and gives examples. For a complete overview of all available options see the [full DCA field reference](../dca/fields).
+
+{{% notice info %}}
+
+This section is still **work in progress.** Please consider contributing when you research a widget configuration to help others! 
+
+{{% /notice %}}
+
+{{% children description="true" %}}

docs/dev/reference/widgets/checkbox-wizard.md

@@ -0,0 +1,9 @@
+---
+title: "Checkbox Wizard"
+description: Not yet documented
+---
+
+This widget is similar to the regular [Checkbox widget](/reference/widgets/checkbox) but it supports manual sorting of the multiple 
+checkboxes.
+
+{{< widget-notice >}}

docs/dev/reference/widgets/checkbox.md

@@ -0,0 +1,141 @@
+---
+title: "Checkbox"
+description: Renders one or multiple checkboxes.
+---
+
+This widget renders one or multiple checkboxes. Choose this if you want the editor to toggle a single property or select from a fixed set of options.
+
+A simple binary checkbox that allows the editor to toggle a boolean state:
+
+![A simple binary checkbox](../images/checkbox.png?classes=shadow)
+
+Multiple checkboxes to give the editor a defined set of options to select one or many options from:
+
+![Multiple checkboxes](../images/checkbox-multiple.png?classes=shadow)
+
+Multiple checkboxes to choose from as before, but grouped into categories: 
+
+![A nested set of checkboxes](../images/checkbox-grouped.png?classes=shadow)
+
+## 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` | `checkbox` | |
+| `options` | `array` | An options array (use in combination with `eval.multiple`) |
+| `options_callback` | `function\|callable` | A callback function that returns the options callback or an array  (use in combination with `eval.multiple`). You may define an anonymous function, but you should consider [registering them via annotations](../../../framework/dca/#registering-callbacks). |
+| `reference` | `array` | Reference an array that will be used to translate the options. Contao will automatically match the options and reference array by key. |
+| `foreignKey` | `string` | Reference another table to generate options from. |
+| `eval.multiple` | true/false (default) `bool` | Set this to true if you want to provide multiple options via `options` or `options_callback` |
+| `eval.includeBlankOption` | true/false (default) `bool` | Includes a blank option (useful in conjunction with `mandatory` fields) |
+| `eval.blankOptionLabel` | `string` (default `-`) | The label of the blank option |
+
+The `options` array – either set directly or returned by an options callback – can have different structures depending on what you are going for:
+
+1. `[ 'label1' , 'label2' ]` where the values of the checkbox input will be the regular array index.
+2. `[ 'value' => 'label' ]` where `value` will be the value of the checkbox input, and `label` the label.
+3. `[ 'foo' => ['a', 'b'], 'bar' => ['c', 'd'] ]` which will render two checkbox groups `foo` and `bar`.
+
+## 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** checkbox (toggle) will be saved as `'1'/'0'` (text column) or `true/false` (bool column). **Multiple** selected values are stored as serialized array. Since you do not know the length in advance, a blob column is prefered. 
+
+## Examples
+
+{{< tabs >}}
+
+{{% tab name="Toggle" %}}
+
+If you simply want to toggle a property:
+
+```php
+// ...
+'myCheckbox' => [
+    'label' => ['Checkbox', 'Help text'],
+    'inputType' => 'checkbox',
+    'sql' => [
+        'type' => 'boolean',
+        'default' => false,
+    ],
+],
+// ...
+```
+
+{{% /tab %}}
+
+{{% tab name="Fixed options" %}}
+
+If you want the editor to select from a fixed set of properties, you may define them via the `options` field. The selected options will be stored as a serialized array, so make sure your database field can store enough data.
+
+```php
+// ...
+'myCheckbox' => [
+    'label' => ['Checkbox', 'Help text'], // Or a reference to the global language array
+    'inputType' => 'checkbox',
+    'options' => [
+        'foo', 'bar', 'baz',
+    ],
+    'eval' => [
+        'multiple' => true,
+    ],
+    'sql' => [
+        'type' => 'blob',
+    ],
+],
+// ...
+```
+
+{{% /tab %}}
+
+{{% tab name="Dynamic options" %}}
+
+You can also dynamically generate the options array to filter them as you wish. See the [options callback](../../dca/callbacks#fields-field-options) for further examples.
+
+```php
+// ...
+'myCheckbox' => [
+    'label' => ['Checkbox', 'Help text'], // Or a reference to the global language array
+    'inputType' => 'checkbox',
+    'options_callback' => [
+        'Vendor\Class', 'getMyCheckboxOptions' // Defines a method that returns the options array. Class can be a service. 
+    ],
+    'eval' => [
+        'multiple' => true,
+    ],
+    'sql' => [
+        'type' => 'blob',
+    ],
+],
+// ...
+```
+
+{{% /tab %}}
+
+{{% tab name="Options from a table" %}}
+
+You can generate an options array from another table with the `foreignKey` property. 
+
+```php
+// ...
+'myUsers' => [
+    'label' => ['My Users', 'Help text'], // Or a reference to the global language array
+    'inputType' => 'checkbox',
+    'foreignKey' => 'tl_user.name', // Will use `name` as label, and the user `id` as value
+    'sql' => [
+        'type' => 'string',
+        'notnull' => false,
+        'default' => '',
+    ],
+],
+// ...
+```
+
+{{% /tab %}}
+
+{{< /tabs >}}
+
+## Usage in Contao
+
+Basically everywhere :-) The checkbox widget in its simplest configuration is often used to toggle [subpalettes](../../dca/palettes). 

docs/dev/reference/widgets/chmod.md

@@ -0,0 +1,6 @@
+---
+title: "CHMOD"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/file-tree.md

@@ -0,0 +1,6 @@
+---
+title: "File tree"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/image-size.md

@@ -0,0 +1,6 @@
+---
+title: "Image Size"
+description: Two text fields with drop-down menu (Not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/input-unit.md

@@ -0,0 +1,6 @@
+---
+title: "Input Unit"
+description: Text field with small unit drop-down menu (Not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/key-value-wizard.md

@@ -0,0 +1,6 @@
+---
+title: "Key-Value-Wizard"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/list-wizard.md

@@ -0,0 +1,6 @@
+---
+title: "List Wizard"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/meta-wizard.md

@@ -0,0 +1,6 @@
+---
+title: "Meta Wizard"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/module-wizard.md

@@ -0,0 +1,6 @@
+---
+title: "Module Wizard"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/option-wizard.md

@@ -0,0 +1,6 @@
+---
+title: "Option Wizard"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/page-tree.md

@@ -0,0 +1,6 @@
+---
+title: "Page Tree"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/picker.md

@@ -0,0 +1,6 @@
+---
+title: "Picker"
+description: General purpose picker (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/radio-table.md

@@ -0,0 +1,6 @@
+---
+title: "Radio Table"
+description: Table with images and radio buttons (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/radio.md

@@ -0,0 +1,6 @@
+---
+title: "Radio"
+description: Renders a single or multiple radio buttons (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/section-wizard.md

@@ -0,0 +1,6 @@
+---
+title: "Section Wizard"
+description: Used for defining sections in the page layout (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/select.md

@@ -0,0 +1,6 @@
+---
+title: "Select Menu"
+description: Drop-down menu (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/serp-preview.md

@@ -0,0 +1,6 @@
+---
+title: "SERP Preview"
+description: Search Engine Result Preview (SERP) widget (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/table-wizard.md

@@ -0,0 +1,6 @@
+---
+title: "Table Wizard"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/text-store.md

@@ -0,0 +1,6 @@
+---
+title: "Text Store"
+description: Text field that will not display its current value (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/text.md

@@ -0,0 +1,6 @@
+---
+title: "Text"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/textarea.md

@@ -0,0 +1,6 @@
+---
+title: "Textarea"
+description: Not yet documented
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/time-period.md

@@ -0,0 +1,6 @@
+---
+title: "Time Period"
+description: Text field with drop-down menu (not yet documented)
+---
+
+{{< widget-notice >}}

docs/dev/reference/widgets/trbl.md

@@ -0,0 +1,6 @@
+---
+title: "Margins"
+description: Four text fields with a small unit drop-down menu (not yet documented)
+---
+
+{{< widget-notice >}}

page/layouts/shortcodes/widget-notice.html

@@ -0,0 +1,3 @@
+<div class="notices info">
+  <p>This widget is not documented yet. Please consider contributing when you research a widget configuration to help others! Use the <a href="{{ ref . "/reference/widgets/checkbox" }}">Checkbox article</a> as a template.</p>
+</div>