FormElements: Let the form modify default decorators and add custom decorators

FormElements:
- Add property `$elementDecoratorLoaderPaths` to add custom decorators
- Add methods `addElementDecoratorLoaderPaths()` and `modifyDefaultDecorators()`

- Introduce interface `DefaultFormElementDecoration`

These methods can be overridden by the form to add decorator loaders and modify the default decotators.

Author: sukhwinder33445

src/Contract/DefaultFormElementDecoration.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace ipl\Html\Contract;
+
+interface DefaultFormElementDecoration
+{
+    /**
+     * Get the default element decorators
+     *
+     * @return ?array
+     */
+    public function getDefaultElementDecorators(): ?array;
+
+    /**
+     * Set the default element decorators
+     *
+     * Call this method before creating any element OR override the {@see self::$defaultElementDecorators} property,
+     * to ensure that the default decorators are applied
+     *
+     * @param ?array $defaultElementDecorators
+     *
+     * @return $this
+     */
+    public function setDefaultElementDecorators(?array $defaultElementDecorators): self;
+}

src/Form.php

@@ -2,14 +2,15 @@
 
 namespace ipl\Html;
 
+use ipl\Html\Contract\DefaultFormElementDecoration;
 use ipl\Html\Contract\FormElement;
 use ipl\Html\Contract\FormSubmitElement;
 use ipl\Html\FormElement\FormElements;
 use ipl\Stdlib\Messages;
 use Psr\Http\Message\ServerRequestInterface;
 use Throwable;
 
-class Form extends BaseHtmlElement
+class Form extends BaseHtmlElement implements DefaultFormElementDecoration
 {
     use FormElements {
         FormElements::remove as private removeElement;
@@ -46,6 +47,18 @@ class Form extends BaseHtmlElement
 
     protected $tag = 'form';
 
+    public function __construct()
+    {
+        if ($this->getDefaultElementDecorators() === null && ! $this->hasDefaultElementDecorator()) {
+            $this->setDefaultElementDecorators([
+                'Fieldset',
+                'Label',
+                'Description',
+                'HtmlTag' => ['tag' => 'div'],
+            ]);
+        }
+    }
+
     /**
      * Get whether the given value is empty
      *

src/FormElement/FieldsetElement.php

@@ -4,14 +4,15 @@
 
 use InvalidArgumentException;
 use ipl\Html\Common\MultipleAttribute;
+use ipl\Html\Contract\DefaultFormElementDecoration;
 use ipl\Html\Contract\FormElement;
 use ipl\Html\Contract\FormElementDecorator;
 use ipl\Html\Contract\Wrappable;
 use LogicException;
 
 use function ipl\Stdlib\get_php_type;
 
-class FieldsetElement extends BaseFormElement
+class FieldsetElement extends BaseFormElement implements DefaultFormElementDecoration
 {
     use FormElements {
         FormElements::getValue as private getElementValue;

src/FormElement/FormElements.php

@@ -3,6 +3,7 @@
 namespace ipl\Html\FormElement;
 
 use InvalidArgumentException;
+use ipl\Html\Contract\DefaultFormElementDecoration;
 use ipl\Html\Contract\FormElement;
 use ipl\Html\Contract\FormElementDecorator;
 use ipl\Html\Contract\ValueCandidates;
@@ -29,12 +30,53 @@ trait FormElements
     /** @var bool Whether the default element loader has been registered */
     protected $defaultElementLoaderRegistered = false;
 
+    /**
+     * Custom Element decorator loader paths
+     *
+     * @var array<int, array<string|int, string> Override this property to add custom decorator loader paths
+     *
+     * Each entry must be an array, where the key is the decorator name postfix (if any) and the value is the path
+     */
+    protected array $elementDecoratorLoaderPaths = [];
+
+    /**
+     * Default element decorators
+     *
+     * Override this property to change the default decorators of the elements.
+     * The default decorators will be applied to all elements that do not have their own decorators.
+     *
+     * The order of the decorators is important, as it determines the rendering order.
+     *
+     * @var ?array<string|int, string|array<string, string>>
+     */
+    protected ?array $defaultElementDecorators = [];
+
     /** @var FormElement[] */
     private $elements = [];
 
     /** @var array<string, array<int, mixed>> */
     private $populatedValues = [];
 
+    public function getDefaultElementDecorators(): ?array
+    {
+        if (empty($this->defaultElementDecorators)) {
+            return null;
+        }
+
+        return $this->defaultElementDecorators;
+    }
+
+    public function setDefaultElementDecorators(?array $defaultElementDecorators): self
+    {
+        if (empty($defaultElementDecorators)) {
+            $defaultElementDecorators = null;
+        }
+
+        $this->defaultElementDecorators = $defaultElementDecorators;
+
+        return $this;
+    }
+
     /**
      * Get all elements
      *
@@ -130,6 +172,23 @@ public function addElement($typeOrElement, $name = null, $options = null)
         return $this;
     }
 
+    /**
+     * Add custom element decorator loader paths for the elements
+     *
+     * Call this method before creating any element OR override the {@see self::$elementDecoratorLoaderPaths} property,
+     * to ensure that your custom decorator loader paths are applied
+     *
+     * @param array $loaderPaths
+     *
+     * @return $this
+     */
+    public function addElementDecoratorLoaderPaths(array $loaderPaths): self
+    {
+        $this->elementDecoratorLoaderPaths = $loaderPaths;
+
+        return $this;
+    }
+
     /**
      * Create an element
      *
@@ -157,6 +216,33 @@ public function createElement($type, $name, $options = null)
         /** @var FormElement $element */
         $element = new $class($name);
 
+        $customDecoratorPaths = $this->elementDecoratorLoaderPaths;
+        if (! empty($customDecoratorPaths)) {
+            if ($element instanceof DefaultFormElementDecoration) {
+                $element->addElementDecoratorLoaderPaths($customDecoratorPaths);
+            }
+
+            $chain = $element->getDecorators();
+            foreach ($customDecoratorPaths as $paths) {
+                foreach ($paths as $postfix => $path) {
+                    if (is_int($postfix)) {
+                        $postfix = '';
+                    }
+
+                    $chain->addDecoratorLoader($path, $postfix);
+                }
+            }
+        }
+
+        $defaultDecorators = $this->getDefaultElementDecorators();
+        if ($defaultDecorators !== null && ! $this->hasDefaultElementDecorator()) {
+            if ($element instanceof DefaultFormElementDecoration) {
+                $element->setDefaultElementDecorators($defaultDecorators);
+            }
+
+            $element->setDecorators($defaultDecorators);
+        }
+
         if ($options !== null) {
             $element->addAttributes($options);
         }
@@ -454,6 +540,11 @@ protected function ensureDefaultElementLoaderRegistered()
      */
     protected function decorate(FormElement $element)
     {
+        if ($element->hasDecorators()) {
+            // new decorator implementation in use
+            return $this;
+        }
+
         if ($this->hasDefaultElementDecorator()) {
             $decorator = $this->getDefaultElementDecorator();