diff --git a/docs/dev/reference/widgets/_index.md b/docs/dev/reference/widgets/_index.md new file mode 100644 index 000000000..a7144f86c --- /dev/null +++ b/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" %}} diff --git a/docs/dev/reference/widgets/checkbox-wizard.md b/docs/dev/reference/widgets/checkbox-wizard.md new file mode 100644 index 000000000..839403975 --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/checkbox.md b/docs/dev/reference/widgets/checkbox.md new file mode 100644 index 000000000..ef0a7d22d --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/dev/reference/widgets/chmod.md b/docs/dev/reference/widgets/chmod.md new file mode 100644 index 000000000..acf0330e8 --- /dev/null +++ b/docs/dev/reference/widgets/chmod.md @@ -0,0 +1,6 @@ +--- +title: "CHMOD" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/file-tree.md b/docs/dev/reference/widgets/file-tree.md new file mode 100644 index 000000000..22df33137 --- /dev/null +++ b/docs/dev/reference/widgets/file-tree.md @@ -0,0 +1,6 @@ +--- +title: "File tree" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/image-size.md b/docs/dev/reference/widgets/image-size.md new file mode 100644 index 000000000..3552d0110 --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/images/checkbox-grouped.png b/docs/dev/reference/widgets/images/checkbox-grouped.png new file mode 100644 index 000000000..28cded98b Binary files /dev/null and b/docs/dev/reference/widgets/images/checkbox-grouped.png differ diff --git a/docs/dev/reference/widgets/images/checkbox-multiple.png b/docs/dev/reference/widgets/images/checkbox-multiple.png new file mode 100644 index 000000000..fcba34b8a Binary files /dev/null and b/docs/dev/reference/widgets/images/checkbox-multiple.png differ diff --git a/docs/dev/reference/widgets/images/checkbox-wizard.png b/docs/dev/reference/widgets/images/checkbox-wizard.png new file mode 100644 index 000000000..1a0cf4e39 Binary files /dev/null and b/docs/dev/reference/widgets/images/checkbox-wizard.png differ diff --git a/docs/dev/reference/widgets/images/checkbox.png b/docs/dev/reference/widgets/images/checkbox.png new file mode 100644 index 000000000..168d4305d Binary files /dev/null and b/docs/dev/reference/widgets/images/checkbox.png differ diff --git a/docs/dev/reference/widgets/input-unit.md b/docs/dev/reference/widgets/input-unit.md new file mode 100644 index 000000000..dd96aac21 --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/key-value-wizard.md b/docs/dev/reference/widgets/key-value-wizard.md new file mode 100644 index 000000000..757f206e7 --- /dev/null +++ b/docs/dev/reference/widgets/key-value-wizard.md @@ -0,0 +1,6 @@ +--- +title: "Key-Value-Wizard" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/list-wizard.md b/docs/dev/reference/widgets/list-wizard.md new file mode 100644 index 000000000..3b33f7a06 --- /dev/null +++ b/docs/dev/reference/widgets/list-wizard.md @@ -0,0 +1,6 @@ +--- +title: "List Wizard" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/meta-wizard.md b/docs/dev/reference/widgets/meta-wizard.md new file mode 100644 index 000000000..ed312fee3 --- /dev/null +++ b/docs/dev/reference/widgets/meta-wizard.md @@ -0,0 +1,6 @@ +--- +title: "Meta Wizard" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/module-wizard.md b/docs/dev/reference/widgets/module-wizard.md new file mode 100644 index 000000000..ef02252ba --- /dev/null +++ b/docs/dev/reference/widgets/module-wizard.md @@ -0,0 +1,6 @@ +--- +title: "Module Wizard" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/option-wizard.md b/docs/dev/reference/widgets/option-wizard.md new file mode 100644 index 000000000..2f119991e --- /dev/null +++ b/docs/dev/reference/widgets/option-wizard.md @@ -0,0 +1,6 @@ +--- +title: "Option Wizard" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/page-tree.md b/docs/dev/reference/widgets/page-tree.md new file mode 100644 index 000000000..01e156d62 --- /dev/null +++ b/docs/dev/reference/widgets/page-tree.md @@ -0,0 +1,6 @@ +--- +title: "Page Tree" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/picker.md b/docs/dev/reference/widgets/picker.md new file mode 100644 index 000000000..c0b336925 --- /dev/null +++ b/docs/dev/reference/widgets/picker.md @@ -0,0 +1,6 @@ +--- +title: "Picker" +description: General purpose picker (not yet documented) +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/radio-table.md b/docs/dev/reference/widgets/radio-table.md new file mode 100644 index 000000000..1c530a77c --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/radio.md b/docs/dev/reference/widgets/radio.md new file mode 100644 index 000000000..344572331 --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/section-wizard.md b/docs/dev/reference/widgets/section-wizard.md new file mode 100644 index 000000000..3cc3c9858 --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/select.md b/docs/dev/reference/widgets/select.md new file mode 100644 index 000000000..371859863 --- /dev/null +++ b/docs/dev/reference/widgets/select.md @@ -0,0 +1,6 @@ +--- +title: "Select Menu" +description: Drop-down menu (not yet documented) +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/serp-preview.md b/docs/dev/reference/widgets/serp-preview.md new file mode 100644 index 000000000..538ede287 --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/table-wizard.md b/docs/dev/reference/widgets/table-wizard.md new file mode 100644 index 000000000..03463d820 --- /dev/null +++ b/docs/dev/reference/widgets/table-wizard.md @@ -0,0 +1,6 @@ +--- +title: "Table Wizard" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/text-store.md b/docs/dev/reference/widgets/text-store.md new file mode 100644 index 000000000..000b3473c --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/text.md b/docs/dev/reference/widgets/text.md new file mode 100644 index 000000000..8ca0cffa7 --- /dev/null +++ b/docs/dev/reference/widgets/text.md @@ -0,0 +1,6 @@ +--- +title: "Text" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/textarea.md b/docs/dev/reference/widgets/textarea.md new file mode 100644 index 000000000..e67807f7f --- /dev/null +++ b/docs/dev/reference/widgets/textarea.md @@ -0,0 +1,6 @@ +--- +title: "Textarea" +description: Not yet documented +--- + +{{< widget-notice >}} diff --git a/docs/dev/reference/widgets/time-period.md b/docs/dev/reference/widgets/time-period.md new file mode 100644 index 000000000..ce3be334a --- /dev/null +++ b/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 >}} diff --git a/docs/dev/reference/widgets/trbl.md b/docs/dev/reference/widgets/trbl.md new file mode 100644 index 000000000..2074b24f9 --- /dev/null +++ b/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 >}} diff --git a/page/layouts/shortcodes/widget-notice.html b/page/layouts/shortcodes/widget-notice.html new file mode 100644 index 000000000..c1d54c25b --- /dev/null +++ b/page/layouts/shortcodes/widget-notice.html @@ -0,0 +1,3 @@ +
+

This widget is not documented yet. Please consider contributing when you research a widget configuration to help others! Use the Checkbox article as a template.

+