DEV Community

Javier Eguiluz
Javier Eguiluz

Posted on

New in EasyAdmin 5.5: Form Field Addons

#easyadmin #symfony

EasyAdmin 5.5 is out with form field addons, sortable nested association fields, and tabs that stay selected when you move from the detail page to the edit page.

Form Field Addons

Many form inputs only make sense with some context attached to them: the https:// prefix of a URL, the unit of a weight, the currency of a price, a search icon. Until now, adding those hints in EasyAdmin meant fiddling with custom form themes or help messages. In EasyAdmin 5.5, every field gains two new methods: prepend() and append():

use EasyCorp\Bundle\EasyAdminBundle\Field\IntegerField;
use EasyCorp\Bundle\EasyAdminBundle\Field\TextField;
use function Symfony\Component\Translation\t;

// a control field with no addons
yield TextField::new('street');

// addon defined as a simple text string
yield TextField::new('website')->prepend('https://');

// addon defined as a text string with HTML contents (rendered raw)
yield TextField::new('email')->append('<b>@example.com</b>');

// addon defined as a Translatable object
yield IntegerField::new('priority')->prepend(t('Priority Addon Lorem Ipsum'));

// addon defined as an icon only
yield TextField::new('phone')->append(icon: 'fa fa-magnifying-glass');

// addon combining an icon and a text content
yield TextField::new('city')->prepend('Search', icon: 'fa fa-magnifying-glass');

// field using both prepend and append at the same time
yield TextField::new('url')->prepend('https://')->append('.com');

// the currency symbol renders as an addon too: "Fee" and "$" become
// sibling addons before the input, with the symbol next to the input
yield MoneyField::new('priceInCents')->setCurrency('USD')->prepend('Fee');

// the percent symbol renders as an append addon
yield PercentField::new('score');
Enter fullscreen mode Exit fullscreen mode

And this is how the previous example looks now:

Form field addons in EasyAdmin 5.5

Fields that already displayed similar hints now integrate with this feature: the currency symbol of MoneyField and the % symbol of PercentField render as addons too. If you add your own addon to those fields, both are displayed as siblings, with the symbol staying next to the input:

use EasyCorp\Bundle\EasyAdminBundle\Field\MoneyField;

// "Fee" and "$" render as two sibling addons before the input
yield MoneyField::new('priceInCents')->setCurrency('USD')->prepend('Fee');
Enter fullscreen mode Exit fullscreen mode

The design of the addons is based on modern design systems like shadcn and GitHub Primer instead of the default Bootstrap input groups, so they blend nicely with the rest of the EasyAdmin interface (and with the theming API introduced in 5.4).

Note: Addons are only displayed on form pages (new and edit) and only for fields whose form control is a single-line input. Fields like TextareaField or ArrayField silently ignore them.

Sort by Nested Association Fields

AssociationField has supported nested property paths for a while: AssociationField::new('customer.country') displays the country of the related customer and even auto-links it to the country's CRUD controller. But sorting by those fields didn't work. BEFORE, the field wasn't sortable in the listing, and trying to sort by default threw an exception:

public function configureCrud(Crud $crud): Crud
{
    // this threw an exception before EasyAdmin 5.5
    return $crud->setDefaultSort(['customer.country' => 'ASC']);
}
Enter fullscreen mode Exit fullscreen mode

AFTER, in EasyAdmin 5.5, nested association fields are sortable by default, mirroring the behavior of single-level association fields:

use EasyCorp\Bundle\EasyAdminBundle\Field\AssociationField;

// sortable by default; results are ordered by the id of the related country
yield AssociationField::new('customer.country');

// use setSortProperty() to order by any property of the related entity
yield AssociationField::new('customer.country')->setSortProperty('name');
Enter fullscreen mode Exit fullscreen mode

The setDefaultSort() example shown above now works as expected too.

Note: A nested association field is sortable when every segment of the path is a to-one association. Paths ending in a to-many association are not sortable, just like single-level to-many association fields.

The Selected Tab Follows You from Detail to Edit

Here's a small UX improvement that you'll notice immediately if your entities use tabs. When browsing an entity's detail page, chances are that when you click "Edit" you want to change something in the tab you're currently looking at. Yet, the edit page always opened on the first tab.

In EasyAdmin 5.5, the detail page also stores the selected tab in the URL hash (e.g. #tab-contact-information). This brings several improvements at once, with zero configuration on your side:

  • The selected tab is kept when going from the detail page to the edit page of the same entity (and vice versa);
  • Reloading the page keeps the same tab selected, and you can bookmark or share a link to a specific tab;
  • The browser back/forward buttons navigate through the tabs you selected.

This only applies to the tabs generated by EasyAdmin, so if you added your own Bootstrap tabs on custom backend pages, they are not affected.

Summary

EasyAdmin 5.5 makes your forms clearer with prepend/append addons, your listings more capable with sorting by nested association fields, and your editing workflow smoother with tab persistence between detail and edit pages. There's nothing to migrate and no code to update: upgrade and start using the new features where they help.

✨ If you enjoyed this feature and want to see more like it, consider sponsoring the EasyAdmin project 🙌💡

Top comments (0)