<commit_before>Chapter 5. List, Search and Show Views Configuration
====================================================

This chapter explains how to customize the read-only views: ``list``, ``search``
and ``show``. You'll learn all their configuration options and how to override
or tweak their templates.

List, Search and Show Views
---------------------------

The **List View** displays the items that match the given criteria and provides
automatic pagination and column sorting:

.. image:: ../images/easyadmin-list-view.png
   :alt: List view interface

The **Search View** displays the results of any query performed by the user.
It reuses most of the design and features of the ``list`` view to ensure a
consistent user experience:

.. image:: ../images/easyadmin-search-view.png
   :alt: Search view interface

The **Show View** displays the contents of a given entity:

.. image:: ../images/easyadmin-show-view.png
   :alt: Show view interface

General Configuration
---------------------

In order to make examples more concise, this section only shows the
configuration for the ``list`` view, but you can apply the exact same options to
the other ``search`` and ``show`` views.

Customize the Title of the Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                label: 'Customers'
                list:
                    title: "Most recent customers"
            # ...

The ``title`` value can include the following special variables:

* ``%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 ``show`` view and it resolves to
  the value of the primary key of the entity being showed. 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:

    .. code-block:: yaml

        easy_admin:
            entities:
                Customer:
                    class: AppBundle\Entity\Customer
                    label: 'Customers'
                    list:
                        title: '%%entity_label%% listing'
                # ...

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

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        list:
            title: 'list.%%entity_label%%'
        show:
            title: '%%entity_label%% (#%%entity_id%%)'

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:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                help: 'Global message displayed in all views'
                # ...
                list:
                    help: 'The list view overrides the global help message'
                    # ...
                show:
                    # 'help' is not defined, so the global help message is displayed
                    # ...
                search:
                    # use the null value to not display the inherited global help message
                    help: null
                    # ...
            # ...

Customize the Number of Rows Displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, listings in the ``list`` and ``search`` display a maximum of 15
rows. Define the ``max_results`` option under the global ``list`` key to change
this value:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        list:
            max_results: 30
        # ...

In addition, the ``show`` view displays a maximum of 10 items for fields related
with other entities (e.g. if ``Category`` and ``Product`` entities are related,
it displays a maximum of 10 products when browsing the details of some
category). Define the ``max_results`` option under the global ``show`` key to
change this value:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        show:
            max_results: 20
        # ...

Customize the Properties Displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the ``show`` view displays all the entity properties and the
``list`` and ``search`` views make some "smart guesses" to decide which columns
to display to make listings look good.

Use the ``fields`` option to explicitly set the properties to display:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields: ['id', 'firstName', 'lastName', 'phone', 'email']
        # ...

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

In the case of the ``search`` view, this ``fields`` option defines the
properties included in the search query. Otherwise, the query is performed on
all entity properties except those with special data types, such as ``binary``,
``blob``, ``object``, etc.

Customize the Properties Appearance
-----------------------------------

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

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields: ['id', '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:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields:
                        - id
                        - name
                        - { property: 'email', label: 'Contact' }
        # ...

These are the options that you can define for each field:

* ``property`` (mandatory): the name of the property to be displayed. This is
  the only mandatory option when using the extended field configuration format.
* ``label`` (optional): the title displayed for the field (as the column name in
  the ``list`` and ``search`` views and as the ``<label>`` element in the
  ``show`` view).

  The default title is the "humanized" version of the property name (e.g.
  ``published`` is displayed as ``Published`` and ``dateOfBirth`` as
  ``Date of birth``).
* ``css_class`` (optional): the CSS class applied to the parent HTML element that
  encloses the field contents. In the ``list`` and ``search`` views, this class
  is also applied to the ``<th>`` header of the column associated with this field.
  For example, to align the contents of some column to the right, use ``css_class: text-right``
* ``template`` (optional): the name of the custom template used to render the
  contents of the field. This option is fully explained later in this chapter.
* ``type`` (optional): the type of data stored in the property, which affects
  how the contents are displayed. The allowed values are:

  * Any of the Doctrine types: ``array``, ``association``, ``bigint``, ``blob``,
    ``boolean``, ``date``, ``datetime``, ``datetimetz``, ``decimal``, ``float``,
    ``guid``, ``integer``, ``json_array``, ``object``, ``simple_array``,
    ``smallint``, ``string``, ``text``, ``time``.
  * Any of the custom EasyAdmin types: ``email``, ``image``, ``raw``, ``tel``,
    ``toggle``, ``url`` (they are explained later in this chapter).

The fields of the ``list`` and ``search`` views define another option:

* ``sortable`` (optional): if ``true`` the backend allows to sort results by
  this property; set it to ``false`` to disable sorting. All properties are
  *sortable* by default except virtual properties (explained later in this
  chapter) and those related with Doctrine associations of any type.

The fields of the ``show`` view can define another option:

* ``help`` (optional): the help message displayed below the field contents.

.. tip::

    In addition to these options defined by EasyAdmin, you can define any custom
    option for the fields. This way you can create very powerful backend
    customizations, as explained in the :doc:`../tutorials/custom-property-options`
    tutorial.

Formatting Dates and Numbers
----------------------------

Customizing Date and Time Properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, these are the formats applied to date and time properties (read the
`date configuration options`_ in the PHP manual if you don't understand the
meaning of these formats):

* ``date``: ``Y-m-d``
* ``time``:  ``H:i:s``
* ``datetime``: ``F j, Y H:i``

These default formats can be overridden in two ways: globally for all entities
and locally for each entity property. The global ``formats`` option sets the
formats for all entities and their properties:

.. code-block:: yaml

    easy_admin:
        formats:
            date:     'd/m/Y'
            time:     'H:i'
            datetime: 'd/m/Y H:i:s'
        entities:
            # ...

The values of the ``date``, ``time`` and ``datetime`` options are passed to the
``format()`` method of the ``DateTime`` class, so you can use any of the
`date configuration options`_ defined by PHP.

Date/time formatting can also be defined in each property configuration using
the ``format`` option. This local option always overrides the global format:

.. code-block:: yaml

    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields:
                        - { property: 'dateOfBirth', format: 'j/n/Y' }
                        # ...
        # ...

Customizing Numeric Properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Numeric properties (``bigint``, ``integer``, ``smallint``, ``decimal``,
``float``) are formatted by default according to the locale of your Symfony
application. This formatting can be overridden globally for all entities or
locally for each property.

The global ``formats`` option applies the same formatting for all entities:

.. code-block:: yaml

    easy_admin:
        formats:
            # ...
            number: '%.2f'
        entities:
            # ...

In this case, the value of the ``number`` option is passed to the ``sprintf()``
function, so you can use any of the `PHP format specifiers`_.

Numeric properties can also define their formatting using the ``format``
option. This local option always overrides the global format:

.. code-block:: yaml

    easy_admin:
        entities:
            Product:
                class: AppBundle\Entity\Product
                list:
                    fields:
                        - { property: 'serialNumber', format: '%010s' }
                        - { property: 'margin', format: '%01.2f' }
                        # ...
        # ...

Virtual Properties
------------------

Sometimes, it's useful to display values which are not entity properties. For
example, if your ``Customer`` entity defines the ``firstName`` and ``lastName``
properties, you may want to display a column called ``Name`` with both values
merged. These are called *virtual properties* because they don't really exist as
Doctrine entity properties.

First add the virtual property to the entity configuration as any other property:

.. code-block:: yaml

    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    # 'name' doesn't exist as a Doctrine entity property
                    fields: ['id', 'name', 'phone', 'email']
        # ...

Now, if you reload the backend, you'll see that the virtual property only
displays ``Inaccessible`` as its value. The reason is that ``name`` does not
match any of the entity's properties. To fix this issue, add a new public method
in your entity called ``getName()``:

.. code-block:: php

    use Doctrine\ORM\Mapping as ORM;

    /** @ORM\Entity */
    class Customer
    {
        // ...

        public function getName()
        {
            return $this->getFirstName().' '.$this->getLastName();
        }
    }

That's it. Reload your backend and now you'll see the value of this virtual
property.

.. note::

    The values or virtual properties are get using the `PropertyAccess component`_
    from Symfony, which requires to follow a strict syntax for getter names:
    ``get`` + camelized version of the property name. Example: ``name`` ->
    ``getName()``; ``firstName`` -> ``getFirstName()``; ``first_and_last_name`` ->
    ``getFirstAndLastName()``.

By default, virtual properties are displayed as text contents. If your virtual
property is a *boolean* value or a date, use the ``type`` option to set a more
appropriate data type:

.. code-block:: yaml

    # in this example, the virtual properties 'is_eligible' and 'last_contact' define
    # their 'type' option to avoid displaying them as regular text contents
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields:
                        - 'id'
                        - { property: 'is_eligible',  type: 'boolean' }
                        - { property: 'last_contact', type: 'datetime' }
        # ...

The main limitation of virtual properties is that you cannot sort listings
using these fields.

Sorting Entity Listings
-----------------------

By default the ``list`` and ``search`` views sort the rows in descending order
according to the value of the primary key. You can sort by any other entity
property using the ``sort`` configuration option:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            User:
                # ...
                list:
                    # if the sort order is not specified, 'DESC' is used
                    sort: 'createdAt'
                search:
                    # use an array to also define the sorting direction
                    sort: ['createdAt', 'ASC']

            Purchase:
                # ...
                # the 'sort' option supports Doctrine associations up to one level
                # (e.g. 'sort: user.name' works but 'sort: user.group.name' won't work)
                list:
                    sort: 'user.name'
                search:
                    sort: ['user.name', 'ASC']

The ``sort`` option of each entity is only used as the default content sorting. If
the query string includes the optional ``sortField`` and ``sortDirection``
parameters, their values override this ``sort`` option. This happens for example
when defining a different sorting in a custom menu and when clicking on the
listings columns to reorder the displayed contents.

Filtering Entities
------------------

A common need for backends is to filter the entities included in listings (for
example: don't display expired offers, display only clients that spend more than
a given amount, etc.) You can achieve this with the features explained later in
this chapter to modify the behavior of the ``list``, ``search`` and ``show`` views.

However, for simple filters it's more convenient to use the ``dql_filter`` option,
which defines the conditions passed to the ``WHERE`` clause of the Doctrine query
used to get the entities displayed in the ``list`` and ``search`` views.

The following example manages the same ``User`` entity in two different ways using
a basic filter to differentiate each type of user:

.. code-block:: yaml

    easy_admin:
        entities:
            VipCustomers:
                class: AppBundle\Entity\User
                list:
                    dql_filter: 'entity.budget > 100000'
            RegularCustomers:
                class: AppBundle\Entity\User
                list:
                    dql_filter: 'entity.budget <= 100000'

The Doctrine DQL expression defined in the ``dql_filter`` option must always use
``entity`` as the name of the entity, regardless of your actual entity name.

Since this is a regular YAML configuration file, you can also include container
parameters inside the filter to use different values depending on the environment
or even dynamic values:

.. code-block:: yaml

    easy_admin:
        entities:
            VipCustomers:
                class: AppBundle\Entity\User
                list:
                    dql_filter: 'entity.budget > %customers.budget_threshold%'
            # ...

The value of the ``dql_filter`` can combine several conditions (in fact, you can
put anything that is considered valid as a ``WHERE`` clause in a Doctrine query):

.. code-block:: yaml

    easy_admin:
        entities:
            UrgentIssues:
                class: AppBundle\Entity\Issue
                list:
                    dql_filter: 'entity.label = "CRITICAL" OR entity.priority > 4'
            ImportantIssues:
                class: AppBundle\Entity\Issue
                list:
                    dql_filter: 'entity.priority > 2 AND entity.numComments > 10'
            AllIssues:
                class: AppBundle\Entity\Issue

.. note::

    By default the ``dql_filter`` option from the ``list`` view is also used in the
    ``search`` view. If you prefer to apply different filters, define the
    ``dql_filter`` option explicitly for the ``search`` view:

    .. code-block:: yaml

        easy_admin:
            entities:
                Issues:
                    class: AppBundle\Entity\Issue
                    list:
                        dql_filter: "LOWER(entity.title) LIKE '%%issue%%'"
                    search:
                        # defining a different condition than 'list'
                        dql_filter: 'entity.status != "DELETED"'
                        # using an empty value to not apply any condition when searching
                        # elements (this prevents inheriting the 'dql_filter' value defined in 'list')
                        dql_filter: ''

.. tip::

    Combine the ``dql_filter`` option with a custom menu (as explained in the next
    chapters) to improve the navigation of the backend.

Property Types Defined by EasyAdmin
-----------------------------------

In addition to the Doctrine data types, properties can use any of the following
data types defined by EasyAdmin.

Email Data Type<commit_msg>Fixed some issues in the DQL examples of the docs<commit_after>Chapter 5. List, Search and Show Views Configuration
====================================================

This chapter explains how to customize the read-only views: ``list``, ``search``
and ``show``. You'll learn all their configuration options and how to override
or tweak their templates.

List, Search and Show Views
---------------------------

The **List View** displays the items that match the given criteria and provides
automatic pagination and column sorting:

.. image:: ../images/easyadmin-list-view.png
   :alt: List view interface

The **Search View** displays the results of any query performed by the user.
It reuses most of the design and features of the ``list`` view to ensure a
consistent user experience:

.. image:: ../images/easyadmin-search-view.png
   :alt: Search view interface

The **Show View** displays the contents of a given entity:

.. image:: ../images/easyadmin-show-view.png
   :alt: Show view interface

General Configuration
---------------------

In order to make examples more concise, this section only shows the
configuration for the ``list`` view, but you can apply the exact same options to
the other ``search`` and ``show`` views.

Customize the Title of the Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                label: 'Customers'
                list:
                    title: "Most recent customers"
            # ...

The ``title`` value can include the following special variables:

* ``%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 ``show`` view and it resolves to
  the value of the primary key of the entity being showed. 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:

    .. code-block:: yaml

        easy_admin:
            entities:
                Customer:
                    class: AppBundle\Entity\Customer
                    label: 'Customers'
                    list:
                        title: '%%entity_label%% listing'
                # ...

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

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        list:
            title: 'list.%%entity_label%%'
        show:
            title: '%%entity_label%% (#%%entity_id%%)'

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:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                help: 'Global message displayed in all views'
                # ...
                list:
                    help: 'The list view overrides the global help message'
                    # ...
                show:
                    # 'help' is not defined, so the global help message is displayed
                    # ...
                search:
                    # use the null value to not display the inherited global help message
                    help: null
                    # ...
            # ...

Customize the Number of Rows Displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, listings in the ``list`` and ``search`` display a maximum of 15
rows. Define the ``max_results`` option under the global ``list`` key to change
this value:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        list:
            max_results: 30
        # ...

In addition, the ``show`` view displays a maximum of 10 items for fields related
with other entities (e.g. if ``Category`` and ``Product`` entities are related,
it displays a maximum of 10 products when browsing the details of some
category). Define the ``max_results`` option under the global ``show`` key to
change this value:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        show:
            max_results: 20
        # ...

Customize the Properties Displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the ``show`` view displays all the entity properties and the
``list`` and ``search`` views make some "smart guesses" to decide which columns
to display to make listings look good.

Use the ``fields`` option to explicitly set the properties to display:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields: ['id', 'firstName', 'lastName', 'phone', 'email']
        # ...

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

In the case of the ``search`` view, this ``fields`` option defines the
properties included in the search query. Otherwise, the query is performed on
all entity properties except those with special data types, such as ``binary``,
``blob``, ``object``, etc.

Customize the Properties Appearance
-----------------------------------

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

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields: ['id', '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:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields:
                        - id
                        - name
                        - { property: 'email', label: 'Contact' }
        # ...

These are the options that you can define for each field:

* ``property`` (mandatory): the name of the property to be displayed. This is
  the only mandatory option when using the extended field configuration format.
* ``label`` (optional): the title displayed for the field (as the column name in
  the ``list`` and ``search`` views and as the ``<label>`` element in the
  ``show`` view).

  The default title is the "humanized" version of the property name (e.g.
  ``published`` is displayed as ``Published`` and ``dateOfBirth`` as
  ``Date of birth``).
* ``css_class`` (optional): the CSS class applied to the parent HTML element that
  encloses the field contents. In the ``list`` and ``search`` views, this class
  is also applied to the ``<th>`` header of the column associated with this field.
  For example, to align the contents of some column to the right, use ``css_class: text-right``
* ``template`` (optional): the name of the custom template used to render the
  contents of the field. This option is fully explained later in this chapter.
* ``type`` (optional): the type of data stored in the property, which affects
  how the contents are displayed. The allowed values are:

  * Any of the Doctrine types: ``array``, ``association``, ``bigint``, ``blob``,
    ``boolean``, ``date``, ``datetime``, ``datetimetz``, ``decimal``, ``float``,
    ``guid``, ``integer``, ``json_array``, ``object``, ``simple_array``,
    ``smallint``, ``string``, ``text``, ``time``.
  * Any of the custom EasyAdmin types: ``email``, ``image``, ``raw``, ``tel``,
    ``toggle``, ``url`` (they are explained later in this chapter).

The fields of the ``list`` and ``search`` views define another option:

* ``sortable`` (optional): if ``true`` the backend allows to sort results by
  this property; set it to ``false`` to disable sorting. All properties are
  *sortable* by default except virtual properties (explained later in this
  chapter) and those related with Doctrine associations of any type.

The fields of the ``show`` view can define another option:

* ``help`` (optional): the help message displayed below the field contents.

.. tip::

    In addition to these options defined by EasyAdmin, you can define any custom
    option for the fields. This way you can create very powerful backend
    customizations, as explained in the :doc:`../tutorials/custom-property-options`
    tutorial.

Formatting Dates and Numbers
----------------------------

Customizing Date and Time Properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, these are the formats applied to date and time properties (read the
`date configuration options`_ in the PHP manual if you don't understand the
meaning of these formats):

* ``date``: ``Y-m-d``
* ``time``:  ``H:i:s``
* ``datetime``: ``F j, Y H:i``

These default formats can be overridden in two ways: globally for all entities
and locally for each entity property. The global ``formats`` option sets the
formats for all entities and their properties:

.. code-block:: yaml

    easy_admin:
        formats:
            date:     'd/m/Y'
            time:     'H:i'
            datetime: 'd/m/Y H:i:s'
        entities:
            # ...

The values of the ``date``, ``time`` and ``datetime`` options are passed to the
``format()`` method of the ``DateTime`` class, so you can use any of the
`date configuration options`_ defined by PHP.

Date/time formatting can also be defined in each property configuration using
the ``format`` option. This local option always overrides the global format:

.. code-block:: yaml

    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields:
                        - { property: 'dateOfBirth', format: 'j/n/Y' }
                        # ...
        # ...

Customizing Numeric Properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Numeric properties (``bigint``, ``integer``, ``smallint``, ``decimal``,
``float``) are formatted by default according to the locale of your Symfony
application. This formatting can be overridden globally for all entities or
locally for each property.

The global ``formats`` option applies the same formatting for all entities:

.. code-block:: yaml

    easy_admin:
        formats:
            # ...
            number: '%.2f'
        entities:
            # ...

In this case, the value of the ``number`` option is passed to the ``sprintf()``
function, so you can use any of the `PHP format specifiers`_.

Numeric properties can also define their formatting using the ``format``
option. This local option always overrides the global format:

.. code-block:: yaml

    easy_admin:
        entities:
            Product:
                class: AppBundle\Entity\Product
                list:
                    fields:
                        - { property: 'serialNumber', format: '%010s' }
                        - { property: 'margin', format: '%01.2f' }
                        # ...
        # ...

Virtual Properties
------------------

Sometimes, it's useful to display values which are not entity properties. For
example, if your ``Customer`` entity defines the ``firstName`` and ``lastName``
properties, you may want to display a column called ``Name`` with both values
merged. These are called *virtual properties* because they don't really exist as
Doctrine entity properties.

First add the virtual property to the entity configuration as any other property:

.. code-block:: yaml

    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    # 'name' doesn't exist as a Doctrine entity property
                    fields: ['id', 'name', 'phone', 'email']
        # ...

Now, if you reload the backend, you'll see that the virtual property only
displays ``Inaccessible`` as its value. The reason is that ``name`` does not
match any of the entity's properties. To fix this issue, add a new public method
in your entity called ``getName()``:

.. code-block:: php

    use Doctrine\ORM\Mapping as ORM;

    /** @ORM\Entity */
    class Customer
    {
        // ...

        public function getName()
        {
            return $this->getFirstName().' '.$this->getLastName();
        }
    }

That's it. Reload your backend and now you'll see the value of this virtual
property.

.. note::

    The values or virtual properties are get using the `PropertyAccess component`_
    from Symfony, which requires to follow a strict syntax for getter names:
    ``get`` + camelized version of the property name. Example: ``name`` ->
    ``getName()``; ``firstName`` -> ``getFirstName()``; ``first_and_last_name`` ->
    ``getFirstAndLastName()``.

By default, virtual properties are displayed as text contents. If your virtual
property is a *boolean* value or a date, use the ``type`` option to set a more
appropriate data type:

.. code-block:: yaml

    # in this example, the virtual properties 'is_eligible' and 'last_contact' define
    # their 'type' option to avoid displaying them as regular text contents
    easy_admin:
        entities:
            Customer:
                class: AppBundle\Entity\Customer
                list:
                    fields:
                        - 'id'
                        - { property: 'is_eligible',  type: 'boolean' }
                        - { property: 'last_contact', type: 'datetime' }
        # ...

The main limitation of virtual properties is that you cannot sort listings
using these fields.

Sorting Entity Listings
-----------------------

By default the ``list`` and ``search`` views sort the rows in descending order
according to the value of the primary key. You can sort by any other entity
property using the ``sort`` configuration option:

.. code-block:: yaml

    # app/config/config.yml
    easy_admin:
        entities:
            User:
                # ...
                list:
                    # if the sort order is not specified, 'DESC' is used
                    sort: 'createdAt'
                search:
                    # use an array to also define the sorting direction
                    sort: ['createdAt', 'ASC']

            Purchase:
                # ...
                # the 'sort' option supports Doctrine associations up to one level
                # (e.g. 'sort: user.name' works but 'sort: user.group.name' won't work)
                list:
                    sort: 'user.name'
                search:
                    sort: ['user.name', 'ASC']

The ``sort`` option of each entity is only used as the default content sorting. If
the query string includes the optional ``sortField`` and ``sortDirection``
parameters, their values override this ``sort`` option. This happens for example
when defining a different sorting in a custom menu and when clicking on the
listings columns to reorder the displayed contents.

Filtering Entities
------------------

A common need for backends is to filter the entities included in listings (for
example: don't display expired offers, display only clients that spend more than
a given amount, etc.) You can achieve this with the features explained later in
this chapter to modify the behavior of the ``list``, ``search`` and ``show`` views.

However, for simple filters it's more convenient to use the ``dql_filter`` option,
which defines the conditions passed to the ``WHERE`` clause of the Doctrine query
used to get the entities displayed in the ``list`` and ``search`` views.

The following example manages the same ``User`` entity in two different ways using
a basic filter to differentiate each type of user:

.. code-block:: yaml

    easy_admin:
        entities:
            VipCustomers:
                class: AppBundle\Entity\User
                list:
                    dql_filter: 'entity.budget > 100000'
            RegularCustomers:
                class: AppBundle\Entity\User
                list:
                    dql_filter: 'entity.budget <= 100000'

The Doctrine DQL expression defined in the ``dql_filter`` option must always use
``entity`` as the name of the entity, regardless of your actual entity name.

Since this is a regular YAML configuration file, you can also include container
parameters inside the filter to use different values depending on the environment
or even dynamic values:

.. code-block:: yaml

    easy_admin:
        entities:
            VipCustomers:
                class: AppBundle\Entity\User
                list:
                    dql_filter: 'entity.budget > %customers.budget_threshold%'
            # ...

The value of the ``dql_filter`` can combine several conditions (in fact, you can
put anything that is considered valid as a ``WHERE`` clause in a Doctrine query):

.. code-block:: yaml

    easy_admin:
        entities:
            UrgentIssues:
                class: AppBundle\Entity\Issue
                list:
                    dql_filter: "entity.label = 'CRITICAL' OR entity.priority > 4"
            ImportantIssues:
                class: AppBundle\Entity\Issue
                list:
                    dql_filter: "entity.priority > 2 AND entity.numComments > 10"
            AllIssues:
                class: AppBundle\Entity\Issue

.. note::

    By default the ``dql_filter`` option from the ``list`` view is also used in the
    ``search`` view. If you prefer to apply different filters, define the
    ``dql_filter`` option explicitly for the ``search`` view:

    .. code-block:: yaml

        easy_admin:
            entities:
                Issues:
                    class: AppBundle\Entity\Issue
                    list:
                        dql_filter: "LOWER(entity.title) LIKE '%%issue%%'"
                    search:
                        # defining a different condition than 'list'
                        dql_filter: "entity.status != 'DELETED'"
                        # using an empty value to not apply any condition when searching
                        # elements (this prevents inheriting the 'dql_filter' value defined in 'list')
                        dql_filter: ''

.. tip::

    Combine the ``dql_filter`` option with a custom menu (as explained in the next
    chapters) to improve the navigation of the backend.

Property Types Defined by EasyAdmin
-----------------------------------

In addition to the Doctrine data types, properties can use any of the following
data types defined by EasyAdmin.

Email Data Type
{'fraction_non_alphanumeric': 0.11224740646049462, 'fraction_numerical': 0.001671665273612272, 'mean_word_length': 2.3741705374917053, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 29, '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': '2356238', 'n_tokens_mistral': 10407, 'n_tokens_neox': 9870, 'n_words': 4676}