minor #5932 Rename Form Panels as Form Fieldsets (javiereguiluz)

This PR was squashed before being merged into the 4.x branch.

Discussion
----------

Rename Form Panels as Form Fieldsets

I know that renames are always annoying because you need to change things in your apps for something that doesn't provide anything valuable 🙏  But:

**(1)** If you don't change anything, everything should keep working the same. You won't see any change ... except some new messages in the list of deprecations shown by Symfony

**(2)** To fix those deprecations, you can use your IDE/editor to do this:

```diff
-::addPanel('...')
+::addFieldset('...')
```

**(3)** Only people doing very obscure/advanced things will need to do some more `panel` -> `fieldset` renames.

-----

Why do I propose this? Because fieldsets is a much more natural word for this feature and also, because it feels better with some upcoming changes in a nice feature that I will unveil in the future.

Commits
-------

fa98932 Rename Form Panels as Form Fieldsets

Author: javiereguiluz

UPGRADE.md

@@ -1,6 +1,25 @@
 Upgrade between EasyAdmin 4.x versions
 ======================================
 
+EasyAdmin 4.8.0
+---------------
+
+### Form Panels are now called Form Fieldsets
+
+You can still use `FormField::addPanel()` but it's deprecated and it will be
+removed in EasyAdmin 5.0.0. To fix the deprecation, "Find & Replace" in your IDE:
+
+    // Before
+    yield FormField::addPanel('...');
+
+    // After
+    yield FormField::addFieldset('...');
+
+If your application uses custom advanced features, you might need to change some
+other occurrences of "panel" such as CSS styles (`.form-panel` -> `.form-fieldset`)
+and form attributes in `CrudFormType` (`$formFieldOptions['ea_form_panel']` ->
+`$formFieldOptions['ea_form_fieldset'] = $currentFormFieldset`)
+
 EasyAdmin 4.6.0
 ---------------
 

assets/css/easyadmin-theme/forms.scss

@@ -344,108 +344,41 @@ label.form-check-label {
     margin-bottom: 15px;
 }
 
-// Form fieldsets (used for the "from groups" feature)
-fieldset {
-    background: var(--fieldset-bg);
-    border: var(--border-width) var(--border-style) var(--border-color);
-    border-radius: var(--border-radius);
-    margin: 10px 0;
-    padding: 10px 20px 15px;
-}
-
-fieldset > legend {
-    border: 0;
-    font-size: var(--font-size-sm);
-    font-weight: 500;
-    text-transform: uppercase;
-    margin: 0 0 5px -5px;
-    padding: 0 5px;
-    width: auto;
-}
-fieldset > legend .fa {
-    color: var(--text-muted);
-    font-size: var(--font-size-lg);
-    margin-right: 4px;
-}
-
-fieldset .form-section {
-    padding-left: 0;
-    padding-right: 0;
-}
-
-fieldset .form-group {
-    padding: 10px 0;
-}
-
-fieldset .form-group label,
-fieldset .form-group legend.col-form-label {
-    flex: 100% 0 0;
-    margin: 0 0 4px 0;
-    text-align: left;
-}
-
-fieldset .form-group .form-widget,
-fieldset .field-checkbox .form-widget {
-    flex: 0 0 100%;
-    padding-left: 0;
-    padding-right: 0;
-}
-
-fieldset .field-checkbox .form-widget,
-fieldset .form-group.field-collection-action {
-    margin-left: 0;
-}
-
-fieldset .form-group.field-collection-action {
-    padding-top: 0;
-}
-
-fieldset .field-collection-action .btn {
-    margin-left: 0;
-}
-
-fieldset .legend-help {
-    color: var(--text-muted);
-    font-size: var(--font-size-sm);
-    margin-bottom: 15px;
-    margin-top: -5px;
-}
-
 // Form sections
-.form-panel {
+.form-fieldset {
     padding: 0 0 20px;
 }
 
 .form-section-empty {
     padding: 25px 10px 25px;
 }
 
-.form-panel-header {
+.form-fieldset-header {
     align-items: flex-start;
-    box-shadow: 0 1px 0 var(--form-panel-header-border-color);
+    box-shadow: 0 1px 0 var(--form-fieldset-header-border-color);
     display: flex;
     flex-wrap: nowrap;
     padding: 15px 0 10px;
     position: relative;
 
-    .form-panel-collapse-marker {
-        color: var(--form-panel-collapse-marker-color);
+    .form-fieldset-collapse-marker {
+        color: var(--form-fieldset-collapse-marker-color);
         margin: 0 10px 0 2px;
         transform: rotate(90deg);
         transition: transform .2s ease-in-out;
     }
 
-    .form-panel-title {
+    .form-fieldset-title {
         flex: 1;
 
         a {
-            color: var(--form-panel-header-color);
+            color: var(--form-fieldset-header-color);
             font-size: 20px;
             font-weight: bold;
 
             &.not-collapsible { cursor: default; }
             &.collapsed {
-                .form-panel-collapse-marker {
+                .form-fieldset-collapse-marker {
                     transform: rotate(0deg);
                 }
             }
@@ -460,18 +393,18 @@ fieldset .legend-help {
             }
         }
 
-        .form-panel-icon {
-            color: var(--form-panel-icon-color);
+        .form-fieldset-icon {
+            color: var(--form-fieldset-icon-color);
             margin-right: 5px;
         }
 
-        .form-panel-help {
-            color: var(--form-panel-help-color);
+        .form-fieldset-help {
+            color: var(--form-fieldset-help-color);
         }
     }
 }
 
-.form-panel-body {
+.form-fieldset-body {
     padding-top: 5px;
 }
 

assets/css/easyadmin-theme/variables-theme.scss

@@ -179,11 +179,11 @@
     --form-help-error-color: var(--gray-800);
     --form-help-active-color: var(--gray-800);
     --form-tabs-border-color: var(--gray-200);
-    --form-panel-header-color: var(--gray-800);
-    --form-panel-help-color: var(--gray-600);
-    --form-panel-header-border-color: var(--gray-400);
-    --form-panel-icon-color: var(--gray-500);
-    --form-panel-collapse-marker-color: var(--gray-400);
+    --form-fieldset-header-color: var(--gray-800);
+    --form-fieldset-help-color: var(--gray-600);
+    --form-fieldset-header-border-color: var(--gray-400);
+    --form-fieldset-icon-color: var(--gray-500);
+    --form-fieldset-collapse-marker-color: var(--gray-400);
     --form-collection-item-collapse-marker-color: var(--gray-400);
     --badge-border: 0;
     --badge-boolean-false-bg: var(--gray-200);
@@ -496,11 +496,11 @@
     --form-help-error-color: var(--true-gray-200);
     --form-help-active-color: var(--true-gray-300);
     --form-tabs-border-color: var(--true-gray-200);
-    --form-panel-header-color: var(--true-gray-300);
-    --form-panel-help-color: var(--true-gray-500);
-    --form-panel-header-border-color: var(--true-gray-600);
-    --form-panel-icon-color: var(--true-gray-500);
-    --form-panel-collapse-marker-color: var(--true-gray-400);
+    --form-fieldset-header-color: var(--true-gray-300);
+    --form-fieldset-help-color: var(--true-gray-500);
+    --form-fieldset-header-border-color: var(--true-gray-600);
+    --form-fieldset-icon-color: var(--true-gray-500);
+    --form-fieldset-collapse-marker-color: var(--true-gray-400);
     --form-collection-item-collapse-marker-color: var(--true-gray-400);
     --badge-box-shadow: inset 0 0 0 1px rgba(245, 245, 245, 0.3);
     --badge-boolean-false-bg: rgba(245, 245, 245, 0.1);

doc/fields.rst

@@ -344,38 +344,43 @@ force the creation of a new line (the next field will forcibly render on a new r
         ];
     }
 
-Form Panels
-~~~~~~~~~~~
+Form Fieldsets
+~~~~~~~~~~~~~~
+
+.. versionadded:: 4.8.0
+
+    Form fieldsets were introduced in EasyAdmin 4.8.0. In previous versions,
+    this feature was called "Form Panels".
 
 In pages where you display lots of fields, you can divide them in groups using
-the "panels" created with the special ``FormField`` object::
+the fieldsets created with the special ``FormField`` object::
 
     use EasyCorp\Bundle\EasyAdminBundle\Field\FormField;
 
     public function configureFields(string $pageName): iterable
     {
         return [
-            // panels usually display only a title
-            FormField::addPanel('User Details'),
+            // fielfsets usually display only a title
+            FormField::addFieldset('User Details'),
             TextField::new('firstName'),
             TextField::new('lastName'),
 
-            // panels without titles only display a separation between fields
-            FormField::addPanel(),
+            // fieldsets without titles only display a separation between fields
+            FormField::addFieldset(),
             DateTimeField::new('createdAt')->onlyOnDetail(),
 
-            // panels can also define their icon, CSS class and help message
-            FormField::addPanel('Contact information')
+            // fieldsets can also define their icon, CSS class and help message
+            FormField::addFieldset('Contact information')
                 ->setIcon('phone')->addCssClass('optional')
                 ->setHelp('Phone number is preferred'),
             TextField::new('phone'),
             TextField::new('email')->hideOnIndex(),
 
-            // panels can be collapsible too (useful if your forms are long)
-            // this makes the panel collapsible but renders it expanded by default
-            FormField::addPanel('Contact information')->collapsible(),
-            // this makes the panel collapsible and renders it collapsed by default
-            FormField::addPanel('Contact information')->renderCollapsed(),
+            // fieldsets can be collapsible too (useful if your forms are long)
+            // this makes the fieldset collapsible but renders it expanded by default
+            FormField::addFieldset('Contact information')->collapsible(),
+            // this makes the fieldset collapsible and renders it collapsed by default
+            FormField::addFieldset('Contact information')->renderCollapsed(),
         ];
     }
 
@@ -395,8 +400,8 @@ the "tabs" created with the special ``FormField`` object::
             // Add a tab
             FormField::addTab('First Tab'),
 
-            // You can use a Form Panel inside a Form Tab
-            FormField::addPanel('User Details'),
+            // You can use a form fieldset inside a Form Tab
+            FormField::addFieldset('User Details'),
 
             // Your fields
             TextField::new('firstName'),

src/Dto/FieldDto.php

@@ -4,7 +4,8 @@
 
 use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
 use EasyCorp\Bundle\EasyAdminBundle\Config\KeyValueStore;
-use function Symfony\Component\String\u;
+use EasyCorp\Bundle\EasyAdminBundle\Form\Type\EaFormFieldsetType;
+use EasyCorp\Bundle\EasyAdminBundle\Form\Type\EasyAdminTabType;
 use Symfony\Component\Uid\Ulid;
 use Symfony\Contracts\Translation\TranslatableInterface;
 
@@ -80,7 +81,17 @@ public function setUniqueId(string $uniqueId): void
 
     public function isFormDecorationField(): bool
     {
-        return u($this->getCssClass())->containsAny(['field-form_panel', 'field-form_tab']);
+        return $this->isFormTab() || $this->isFormFieldset();
+    }
+
+    public function isFormFieldset(): bool
+    {
+        return EaFormFieldsetType::class === $this->formType;
+    }
+
+    public function isFormTab(): bool
+    {
+        return EasyAdminTabType::class === $this->formType;
     }
 
     public function getFieldFqcn(): ?string

src/Factory/FieldFactory.php

@@ -20,6 +20,7 @@
 use EasyCorp\Bundle\EasyAdminBundle\Field\TextareaField;
 use EasyCorp\Bundle\EasyAdminBundle\Field\TextField;
 use EasyCorp\Bundle\EasyAdminBundle\Field\TimeField;
+use EasyCorp\Bundle\EasyAdminBundle\Form\Type\EaFormFieldsetType;
 use EasyCorp\Bundle\EasyAdminBundle\Form\Type\EaFormRowType;
 use EasyCorp\Bundle\EasyAdminBundle\Form\Type\EasyAdminTabType;
 use EasyCorp\Bundle\EasyAdminBundle\Provider\AdminContextProvider;
@@ -135,16 +136,7 @@ private function preProcessFields(FieldCollection $fields, EntityDto $entityDto)
             return;
         }
 
-        // this is needed to handle this edge-case: the list of fields include one or more form panels,
-        // but the first fields of the list don't belong to any panel. We must create an automatic empty
-        // form panel for those "orphaned fields" so they are displayed as expected
-        $firstFieldIsAFormPanel = $fields->first()->isFormDecorationField();
-        foreach ($fields as $fieldDto) {
-            if (!$firstFieldIsAFormPanel && $fieldDto->isFormDecorationField()) {
-                $fields->prepend(FormField::addPanel()->getAsDto());
-                break;
-            }
-        }
+        $this->fixOrphanFieldsetFields($fields);
 
         foreach ($fields as $fieldDto) {
             if (Field::class !== $fieldDto->getFieldFqcn()) {
@@ -269,4 +261,26 @@ private function checkOrphanTabFields(FieldCollection $fields, AdminContext $con
 
         throw new \RuntimeException(sprintf('The "%s" page of "%s" uses tabs to display its fields, but the following fields don\'t belong to any tab: %s. Use "FormField::addTab(\'...\')" to add a tab before those fields.', $context->getCrud()->getCurrentPage(), $context->getCrud()->getControllerFqcn(), implode(', ', $orphanFieldNames)));
     }
+
+    /*
+     * This is needed to handle this edge-case: the list of fields include one or more form fieldsets,
+     * but the first fields of the list don't belong to any fieldset. We must create an automatic empty
+     * form fieldset for those "orphaned fields" so they are displayed as expected.
+     */
+    private function fixOrphanFieldsetFields(FieldCollection $fields): void
+    {
+        $formUsesFieldsets = false;
+        /** @var FieldDto $fieldDto */
+        foreach ($fields as $fieldDto) {
+            if (EaFormFieldsetType::class === $fieldDto->getFormType()) {
+                $formUsesFieldsets = true;
+                break;
+            }
+        }
+
+        $firstFieldIsAFieldsetOrTab = $fields->first()?->isFormDecorationField();
+        if ($formUsesFieldsets && !$firstFieldIsAFieldsetOrTab) {
+            $fields->prepend(FormField::addFieldset()->getAsDto());
+        }
+    }
 }

src/Field/Configurator/CommonPostConfigurator.php

@@ -7,7 +7,6 @@
 use EasyCorp\Bundle\EasyAdminBundle\Contracts\Field\FieldConfiguratorInterface;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\FieldDto;
-use EasyCorp\Bundle\EasyAdminBundle\Field\BooleanField;
 use EasyCorp\Bundle\EasyAdminBundle\Provider\AdminContextProvider;
 use function Symfony\Component\String\u;
 use Twig\Markup;