Any option defined in the form view is copied into the new and edit
views. However, any option defined in the edit and new view overrides
the corresponding form option. In other words, always use the form
action to define the common configuration, and then use the new and edit
views to define just the specific options you want to override:

The merging of the form fields configuration is done recursively, so you can
change or add any option to any property. In addition, the following processing
takes place:

All the fields defined in the form view are copied in the same order into
the edit and new views.

Any field defined in the edit or new view which is not present in the
form view is added after the form fields.

The edit and new views can remove any field defined in the form view
just by prefixing the name of the removed field with a dash - (e.g. add
a property called -name to remove the name property defined in form)

This option refers both to the value of the <title> element and to the visible
title displayed at the top of the page. By default the title is just the name of
the entity. Define the title option to set a custom page title:

%entity_label%, resolves to the value defined in the label option of
the entity. If you haven't defined it, this value will be equal to the
entity name. In the example above, this value would be Customers.

%entity_name%, resolves to the entity name, which is the YAML key used
to configure the entity in the backend configuration file. In the example
above, this value would be Customer.

%entity_id%, it's only available for the edit view and it resolves to
the value of the primary key of the entity being edited. Even if the option
is called entity_id, it also works for primary keys with names different
from id.

Caution

In Symfony applications, YAML values enclosed with % and % have a
special meaning (they are considered container parameters). Escape these
values doubling the % characters:

If several entities use the same custom title, you can define the default title
for all entities in the global edit.title and new.title options (these
global titles are always overridden by the title defined by each entity):

Entities can define a global help message that is displayed below the title of
the page. This is useful to add instructions or warning messages for the end
users (e.g. "The upload process can take a lot of time (don't close the browser
window)").

The help message is defined with the help configuration option, which can be
added to the entity (all views display the same message) and to each of the
entity views:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# app/config/config.ymleasy_admin:entities:Customer:class:AppBundle\Entity\Customerhelp:'Globalmessagedisplayedinallviews'# ...form:help:'Theformviewoverridestheglobalhelpmessage'# ...edit:# 'help' is not defined, so the global help message is displayed# ...new:# use the null value to not display the inherited global help messagehelp:null# ...# ...

This option is also useful to reorder the form fields, because by default they
are displayed in the same order as defined in the related Doctrine entity.

Note

Fields that represent an association with another entity are displayed as
<select> lists. For that reason, you must define the __toString()
magic method in any entity which is used in a Doctrine relation. Otherwise
you'll see the following error message:
Catchable Fatal Error: Object of class XY could not be converted to string

The fields option can also include properties that are not defined in the
Doctrine entities. These properties are called "virtual properties" and the only
requirement is that they must define a setter method for them. For example, if
your entity contains a setName() method but not a name property, the
fields option can include the namevirtual property to set its value.

Note

The values or virtual properties are set using the PropertyAccess component
from Symfony, which requires to follow a strict syntax for setter names:
set + camelized version of the property name. Example: name ->
setName(); firstName -> setFirstName(); first_and_last_name ->
setFirstAndLastName().

When form fields are not configured explicitly, the backend renders them with
the most appropriate widget according to their data types. If you prefer to
control their appearance, start by using the extended field configuration:

Instead of using a string to define the property (e.g. 'email') you have to
define a hash with the name of the property ({ property: 'email' }) and the
options you want to define for it ({ ..., label: 'Contact' }).

If your entity contains lots of properties, consider using the alternative YAML
sequence syntax to improve the legibility of your backend configuration. The
following example is equivalent to the above example:

property (mandatory): the name of the property to bet set (in new view)
or modified (in edit view). This is the only mandatory option when using
the extended field configuration format.

label (optional): the content displayed in the <label> element of the
form field. The default label is the "humanized" version of the property name
(e.g. published is displayed as Published and dateOfBirth as
Date of birth).

help (optional): the help message displayed below the form field.

css_class (optional): the CSS class applied to the parent HTML element
that contains the entire form field. For example, when using the default
Bootstrap form theme, this value is applied to the <div> element which
wraps the label, the widget and the error messages of the field.

type (optional): the Symfony Form type used to render this field. You can
use the short type name (e.g. email) instead of its fully qualified class
name (e.g. Symfony\Component\Form\Extension\Core\Type\EmailType) even if
your application runs on Symfony 3 (the needed conversion is done internally
by the bundle).The allowed values are:

Unlike the list, search and show views, there are no configuration
options to define the date/time format for edit and new form fields. You
must use instead the options defined by Symfony's DateTimeType, DateType
and TimeType types.

For example, to display your dates as a single <input> text element, define
the widget form field option (commonly used together with format):

Similarly, there are no configuration options to define the formatting of the
numeric values for the edit and new views. You must use instead the
options defined by Symfony's NumberType, IntegerType, MoneyType and
PercentType types.

For example, to display a numeric property that stores prices, you can define
the currency option of the MoneyType form type:

When your application defines custom Doctrine DBAL types, you must also define
a custom form type for them before using them as form fields. Imagine that your
application defines a UTCDateTime type to convert the timezone of datetime
values to UTC before saving them in the database.

If you add that type in a property as follows, you'll get an error message
saying that the utcdatetime type couldn't be loaded:

It's similar to Symfony's Entity type, but the values are loaded on demand
via Ajax requests based on the user's input. This type is useful to improve the
backend performance when a field is related to an entity with lots of database
records:

When the user types in an autocomplete field, EasyAdmin performs a fuzzy search
on all the properties of the related entity. This is the same behavior applied
when using the backend search form.

The autocomplete action returns to the browser a JSON array of
{ id: '...', text: '...' } tuples. The id is used as the form field value
and the text is the value displayed to the user.

By default, the entity's primary key is used for the id property and the
(string) $entity conversion is used for the text property. Therefore,
you must define the __toString() method in all the entities used in
autocomplete form fields.

If the number of autocomplete suggestions is large, they are paginated to
display a maximum of 10 results. Define the show.max_results option to
change this value (globally or per entity):

Finally, add this custom theme to the list of themes used to render backend forms:

1
2
3
4
5
6
7
8
9

easy_admin:# ...design:form_theme:-'horizontal'# the following Twig template can be located anywhere in the application.# it can also be added to the twig.form_themes option to use it in the# entire application, not only the backend-'easy_admin/form.html.twig'

The default form layout is pretty basic: fields are displayed in the same order
they were defined and they span the full browser window width. However, forms
can also include special design elements (dividers, groups, sections) to create
more advanced layouts.

When using form groups, it's recommended to use the vertical form theme.
Otherwise, the field label will take up too much space.

Tip

Because of the way CSS works, when creating multi-column forms is common to
have ugly gaps between some rows and columns. EasyAdmin provides a .new-row
CSS class that forces the form group to be displayed in a new row:

1
2

# ...-{ type:'group', css_class:'new-row...'}

This solves most of the issues, but sometimes you might be forced to also
reorder the form group positions.

Tip

Form groups can define the collapsible option (false by default) to
show/hide their contents dynamically thanks to a toggle icon displayed at
their header. The expanded option (true by default) defines the
initial state of the contents:

1
2
3
4
5

# ...# allow to show/hide contents and show them by default-{ type:'group', collapsible:true}# allow to show/hide contents and hide them by default-{ type:'group', collapsible:true, expanded:false}

Caution

The collapsible option is deprecated since 1.x version and it will
be removed in EasyAdmin 2.0.

This element groups one or more fields and displays them in a separate tab. You
can combine it with the other elements (tabs can contain groups, but no the other
way around) to create clean interfaces when forms contains lots of fields.

EasyAdmin defines seven Twig templates to create its interface. These are the
four templates related to edit and new views:

layout, the common layout that decorates the rest of the main templates;

new, renders the page where new entities are created;

edit, renders the page where entity contents are edited;

form, renders the form included in the new and edit views.

Note

Unlike the properties displayed on the list, search and show
views, you can't easily override the template fragment used to render each
form field. Instead, use the form_theme option explained in the previous
sections to make EasyAdmin use your own Symfony Form theme when rendering
the backend forms.

Depending on your needs you can override these templates in different ways:

Override the templates via configuration, when you want to decide where
to store the custom templates;

Override the templates via convention, which is faster to set up because
you store the custom templates in a specific directory defined by EasyAdmin.

Before selecting a template to render some contents, EasyAdmin looks for these
configuration options and directory locations to check if your backend has
overridden it (the first template which exists is used):

The last one is the path of the built-in templates and they are always available.
The following sections explain the first four ways to customize the templates
used by the backend.

Tip

Regardless of how you override the default templates, it's convenient to
check first the variables provided by the backend to those templates. The
easiest way to do this is to include an empty {{ dump() }} call in your
templates.

Overriding the default EasyAdmin templates by convention is deprecated since
1.x version and it will be removed in EasyAdmin 2.0. Instead, use Symfony's
template overriding mechanism or override the templates by configuration as
explained the previous section.

If you don't mind the location of your custom templates, consider creating them
in the app/Resources/views/easy_admin/ directory. When the templates
option is not defined, EasyAdmin looks into this directory before falling back
to the default templates.

For example, to override the edit template just for the Customer entity,
you only need to create this template in this exact location (there is no need
to define the templates configuration option):