<commit_before>Chapter 6. Customizing the New and Edit Views
=============================================

The `new` view is displayed when creating a new item of the given entity,
whereas the `edit` view is displayed when editing any entity instance. Both
views are pretty similar, so most of the times you apply them the same
customization.

Instead of duplicating the configuration for both views, you can define a new
*virtual* `form` view with the common configuration:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\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 will be 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 define in the `new`
and `edit` views just the specific options you want to override:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields: ['id', 'name', 'email']
                title:  'Add customer'
            new:
                fields: ['name', 'email']
            edit:
                title:  'Edit customer'
    # ...
```

The above configuration is equivalent to the following:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            new:
                fields: ['name', 'email']
                title:  'Add customer'
            edit:
                fields: ['id', 'name', 'email']
                title:  'Edit customer'
    # ...
```

Customize the Title of the Page
-------------------------------

By default, the title of the `edit`/`new` pages displays a very generic title.
Define the `title` option to set a custom page title:

```yaml
# app/config/config.yml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                title: 'Modify customer information'
        # ...
```

The `title` option can include any of the following two variables:

  * `%entity_name%`, resolves to the class name of the current entity (e.g.
    `Customer`, `Product`, `User`, etc.)
  * `%entity_id%`, resolves to the value of the primary key of the entity being
    edited. Obviously, this variable is not available for the title of the
    `new` action. Even if the option is called `entity_id`, it also works for
    primary keys with names different from `id`.

Beware that, in Symfony applications, YAML values enclosed with `%` and `%`
have a special meaning. Use two consecutive `%` characters to avoid any issue:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                title: 'Modify customer %%entity_id%% information'
        # ...
```

Customize which Fields are Displayed
------------------------------------

By default, the forms used to create and edit entities display all their
properties. Customize any of these forms for any of your entities using the
`fields` option:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields: ['firstName', 'secondName', 'phone', 'email']
    # ...
```

If any of the fields is an association with another entity, the form will
display it as a `<select>` list. The values displayed in this list will be the
values returned by the magic `__toString()` PHP method. Define this method in
all your entities to avoid errors and to define the textual representation of
the entity.

Customize the Order of the Fields Displayed
-------------------------------------------

By default, forms show their fields in the same order as they were defined in
the associated entities. You could customize the fields order just by
reordering the entity properties, but it's more convenient to just define the
order using the `fields` option:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields: ['firstName', 'secondName', 'phone', 'email']
    # ...
```

Customize the Form Fields Appearance
------------------------------------

By default, all form fields are displayed with the same visual style, they
don't show any help message, and their label and field type are inferred from
their associated Doctrine property.

In case you want to customize any or all form fields, use the extended form
field configuration showed below:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields:
                    - 'id'
                    - { property: 'email', type: 'email', label: 'Contact' }
                    - { property: 'code', type: 'number', label: 'Customer Code', class: 'input-lg' }
                    - { property: 'notes', help: 'Use this field to add private notes and comments about the client' }
                    - { property: 'zone', type: 'country' }
    # ...
```

These are the options that you can define for form fields:

  * `property` (mandatory): the name of the related Doctrine entity property.
    It can be a real property or a "virtual property" based on an entity
    method. This is the only mandatory option.
  * `type` (optional): the [Symfony Form Type](http://symfony.com/doc/current/reference/forms/types.html)
    used to render the field. If you don't specify a type, EasyAdmin will
    guess the best type for it.
  * `label` (optional): the title that will be displayed for the form field.
    The default title is the "humanized" version of the property name.
  * `help` (optional): the help message that will be displayed below the
    form field.
  * `class` (optional): the CSS class that will be applied to the form field
    widget container element. For example, when using the default Bootstrap
    based form theme, this value is applied to the `<div class="form-group">`
    element which wraps the label, the widget and the error messages of the
    field.

### Translate Form Field Labels

Read *"Translate Column Labels"* section of the [chapter 4](4-customizing-list-view.md).

Use Custom Doctrine Types in Forms
----------------------------------

When your application defines custom Doctrine DBAL types, you must define a
related custom form type 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 form field as follows, you'll get an error message
saying that the `utcdatetime` type couldn't be loaded:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields:
                    - { property: 'createdAt', type: 'utcdatetime' }
                    # ...
    # ...
```

This problem is solved defining a custom `utcdatetime` Form Type related to
this custom Doctrine DBAL type. Read the
[How to Create a Custom Form Field Type](http://symfony.com/doc/current/cookbook/form/create_custom_field_type.html)
article of the official Symfony documentation to learn how to define custom
form types.

Customize the Actions Used to Create and Edit Entities
------------------------------------------------------

By default, new and edited entities are persisted without any further
modification. In case you want to manipulate the entity before persisting it,
you can override the methods used by EasyAdmin.

Similarly to customizing templates, you need to use the Symfony bundle
[inheritance mechanism](http://symfony.com/doc/current/book/templating.html#overriding-bundle-templates)
to override the controller used to generate the backend. Among many other
methods, this controller contains two methods which are called just before the
entity is persisted:

```php
protected function prepareEditEntityForPersist($entity)
{
    return $entity;
}<commit_msg>Correct the link for overriding symfony controllers<commit_after>Chapter 6. Customizing the New and Edit Views
=============================================

The `new` view is displayed when creating a new item of the given entity,
whereas the `edit` view is displayed when editing any entity instance. Both
views are pretty similar, so most of the times you apply them the same
customization.

Instead of duplicating the configuration for both views, you can define a new
*virtual* `form` view with the common configuration:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\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 will be 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 define in the `new`
and `edit` views just the specific options you want to override:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields: ['id', 'name', 'email']
                title:  'Add customer'
            new:
                fields: ['name', 'email']
            edit:
                title:  'Edit customer'
    # ...
```

The above configuration is equivalent to the following:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            new:
                fields: ['name', 'email']
                title:  'Add customer'
            edit:
                fields: ['id', 'name', 'email']
                title:  'Edit customer'
    # ...
```

Customize the Title of the Page
-------------------------------

By default, the title of the `edit`/`new` pages displays a very generic title.
Define the `title` option to set a custom page title:

```yaml
# app/config/config.yml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                title: 'Modify customer information'
        # ...
```

The `title` option can include any of the following two variables:

  * `%entity_name%`, resolves to the class name of the current entity (e.g.
    `Customer`, `Product`, `User`, etc.)
  * `%entity_id%`, resolves to the value of the primary key of the entity being
    edited. Obviously, this variable is not available for the title of the
    `new` action. Even if the option is called `entity_id`, it also works for
    primary keys with names different from `id`.

Beware that, in Symfony applications, YAML values enclosed with `%` and `%`
have a special meaning. Use two consecutive `%` characters to avoid any issue:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                title: 'Modify customer %%entity_id%% information'
        # ...
```

Customize which Fields are Displayed
------------------------------------

By default, the forms used to create and edit entities display all their
properties. Customize any of these forms for any of your entities using the
`fields` option:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields: ['firstName', 'secondName', 'phone', 'email']
    # ...
```

If any of the fields is an association with another entity, the form will
display it as a `<select>` list. The values displayed in this list will be the
values returned by the magic `__toString()` PHP method. Define this method in
all your entities to avoid errors and to define the textual representation of
the entity.

Customize the Order of the Fields Displayed
-------------------------------------------

By default, forms show their fields in the same order as they were defined in
the associated entities. You could customize the fields order just by
reordering the entity properties, but it's more convenient to just define the
order using the `fields` option:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields: ['firstName', 'secondName', 'phone', 'email']
    # ...
```

Customize the Form Fields Appearance
------------------------------------

By default, all form fields are displayed with the same visual style, they
don't show any help message, and their label and field type are inferred from
their associated Doctrine property.

In case you want to customize any or all form fields, use the extended form
field configuration showed below:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields:
                    - 'id'
                    - { property: 'email', type: 'email', label: 'Contact' }
                    - { property: 'code', type: 'number', label: 'Customer Code', class: 'input-lg' }
                    - { property: 'notes', help: 'Use this field to add private notes and comments about the client' }
                    - { property: 'zone', type: 'country' }
    # ...
```

These are the options that you can define for form fields:

  * `property` (mandatory): the name of the related Doctrine entity property.
    It can be a real property or a "virtual property" based on an entity
    method. This is the only mandatory option.
  * `type` (optional): the [Symfony Form Type](http://symfony.com/doc/current/reference/forms/types.html)
    used to render the field. If you don't specify a type, EasyAdmin will
    guess the best type for it.
  * `label` (optional): the title that will be displayed for the form field.
    The default title is the "humanized" version of the property name.
  * `help` (optional): the help message that will be displayed below the
    form field.
  * `class` (optional): the CSS class that will be applied to the form field
    widget container element. For example, when using the default Bootstrap
    based form theme, this value is applied to the `<div class="form-group">`
    element which wraps the label, the widget and the error messages of the
    field.

### Translate Form Field Labels

Read *"Translate Column Labels"* section of the [chapter 4](4-customizing-list-view.md).

Use Custom Doctrine Types in Forms
----------------------------------

When your application defines custom Doctrine DBAL types, you must define a
related custom form type 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 form field as follows, you'll get an error message
saying that the `utcdatetime` type couldn't be loaded:

```yaml
easy_admin:
    entities:
        Customer:
            class: AppBundle\Entity\Customer
            form:
                fields:
                    - { property: 'createdAt', type: 'utcdatetime' }
                    # ...
    # ...
```

This problem is solved defining a custom `utcdatetime` Form Type related to
this custom Doctrine DBAL type. Read the
[How to Create a Custom Form Field Type](http://symfony.com/doc/current/cookbook/form/create_custom_field_type.html)
article of the official Symfony documentation to learn how to define custom
form types.

Customize the Actions Used to Create and Edit Entities
------------------------------------------------------

By default, new and edited entities are persisted without any further
modification. In case you want to manipulate the entity before persisting it,
you can override the methods used by EasyAdmin.

Similarly to customizing templates, you need to use the Symfony bundle
[inheritance mechanism](http://symfony.com/doc/current/cookbook/bundles/inheritance.html#overriding-controllers)
to override the controller used to generate the backend. Among many other
methods, this controller contains two methods which are called just before the
entity is persisted:

```php
protected function prepareEditEntityForPersist($entity)
{
    return $entity;
}
{'fraction_non_alphanumeric': 0.11025794841031794, 'fraction_numerical': 0.00035992801439712057, 'mean_word_length': 2.4767466110531804, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7311165', 'n_tokens_mistral': 4250, 'n_tokens_neox': 4084, 'n_words': 1986}