Add connectedTo for inline repeater and documentation about connectedTo

docs/content/1_docs/4_form-fields/15_conditional-fields.md

@@ -4,6 +4,38 @@ You can conditionally display fields based on the values of other fields in your
 display a video embed text field only if the type of article, a radio field, is "video" you'd do something like the
 following:
 
+
+:::tabs=currenttab.FormBuilder&items.FormBuilder|FormView:::
+:::tab=name.FormBuilder:::
+
+```php
+$form->add(\A17\Twill\Services\Forms\Fields\Radios::make()
+  ->name('type')
+  ->label('Article type')
+  ->inline()
+  ->default('long_form')
+  ->options([
+    [
+      'value' => 'long_form',
+      'label' => 'Long form article'
+    ],
+    [
+      'value' => 'video',
+      'label' => 'Video article'
+    ]
+  ])
+);
+
+$form->add(\A17\Twill\Services\Forms\Fields\Input::make()
+  ->name('video_embed')
+  ->label('Video embed')
+  ->connectedTo('type', 'video')
+);
+```
+
+:::#tab:::
+:::tab=name.FormView:::
+
 ```blade
 <x-twill::radios
     name="type"
@@ -34,8 +66,30 @@ following:
 </x-twill::formConnectedFields>
 ```
 
+:::#tab:::
+:::#tabs:::
+
 Here's an example based on a checkbox field where the value is either true or false:
 
+
+:::tabs=currenttab.FormBuilder&items.FormBuilder|FormView:::
+:::tab=name.FormBuilder:::
+
+```php
+$form->add(\A17\Twill\Services\Forms\Fields\Checkbox::make()
+  ->name('vertical_article')
+  ->label('Vertical story')
+);
+
+$form->add(\A17\Twill\Services\Forms\Fields\Medias::make()
+  ->name('vertical_image')
+  ->label('Vertical Image')
+  ->connectedTo('vertical_article', true)
+);
+```
+
+:::#tab:::
+:::tab=name.FormView:::
 ```blade
 <x-twill::checkbox
     name="vertical_article"
@@ -54,8 +108,47 @@ Here's an example based on a checkbox field where the value is either true or fa
 </x-twill::formConnectedFields>
 ```
 
+:::#tab:::
+:::#tabs:::
+
 Here's an example based on a checkboxes field where the values are stored in a json field:
 
+:::tabs=currenttab.FormBuilder&items.FormBuilder|Directive:::
+:::tab=name.FormBuilder:::
+
+```php
+$form->add(\A17\Twill\Services\Forms\Fields\Checkboxes::make()
+  ->name('article_target')
+  ->label('Target')
+  ->min(1)->max(3)->inline()
+  ->options([
+    [
+      'value' => 'students',
+      'label' => 'Students'
+    ],
+    [
+      'value' => 'teachers',
+      'label' => 'Teachers'
+    ],
+    [
+      'value' => 'administration',
+      'label' => 'Administration'
+    ]
+  ])
+);
+
+$form->add(\A17\Twill\Services\Forms\Fields\Files::make()
+  ->name('attachment')
+  ->label('Attachment')
+  ->connectedTo('article_target', ['teachers', 'administration'], [
+    'keepAlive' => true,
+    'arrayContains' => true, // If you don't pass an array as fieldValues, set to false
+  ])
+);
+```
+
+:::#tab:::
+:::tab=name.Directive:::
 ```blade
 @formField('checkboxes', [
     'name' => 'article_target',
@@ -81,8 +174,9 @@ Here's an example based on a checkboxes field where the values are stored in a j
 
 @formConnectedFields([
     'fieldName' => 'article_target',
-    'fieldValues' => 'administration',
-    'arrayContains' => false,
+    'fieldValues' => ['administration', 'teachers'],
+    'arrayContains' => true, // If you don't pass an array as fieldValues, set to false
+    'keepAlive' => true,
     'renderForBlocks' => true/false # (depending on regular form vs block form)
 ])
     @formField('files', [
@@ -91,9 +185,42 @@ Here's an example based on a checkboxes field where the values are stored in a j
     ])
 @endformConnectedFields
 ```
+:::#tab:::
+:::#tabs:::
 
 Here's an example based on a browser field where the fields are displayed only when the browser field is not empty:
 
+:::tabs=currenttab.FormBuilder&items.FormBuilder|FormView:::
+:::tab=name.FormBuilder:::
+
+```php
+$form->add(\A17\Twill\Services\Forms\Fields\Browser::make()
+  ->name('related_publications')
+  ->label('Related publications')
+  ->max(4)
+  ->modules([Publications::class]))
+);
+
+$form->add(\A17\Twill\Services\Forms\Fields\Input::make()
+  ->name('related_publications_header')
+  ->label('Related publications header')
+  ->connectedTo('article_publications', true, [
+    'isBrowser' => true,
+    'keepAlive' => true,
+  ])
+);
+$form->add(\A17\Twill\Services\Forms\Fields\Input::make()
+  ->name('related_publications_copy')
+  ->label('Related publications copy')
+  ->connectedTo('article_publications', true, [
+    'isBrowser' => true,
+    'keepAlive' => true,
+  ])
+);
+```
+
+:::#tab:::
+:::tab=name.FormView:::
 ```blade
 <x-twill::browser
     module-name="publication"
@@ -117,14 +244,16 @@ Here's an example based on a browser field where the fields are displayed only w
     />
 </x-twill::formConnectedFields>
 ```
+:::#tab:::
+:::#tabs:::
 
-| Option            | Description                                                                                      | Type              | Default value |
-|:------------------|:-------------------------------------------------------------------------------------------------|:------------------|:--------------|
-| fieldName         | Name of the connected field                                                                      | string            |               |
-| fieldValues       | Value or values of the connected field that will reveal the fields in this component's slot      | string&vert;array |               |
-| isEqual           | Controls how `fieldValues` are evaluated against the connected field                             | boolean           | true          |
-| isBrowser         | Indicates that the connected field is a `browser` field                                          | boolean           | false         |
-| arrayContains     | Controls how `fieldValues` are evaluated when connected field is an array                        | boolean           | true          | 
-| matchEmptyBrowser | When set to true, the fields in this component's slot will be revealed when the browser is empty | boolean           | false         |
-| keepAlive         | When set to true, the state of the hidden fields is preserved                                    | boolean           | false         |
-| renderForBlocks   | When used inside a block, this needs to be set to true                                           | string            | false         |
+| Option            | Description                                                                                                   | Type              | Default value |
+|:------------------|:--------------------------------------------------------------------------------------------------------------|:------------------|:--------------|
+| fieldName         | Name of the connected field                                                                                   | string            |               |
+| fieldValues       | Value or values of the connected field that will reveal the fields in this component's slot                   | string&vert;array |               |
+| isEqual           | Controls how `fieldValues` are evaluated against the connected field                                          | boolean           | true          |
+| isBrowser         | Indicates that the connected field is a `browser` field                                                       | boolean           | false         |
+| arrayContains     | Controls how `fieldValues` are evaluated when connected field is an array                                     | boolean           | true          | 
+| matchEmptyBrowser | When set to true, the fields in this component's slot will be revealed when the browser is empty              | boolean           | false         |
+| keepAlive         | When set to true, the state of the hidden fields is preserved                                                 | boolean           | false         |
+| renderForBlocks   | When used inside a block, this needs to be set to true (this is automatically set when using the FormBuilder) | string            | false         |

src/Services/Forms/Fields/BaseFormField.php

@@ -23,7 +23,7 @@ protected function __construct(
         protected ?bool $required = false,
         protected ?bool $disabled = false,
         protected mixed $default = null,
-        protected mixed $connectedTo = null,
+        protected ?array $connectedTo = null,
         /**
          * A list of mandatory properties in order of their component
          * constructor.

src/Services/Forms/InlineRepeater.php

@@ -29,6 +29,7 @@
         private ?int $max = null,
         private ?string $titleField = null,
         private ?bool $hideTitlePrefix = false,
+        protected ?array $connectedTo = null,
     ) {
     }
 
@@ -202,6 +203,9 @@
         if ($this->max) {
             $repeater->max($this->max);
         }
+        if ($this->connectedTo) {
+            $repeater->connectedTo($this->connectedTo['fieldName'], $this->connectedTo['fieldValues'], $this->connectedTo);
+        }
 
         $repeater->renderForBlocks = $this->renderForBlocks ?? false;
         return $repeater->render();
@@ -218,4 +222,16 @@
             }
         }
     }
+
+
+    public function connectedTo(string $fieldName, mixed $fieldValues, array $options = []): static
+    {
+        $this->connectedTo = [
+            'fieldName' => $fieldName,
+            'fieldValues' => $fieldValues,
+            ...$options,
+        ];
+
+        return $this;
+    }
 }