DOC Document new ChildFieldManager interface

Author: GuySartorelli

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

@@ -0,0 +1,77 @@
+---
+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::validate()`](api:SilverStripe\Forms\Form::validate()), [`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\Forms\ChildFieldManager;
+use SilverStripe\Forms\FormField;
+use SilverStripe\Forms\TextField;
+
+class MyChildFieldManager extends FormField implements ChildFieldManager
+{
+    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 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

@@ -135,6 +135,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.