OC Release - v3.7

3.x/element/define-options.md

@@ -109,6 +109,27 @@ Property | Description
 **image** | specifies an image URL for this option (dropdown)
 **children** | specifies child options as another array for a nested structure (checkbox list)
 
+Use the `children` property if the option definition supports nesting. Generally, this will display a structure for checkbox lists and implement an option group for dropdowns.
+
+```php
+public function getDetailedFieldOptions()
+{
+    return [
+        1 => [
+            'label' => 'Option 1',
+            'comment' => 'This is option one',
+            'children' => [
+                2 => [
+                    'label' => 'Option 2',
+                    'comment' => 'This is option two',
+                ],
+                // ...
+            ]
+        ],
+    ];
+}
+```
+
 #### See Also
 
 ::: also

3.x/element/form/field-dropdown.md

@@ -29,6 +29,7 @@ Property | Description
 **optionsPreset** | take options from a [preset list of defined options](../define-options.md).
 **emptyOption** | text to display when allowing an empty option.
 **showSearch** | allow the user to search options. Default: `true`.
+**attributes** | an associative array of attributes and values to apply to the select field, useful for specifying custom Select2 configuration (see below).
 
 Generally `options` are defined with key-value pair, where the value and label are independently specified.
 
@@ -178,3 +179,56 @@ public static function staticMethodOptions($model, $formField)
     return ['published' => 'Published', ...];
 }
 ```
+
+To use option groups (`optgroup`) you can specify child items using a [detailed option definition](../define-options.md). In the example below, the label for the option group is taken from the value so it doesn't need to be repeated. The `children` property contains the options for that group and only one level of options are supported.
+
+```php
+public function getDetailedFieldOptions()
+{
+    return [
+        'Option Group' => [
+            'children' => [
+                1 => [
+                    'label' => 'Option 1',
+                    'comment' => 'This is option one',
+                ],
+                2 => [
+                    'label' => 'Option 2',
+                    'comment' => 'This is option two',
+                ],
+                // ...
+            ]
+        ],
+    ];
+}
+```
+
+## Custom Select2 Configuration
+
+The dropdown field uses the [Select2 control](https://select2.org/) to render the field. In some cases you may wish to specify custom configuration for this field. This is possible using the `attributes` property along with the [data attribute configuration](https://select2.org/configuration/data-attributes) supplied by Select2.
+
+For example, you may fine tune the auto completion behavior of the dropdown.
+
+```yaml
+attributes:
+    data-handler: onGetClientOptions
+    data-minimum-input-length: 3
+    data-process-Results: true
+    data-ajax--delay: 300
+```
+
+When used with a [Tag List field](./widget-taglist.md) the following will keep the dropdown open after an item has been selected.
+
+```yaml
+categories:
+    type: taglist
+    attributes:
+        data-close-on-select: false
+```
+
+#### See Also
+
+::: also
+* [Tag List Form Field](./widget-taglist.md)
+* [Select2 Control](https://select2.org/)
+:::

3.x/markup/filter/resize.md

@@ -50,6 +50,27 @@ You may modify the extension with the `extension` option. This process will atte
 }) }}" />
 ```
 
+## Custom Folder Names
+
+When using custom filenames, the filename will still contain a trailing hash to ensure uniqueness within the resizer resource directory. In most cases this is enough to satisfy basic SEO requirements. For example, the file will appear in the system like so.
+
+- `.../800_600_0_0_auto/my-seo-friendly-name_001a14981ffe90700046616c5f415467.png`
+
+A `group` can be specified as a folder name, this will place the image in a dedicated resource group.
+
+```twig
+<img src="{{ 'banner.jpg'|resize(800, 600, {
+    filename: 'my-seo-friendly-name',
+    group: '2024-banners'
+}) }}" />
+```
+
+For example, the above will place the file in the following directory:
+
+- `.../800_600_0_0_auto/2024-banners/my-seo-friendly-name.png`
+
+However, keep in mind, this approach can be prone to naming collisions. If a different file is resized using the same name and resize options, it will output the original file since there is no unique hash added to the path.
+
 ## Available Sources
 
 You may reference images from multiple sources, including the following paths: