DOC Document new ChildFieldManager interface

Author: GuySartorelli

en/02_Developer_Guides/03_Forms/Field_types/05_ChildFieldManager.md

@@ -0,0 +1,88 @@
+---
+title: ChildFieldManager
+summary: Strict management of child fields for advanced use cases
+---
+
+# `ChildFieldManager`
+
+In most cases, child form fields can be grouped with a [`CompositeField`](api:SilverStripe\Forms\CompositeField) or one of its subclasses - but sometimes you need more control.
+
+For example, you may have a use case where specific form fields *must* be present in the child field list. In that case you won't want methods like [`FieldList::removeByName()`](api:SilverStripe\Forms\FieldList::removeByName()) or [`FieldList::replaceField()`](api:SilverStripe\Forms\FieldList::replaceField()) to know about your child fields, but you'll still want to expose them for things like [`Form::loadDataFrom()`](api:SilverStripe\Forms\Form::loadDataFrom()), [`Form::saveInto()`](api:SilverStripe\Forms\Form::saveInto()), and allow them to manage their own AJAX requests.
+
+To achieve this, your custom [`FormField`](api:SilverStripe\Forms\FormField) can implement the [`ChildFieldManager`](api:SilverStripe\Forms\ChildFieldManager) interface. The methods declared in this interface allow the form to access your fields for critical functionality, but doesn't let anyone remove or replace fields in your managed child field list.
+
+In order to get managed fields from a `FieldList`, call [`FieldList::getAllDataFields()`](api:SilverStripe\Forms\FieldList::getAllDataFields()). This differs from [`FieldList::dataFields()`](api:SilverStripe\Forms\FieldList::dataFields()) in two ways:
+
+1. It gets all data fields *including* those managed by a `ChildFieldManager`, which `dataFields()` excludes
+1. It only caches the same fields that `dataFields()` caches - i.e. fields returned from a `ChildFieldManager` are not cached when calling `getAllDataFields()`.
+
+A very simple implementation of this interface would look like this:
+
+> [!WARNING]
+> The below example shows a minimal PHP implementation but not the template.
+> The assumption is if you're implementing this interface, you already have an advanced use case and know what you need to do in your template to get your use case broadly working.
+
+```php
+namespace App\Form;
+
+use SilverStripe\Core\Validation\FieldValidation\CompositeFieldValidator;
+use SilverStripe\Forms\ChildFieldManager;
+use SilverStripe\Forms\FormField;
+use SilverStripe\Forms\TextField;
+
+class MyChildFieldManager extends FormField implements ChildFieldManager
+{
+    private static array $field_validators = [
+        CompositeFieldValidator::class,
+    ];
+
+    private array $children = [];
+
+    public function __construct()
+    {
+        $this->children = [
+            'FieldOne' => TextField::create('FieldOne'),
+            'FieldTwo' => TextField::create('FieldTwo'),
+        ];
+        parent::__construct('MyManagedField');
+    }
+
+    public function isManagedField(string $fieldName): bool
+    {
+        return array_key_exists($fieldName, $this->children);
+    }
+
+    public function getManagedFieldByName(string $fieldName): ?FormField
+    {
+        return $this->children[$fieldName] ?? null;
+    }
+
+    public function getManagedFields(): iterable
+    {
+        return $this->children;
+    }
+
+    public function getValueForValidation(): mixed
+    {
+        // Ensure child fields get validated by the CompositeFieldValidator
+        return $this->children;
+    }
+
+    public function getSchemaDataDefaults(): array
+    {
+        $defaults = parent::getSchemaDataDefaults();
+        // Include child schema data for react forms
+        $children = $this->getChildren();
+        foreach ($children as $child) {
+            $childSchema[] = $child->getSchemaData();
+        }
+        $defaults['children'] = $childSchema;
+        return $defaults;
+    }
+}
+```
+
+You can then implement whatever logic you want and rely on those specific fields being there no matter what anyone else is doing with your form.
+
+> [!TIP]
+> It's usually a good idea to ensure that if [`FormField::setForm()`](api:SilverStripe\Forms\FormField::setForm()), [`FormField::performReadonlyTransformation()`](api:SilverStripe\Forms\FormField::performReadonlyTransformation()), [`FormField::performDisabledTransformation()`](api:SilverStripe\Forms\FormField::performDisabledTransformation()), [`FormField::setReadonly()`](api:SilverStripe\Forms\FormField::setReadonly()), or [`FormField::setDisabled()`](api:SilverStripe\Forms\FormField::setDisabled()) is called on your parent form, the appropriate methods are called on your child fields a well.

en/08_Changelogs/6.2.0.md

@@ -105,11 +105,14 @@ Note that some third-party modules may not yet support PHP 8.5, so PHP deprecati
 
 ### Move elemental blocks
 
-In the [dnadesign/silverstripe-elemental](/optional_features/elemental/) module, functionality has been added to move elemental blocks from one parent to another, including from one elemental area to another on the same parent record.
+The [dnadesign/silverstripe-elemental](/optional_features/elemental/) module now includes functionality that allows elemental blocks to be moved from one parent record to another. This includes moving blocks between different elemental areas on the same parent record.
 
 ![move block button](./_images/move-block-button.png)
 
-The move form provides a lot of flexibility for various configurations, and fields will be hidden if there's only one option to select from. For example, if there's only one elemental area relation on your selected parent record, no dropdown to select an elemental area will be displayed - but if there's multiple, a dropdown will be there for you.
+The move form has been designed for flexibility and will automatically hide fields if there's only one option available. For example:
+
+- If your selected parent record has only one elemental area relation, the dropdown for selecting an elemental area won't be displayed.
+- If there are multiple elemental area relations, the dropdown will be available.
 
 ![move block form modal](./_images/move-block-modal.png)
 
@@ -142,6 +145,7 @@ You can filter by the name and description of the campaign, its status, and the
 
 ### Other new features and enhancements {#other-new}
 
+- A new [`ChildFieldManager`](api:SilverStripe\Forms\ChildFieldManager) interface has been added to allow a parent form field to strictly control its children, but still allow setting/getting values for those fields let them handle AJAX requests. See [`ChildFieldManager` docs](/developer_guides/forms/field_types/childfieldmanager/) for more details.
 - The `help` plugin is now added by default to all [`TinyMCEConfig`](api:SilverStripe\TinyMCE\TinyMCEConfig) instances. If you were adding it manually, you can remove that custom code. If for some reason you don't want that plugin in one of your configs, you can use [`TinyMCEConfig::disablePlugins()`](api:SilverStripe\TinyMCE\TinyMCEConfig::disablePlugins()) to remove it - but be aware that it is extremely useful for screen reader users to keep this plugin installed.
 - [`HTML::createTag()`](api:SilverStripe\View\HTML::createTag()) now supports value-less boolean attributes. For example if you pass `HTML::create('input', ['readonly' => true])`, the result will be `<input readonly>`. Previously it would output as `<input readonly="1">`.
 - The built-in session handlers [`FileSessionHandler`](api:SilverStripe\Control\SessionHandler\FileSessionHandler), [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler), and [`DatabaseSessionHandler`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler) all now validate the session ID `PHPSESSID` to ensure it matches a valid format, otherwise a `RuntimeException` will be thrown.