Chapter 6. Edit and New Views Configuration
This chapter explains how to customize the read-and-write views: edit and
new. You’ll learn all their configuration options and how to override or
tweak their templates.
Edit, New and Form Views
The Edit View is displayed when modifying the contents of any existing entity. The New View is used when creating new items of the given entity. The design of both views is almost identical:
.. image:: ../images/easyadmin-edit-view.png :alt: Edit view interface
The Special form View
Most of the times you apply the same or very similar configuration to both the
`edit` and `new` views. Instead of duplicating the configuration, you can
use the special `form` view:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form: # <-- 'form' is applied to both 'new' and 'edit' views
fields:
- 'id'
- { property: 'email', type: 'email', label: 'Contact' }
# ...
# ...
```
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:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
title: 'Add customer'
form_options: { validation_groups: ['Default'] }
new:
form_options: { validation_groups: ['Default', 'Customer'] }
edit:
title: 'Edit customer'
# ...
```
The above configuration is equivalent to the following:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
new:
title: 'Add customer'
form_options: { validation_groups: ['Default', 'Customer'] }
edit:
title: 'Edit customer'
form_options: { validation_groups: ['Default'] }
# ...
```
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:
1. All the fields defined in the `form` view are copied in the same order into
the `edit` and `new` views.
2. Any field defined in the `edit` or `new` view which is not present in the
`form` view is added after the `form` fields.
3. 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`)
Consider the following complex form field configuration:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
fields:
- id
- { property: 'name', icon: 'user' }
- { property: 'email', css_class: 'input-large' }
new:
fields:
- '-id'
- { property: 'email', type_options: { required: false } }
edit:
fields:
- { property: 'name', icon: 'customer' }
- { property: 'email', help: 'Phone number is preferred' }
- phone
# ...
```
The above configuration is equivalent to the following:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
new:
fields:
- { property: 'name', icon: 'user' }
- { property: 'email', css_class: 'input-large', type_options: { required: false } }
edit:
fields:
- id
- { property: 'name', icon: 'customer' }
- { property: 'email', css_class: 'input-large', help: 'Phone number is preferred' }
- phone
# ...
```
## General Configuration
In order to make examples more concise, this section only shows the
configuration for the special `form` view, but you can apply the same options
to the other `edit` and `new` views.
Customize the Title of the PageThis 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:
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
label: 'Customers'
form:
title: "Add/edit customers"
# ...The title option can include the following special variables:
%entity_label%, resolves to the value defined in thelabeloption 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 beCustomers.%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 beCustomer.%entity_id%, it’s only available for theeditview and it resolves to the value of the primary key of the entity being edited. Even if the option is calledentity_id, it also works for primary keys with names different fromid.
.. caution::
In Symfony applications, YAML values enclosed with ``%`` and ``%`` have a
special meaning (they are considered container parameters). Escape these
values doubling the ``%`` characters:
.. code-block:: yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
label: 'Customers'
form:
title: '%%entity_label%% listing'
# ...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):
# config/packages/easy_admin.yaml
easy_admin:
edit:
title: '%%entity_label%%_edit'
new:
title: 'New %%entity_label%%'Display a Help Message in the Page
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:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
help: 'Global message displayed in all views'
# ...
form:
help: 'The form view overrides the global help message'
# ...
edit:
# 'help' is not defined, so the global help message is displayed
# ...
new:
# use the null value to not display the inherited global help message
help: null
# ...
# ...
```
Customize the Properties DisplayedBy default, the edit and new views display all the entity properties.
Use the fields option to explicitly set the properties to display in each
view:
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
fields: ['firstName', 'lastName', 'phone', 'email']
# ...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``Virtual Properties …
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 name virtual property to set its value.
.. note::
The values or virtual properties are set using the [PropertyAccess component](https://symfony.com/doc/current/components/property_access.html)
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()`.Defining Custom Form Options
By default, the forms built to create and edit entities only define the
data_class configuration option:
$form = $this->createFormBuilder($entity, [
'data_class' => 'App\Entity\Customer',
])
-> ...If you need to pass custom options to the forms, define the form_options
option under the edit, new or form options:
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
form_options: { validation_groups: ['Default', 'my_validation_group'] }
# ...The above example makes the backend use the following PHP code to build the form:
$form = $this->createFormBuilder($entity, [
'data_class' => 'App\Entity\Customer',
'validation_groups' => ['Default', 'my_validation_group'],
])
-> ...Customize the Form Fields
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:
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
fields: ['name', { property: 'email', label: 'Contact' }]
# ...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:
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
fields:
- name
- { property: 'email', label: 'Contact' }
# ...These are the options that you can define for each field:
-
property(mandatory): the name of the property to bet set (innewview) or modified (ineditview). 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.publishedis displayed asPublishedanddateOfBirthasDate of birth).If the form field renders a collection of items, the numeric auto-increment label of the collection items is hidden by default. If you want to display it, set the
entry_options.labeloption totrue:- { property: '...', type: 'collection', type_options: { entry_options: { label: true } } -
help(optional): the help message displayed below the form field. You can also define this value via thetype_options: { help: '...' }option. -
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. -
permission(optional): a string or array defining the role or roles the current user must have to see this form field. It’s explained later in the :ref:Security permissions <edit-new-security>section. -
type(optional): the Symfony Form type used to render this field. In addition to its fully qualified class name (e.g.Symfony\Component\Form\Extension\Core\Type\EmailType), you can also use the short type name (e.g.email) (the map between names and classes is done internally by the bundle). The allowed values are:- Any of the Symfony Form types.
- Any of the custom EasyAdmin form types:
code_editor,file_upload,text_editor,easyadmin_autocomplete(they are explained later in this chapter).
-
type_options(optional), a hash with the options passed to the Symfony Form type used to render the field.
The type_options is the most powerful option because it literally comprises
tens of options suited for each form type:
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
fields:
- 'id'
- { property: 'email', type: 'email', type_options: { trim: true } }
- { property: 'interests', type_options: { expanded: true, multiple: true } }
- { property: 'updated_at', type_options: { widget: 'single_text' } }Read the Symfony Form types reference to learn about all the available options, their usage and allowed values.
.. tip::
Symfony makes Doctrine relations nullable by default. Instead of adding the
``type_options: { required: true }`` option to all those fields, it's simpler
to add ``@ORM\JoinColumn(nullable=false)`` to the property that defines the
relation in the entity class.Formatting Dates and Numbers
Customizing Date and Time Properties
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`):
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Event:
edit:
fields:
- { property: 'startsAt', type_options: { widget: 'single_text' } }
# ...
```
Customizing Numeric Properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Product:
edit:
fields:
- { property: 'price', type: 'money', type_options: { currency: 'EUR' } }
# ...
```
## Custom Doctrine Types
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:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
fields:
- { property: 'createdAt', type: 'utcdatetime' }
# ...
# ...
```
This problem is solved defining a custom `utcdatetime` Form Type. Read the
[How to Create a Custom Form Field Type](https://symfony.com/doc/current/cookbook/form/create_custom_field_type.html) article to learn how to define
custom form types.
## EasyAdmin Form Types
In addition to the Symfony Form types, fields can use any of the following types
defined by EasyAdmin.
Autocomplete
~~~~~~~~~~~~
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:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Product:
class: App\Entity\Product
form:
fields:
- { property: 'category', type: 'easyadmin_autocomplete' }
# ...
# ...
```
The `easyadmin_autocomplete` type configures the class of the related entity
automatically. If you prefer to define it explicitly, do it in the type options:
``` yaml
# ...
- { property: 'category', type: 'easyadmin_autocomplete', type_options: { class: 'App\Entity\Category' } }
```
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):
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
show:
max_results: 20
entities:
Category:
show:
max_results: 5
# ...
```
Code Editor
~~~~~~~~~~~
It displays a JavaScript-based editor for source code. It provides advanced
features such as code highlighting and smart indenting.
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Server:
class: App\Entity\Server
form:
fields:
- { property: 'config', type: 'code_editor', language: 'nginx' }
# ...
# ...
```
This type defines the following configuration options:
- `height`: the initial height of code blocks is the same as their contents
and it grows automatically as you add more contents. This option, which must
be an integer, sets the height of the code block element in pixels. If
contents don't fit, a scrollbar is displayed.
- `language`: sets the programming language used for the syntax highlighting
of the code (the language can't be autodetected from the contents). The available
languages are: `css`, `dockerfile`, `js` (equivalent to `javascript`),
`markdown`, `nginx`, `php`, `shell`, `sql`, `twig`, `xml`,
``yaml-frontmatter`` (used in some blogs, CMS systems and static site
generators), `yaml`.
- `tab_size`: an integer (default: `4`) that defines the indention size (no
matter if the code uses white spaces or tabs).
- `indent_with_tabs`: if this boolean option is set to `true`, code is
indented with real tabs instead of white spaces (default: `false`).
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
ExamQuestion:
class: App\Entity\ExamQuestion
form:
fields:
- { property: 'question', type: 'code_editor', language: 'yaml', height: 150, tab_size: 4 }
- { property: 'codeSample', type: 'code_editor', language: 'php', height: 600, tab_size: 2 }
# ...
# ...
```
File Upload
~~~~~~~~~~~
It displays an advanced file upload widget which supports single and multiple
uploads, deleting files, etc.
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
User:
class: App\Entity\User
form:
fields:
- { property: 'photo', type: 'file_upload' }
# ...
# ...
```
This type defines the following configuration options:
- `upload_dir`: (optional; default `public/uploads/files/`) a string with
the path to the directory where the files are uploaded. If the value doesn't
start with a directory separator (e.g. `/var/sites/uploads`), it's considered
relative to the `kernel.project_dir` value;
- `download_path`: (optional) a PHP callable that returns the relative path
where assets can be downloaded. For example, if `upload_dir` is `public/contracts/`,
this option would be `contracts/` and the public asset URL would be
``https://example.com/contracts/filename.extension``. Overriding this option is
useful in complex scenarios such as when uploading files to a cloud service which
creates special URLs to access to assets;
- `upload_filename`: (optional; by default the original name is used) if defined,
this string is the pattern used to rename the uploaded file. You can also pass a
PHP callable to use some logic to generate the new file name. Example of a
file name pattern: ``[year]/[month]/[day]/[slug]-[contenthash].[extension]``.
The available placeholders in the pattern are:
* ``[contenthash]``, the SHA1 hash of the entire file contents;
* ``[day]``, the current day of the month with leading zeros (e.g. `07`);
* ``[extension]``, the guessed extension for the uploaded file (it can be
different from the original file extension);
* ``[month]``, the current month number with leading zeros (e.g. March = `03`);
* ``[name]``, the original file name without the extension;
* ``[randomhash]``, an alphanumeric random string;
* ``[slug]``, the slug of the original file name (i.e. the name is lower cased
and any non-ASCII letter or number is removed);
* ``[timestamp]``, the current timestamp;
* ``[uuid]``, a random UUID v4 value;
* ``[year]``, the current year with 4 digits (e.g. `2020`).
- `allow_add`: (optional, default = `true`) a boolean value which is only
used when the `multiple` option is `true`. If set to `false`, when you
upload new files, all the previous files are deleted. If set to `true`, the
new files are added to the list of previously uploded files;
- `allow_delete`: (optional, default `true`) a boolean value indicating if
uploaded files can be deleted directly in the edit/new form;
- `multiple`: (optional, default `false`) a boolean value indicating if
it's allowed to upload more than one file;
- `upload_new`: (optional) a PHP callable used to move the uploaded file/s to
its final destination. By default it's just ``$file->move($uploadDir, $fileName)``.
It's useful in complex scenarios such as moving the files to some cloud service;
- `upload_delete`: (optional) a PHP callable to delete the uploaded file/s.
By default it's just ``unlink($file->getPathname())``. It's useful in complex
scenarios such as performing some tasks before/after deleting files or when you
also need to delete the file from other locations (e.g. cloud services).
- `upload_validate`: (optional) a PHP callable used to validate the uploaded files
before moving them to their final destination. By default it checks duplicated
files and renames them. It's useful in complex scenarios such as validating
files that will be moved to some cloud service.
This form type uses a [form data transformer](https://symfony.com/doc/current/form/data_transformers.html) to manage the file resource to
file path conversion. This means that only the file path/s is/are stored in the
entity property and not the entire file/s contents. In other words, your file
upload property should be a varchar/string/text property and not a binary blob.
Text Editor
~~~~~~~~~~~
It displays a JavaScript-based WYSIWYG text editor based on the popular
[Trix editor](https://trix-editor.org/). You don't need to install any external dependencies because
EasyAdmin includes them dynamically when needed. The result of editing the
contents is stored as HTML in the given property:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
ExamQuestion:
class: App\Entity\BlogPost
form:
fields:
- { property: 'content', type: 'text_editor' }
# ...
# ...
```
This field does not define any configuration option. It has been designed to
provide the most commonly needed formatted options. If this doesn't fit your
needs, you can :doc:`integrate the popular CKEditor text editor with EasyAdmin </integration/ivoryckeditorbundle>`.
## Advanced Form Design
Selecting the Form Theme
~~~~~~~~~~~~~~~~~~~~~~~~
By default, forms are displayed using a proprietary form theme compatible with
the Bootstrap 4 CSS framework.
.. image:: ../images/easyadmin-new-view.png
:alt: Default form style
The form style can be changed with the `form_theme` design option:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
design:
# ...
# this is the default form theme used by backends
form_theme: '@EasyAdmin/form/bootstrap_4.html.twig'
# you can use your own form theme
form_theme: '@App/form/custom_layout.html.twig'
# you can also define an array of form themes to use all of them
form_theme:
- 'admin/form/custom_layout.html.twig'
- 'form_div_layout.html.twig'
- '@EasyAdmin/form/bootstrap_4.html.twig'
```
Customizing the Form Fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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, EasyAdmin forms follow the same mechanism defined by Symfony to
[customize individual form fields](https://symfony.com/doc/current/form/form_customization.html#how-to-customize-an-individual-field).
Imagine a form field where you want to include a ``<a>`` element that links to
additional information. If the field is called `title` and belongs to a
`Product` entity, the configuration would look like this:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
# ...
entities:
Product:
class: App\Entity\Product
form:
fields:
- { property: title, type_options: { block_name: 'custom_title' } }
# ...
```
The next step is to define the template fragment used by that field, which
requires to know the [form fragment naming rules](https://symfony.com/doc/current/form/form_themes.html#form-template-blocks) defined by Symfony:
``` html+twig
{# templates/admin/form.html.twig #}
{% block _product_custom_title_widget %}
{# ... #}
<a href="...">More information</a>
{% endblock %}
```
Finally, add this custom theme to the list of themes used to render backend forms:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
# ...
design:
form_theme:
- '@EasyAdmin/form/bootstrap_4.html.twig'
# 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
- 'admin/form.html.twig'
```
Customizing the Form Layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 (tabs, groups, sections) to create
more advanced layouts.
Form Sections
.............
This design element helps you divide a long form into different sections using
a subtle line. They are defined with elements of type `section`:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
# ...
entities:
Customer:
class: App\Entity\Customer
form:
fields:
- id
- { type: 'section', label: 'User Details' }
- name
- surname
- { type: 'section', label: 'Contact information', icon: 'phone',
help: 'Phone number is preferred' }
- email
- phoneNumber
```
The configurable options of this element are:
- `label` (optional, `string`), leave it empty if you only want to display
a separator line.
- `icon` (optional, `string`), the name of the FontAwesome icon without the
``fa-`` prefix (e.g. don't use ``fa fa-user`` or ``fa-user`` but `user`).
- `css_class` (optional, `string`), you can apply multiple classes separating
them with white spaces.
- `help` (optional, `string`), text displayed to describe the form section
or display helpful messages. It can include HTML elements.
A form that includes sections is still displayed as a single form that spans
the entire available width. Multi-column forms are created with "groups"
as explained below.
.. image:: ../images/easyadmin-form-section.png
:alt: A form using sections to separate its fields
Form Groups
...........
This element groups one or more fields using ``<fieldset>`` elements and
displays them separately from the rest of the form fields. It's useful to create
multi-column forms and to create very advanced layouts. They are defined with
elements of type `group`:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Customer:
class: App\Entity\Customer
form:
fields:
- { type: 'group', columns: 4, label: 'Basic information' }
- id
- name
- surname
- { type: 'group', label: 'Contact information', icon: 'phone', columns: 6 }
- email
- phoneNumber
```
.. image:: ../images/easyadmin-form-group.png
:alt: A form using groups to separate its fields
The configurable options of this element are:
- `label` (optional, `string`), leave it empty if you only want to display
a the ``<fieldset>`` without the ``<legend>`` element.
- `icon` (optional, `string`), the name of the FontAwesome icon without the
``fa-`` prefix (e.g. don't use ``fa fa-user`` or ``fa-user`` but `user`).
- `css_class` (optional, `string`), you can apply multiple classes separating
them with white spaces.
- `columns` (optional, `integer`), the number of columns that spans this
form group. The default value is `12`, which spans the whole row. Ideal to
display complex forms as multi-column forms.
- `help` (optional, `string`), text displayed to describe the form group
or display helpful messages. It can include HTML elements.
.. tip::
Because of the way CSS works, when creating multi-column forms is common to
have ugly gaps between some rows and columns. Use the ``.w-100`` CSS class
provided by Bootstrap 4 to force the form group to be displayed in a new row:
.. code-block:: yaml
# ...
- { type: 'group', css_class: 'w-100 ...' }
This solves most of the issues, but sometimes you might be forced to also
reorder the form group positions.
Form Tabs
.........
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 not the other
way around) to create clean interfaces when forms contains lots of fields. They
are defined with elements of type `tab`:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
User:
class: App\Entity\User
form:
fields:
- { type: 'tab' , label: 'Basic Information' }
- id
- name
- surname
- { type: 'tab', label: 'Contact Information', icon: 'phone' }
- email
- phone
```
.. image:: ../images/easyadmin-form-tabs.png
:alt: A form using tabs to separate its fields
The configurable options of this element are:
- `label` (mandatory, `string`), displayed as the clickable name of the tab.
- `icon` (optional, `string`), the name of the FontAwesome icon without the
``fa-`` prefix (e.g. don't use ``fa fa-user`` or ``fa-user`` but `user`).
- `css_class` (optional, `string`), you can apply multiple classes separating
them with white spaces.
- `help` (optional, `string`), text displayed to describe the form tab
or display helpful messages. It can include HTML elements.
Design elements can be combined to display sections inside groups and create
advanced layouts:
.. image:: ../images/easyadmin-form-complex-layout.png
:alt: A complex form layout combining sections and groups
## Advanced Design Configuration
The previous sections explain how to customize the design of the forms and their
fields using Symfony's Form component features. EasyAdmin also lets you
customize the entire `edit` and `new` views, similar to how the other
views (`list`, `show`, etc.) are customized.
EasyAdmin defines several Twig templates to create its interface. These are the
templates related to `edit` and `new` views:
- `@EasyAdmin/default/layout.html.twig`, the common layout that decorates the
rest of the main templates;
- `@EasyAdmin/default/new`, renders the page where new entities are created;
- `@EasyAdmin/default/edit`, renders the page where entity contents are edited;
.. note::
The special `form` view doesn't have a template associated. The template
configured for `form` will be used for both `edit` and `new` unless
they override that template in their own configuration.
Depending on your needs, there are several customization options:
1) Override the default EasyAdmin templates using Symfony's overriding mechanism.
Useful to add or change minor things in the default interface.
2) Use your own templates to display the edit/new views and all their elements.
Useful if you want to customize the interface entirely.
Overriding the Default Templates Using Symfony's MechanismSymfony allows to override any part of third-party bundles. To override one
of the default EasyAdmin templates, create a new template inside
templates/bundles/EasyAdminBundle/default/ with the same path as the
template to override. Example:
your-project/
├─ ...
└─ templates/
└─ bundles/
└─ EasyAdminBundle/
└─ default/
├─ new.html.twig
└─ edit.html.twig.. tip::
Add an empty ``{{ dump() }}`` call in your custom templates to know which
variables are passed to them by EasyAdmin.Instead of creating the new templates from scratch, you can extend from the
original templates and change only the parts you want to override. However, you
must use a special syntax inside extends to avoid an infinite loop:
{# templates/bundles/EasyAdminBundle/default/layout.html.twig #}
{# DON'T DO THIS: it will cause an infinite loop #}
{% extends '@EasyAdmin/default/layout.html.twig' %}
{# DO THIS: the '!' symbol tells Symfony to extend from the original template #}
{% extends '@!EasyAdmin/default/layout.html.twig' %}
{% block sidebar %}
{# ... #}
{% endblock %}Using your Own Templates to Display the edit/new Views
Add the `templates` option (globally or only to some entities) to define the
path of the Twig template used to render each part of the interface:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
design:
# these custom templates are applied to all entities
templates:
edit: 'admin/custom_edit_form.html.twig'
entities:
Customer:
# ...
# these custom templates are only applied to this entity and
# they override any global template defined in 'design.templates'
templates:
edit: 'admin/customer/edit.html.twig'
new: 'admin/customizations/customer_new.html.twig'
```
The name of the config option matches the name of the template files inside
`src/Resources/views/` (e.g. `layout`, `edit`, `new`, etc.) The value of
the options can be any valid Twig template path.
.. tip::
Add an empty ``{{ dump() }}`` call in your custom templates to know which
variables are passed to them by EasyAdmin.
Instead of creating the new templates from scratch, you can extend from the
original templates and change only the parts you want to override. Suppose you
only want to change the way titles are displayed on the `new` view. To do so,
create the following `new.html.twig` template extending from the default one
and override only the `content_title` Twig block:
``` twig
{# templates/admin/new.html.twig #}
{% extends '@EasyAdmin/default/new.html.twig' %}
{% block content_title %}
{# ... customize the content title ... #}
{% endblock %}
```
## Security and Permissions
The `permission` option of each property allows to hide the associated form
field depending on the current user roles:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
entities:
Product:
edit:
fields:
# all users will see the first three form fields
- name
- price
- stock
# only users with this role will see this form field
- { property: 'taxRate', permission: 'ROLE_ADMIN' }
# this form field will only be displayed for users with one of these roles
# (or all of them, depending on your Symfony app configuration)
# (see https://symfony.com/doc/current/security/access_control.html#access-enforcement)
- { property: 'comission', permission: ['ROLE_SALES', 'ROLE_ADMIN'] }
# ...
```
You can also restrict which items can users create and/or edit with the
`item_permission` option. The role or roles defined in that option are passed
to the ``is_granted($roles, $item)`` function to decide if the current user can
create/edit the given item:
``` yaml
# config/packages/easy_admin.yaml
easy_admin:
edit:
# optionally you can define a global permission applied to all entities
# each entity can later override this by defining their own item_permission option
item_permission: 'ROLE_ADMIN'
entities:
Product:
edit:
# set this option to an empty string or array to unset the global permission for this entity
item_permission: ''
Employees:
edit:
# this completely overrides the global option (both options are not merged)
item_permission: ['ROLE_SUPER_ADMIN', 'ROLE_HUMAN_RESOURCES']
# ...
```
If the user doesn't have permission they will see an appropriate error message
(and you'll see a detailed error message in the application logs).
.. tip::
Combine the `item_permission` option with custom [Symfony security voters](https://symfony.com/doc/current/security/voters.html)
to better decide if the current user can see any given item.
##
Next chapter: :doc:`actions-configuration`