Documentation » Admin

10. Creating and Editing objects »

« 8. Routing

9. The List View


This document is a stub representing a new work in progress. If you’re reading this you can help contribute, no matter what your experience level with Sonata is. Check out the issues on GitHub for more information about how to get involved.

This document will cover the List view which you use to browse the objects in your system. It will cover configuration of the list itself and the filters you can use to control what’s visible.

9.1. Basic configuration

SonataAdmin Options that may affect the list view:

        list:                       SonataAdminBundle:CRUD:list.html.twig
        action:                     SonataAdminBundle:CRUD:action.html.twig
        select:                     SonataAdminBundle:CRUD:list__select.html.twig
        list_block:                 SonataAdminBundle:Block:block_admin_list.html.twig
        short_object_description:   SonataAdminBundle:Helper:short-object-description.html.twig
        batch:                      SonataAdminBundle:CRUD:list__batch.html.twig
        inner_list_row:             SonataAdminBundle:CRUD:list_inner_row.html.twig
        base_list_field:            SonataAdminBundle:CRUD:base_list_field.html.twig
        pager_links:                SonataAdminBundle:Pager:links.html.twig
        pager_results:              SonataAdminBundle:Pager:results.html.twig

To do:

  • a note about Routes and how disabling them disables the related action
  • adding custom columns

9.2. Customizing the fields displayed on the list page

You can customize the columns displayed on the list through the configureListFields method:


// Example taken from Sonata E-Commerce Product Admin

public function configureListFields(ListMapper $list)
        // addIdentifier allows to specify that this column will provide a link to the entity's edition

        // You may specify the field type directly as the second argument instead of in the options
        ->add('isVariation', 'boolean')

        // The type can be guessed as well
        ->add('enabled', null, array('editable' => true))

        // We can add options to the field depending on the type
        ->add('price', 'currency', array('currency' => $this->currencyDetector->getCurrency()->getLabel()))

        // Here we specify which method is used to render the label
        ->add('productCategories', null, array('associated_tostring' => 'getCategory'))
        ->add('productCollections', null, array('associated_tostring' => 'getCollection'))

        // You may also use dotted-notation to access specific properties of a relation to the entity

        // You may also specify the actions you want to be displayed in the list
        ->add('_action', 'actions', array(
            'actions' => array(
                'show' => array(),
                'edit' => array(),
                'delete' => array(),


9.2.1. Options


  • (m) stands for mandatory
  • (o) stands for optional
  • type (m): defines the field type - mandatory for the field description itself but will try to detect the type automatically if not specified
  • template (o): the template used to render the field
  • label (o): the name used for the column’s title
  • link_parameters (o): add link parameter to the related Admin class when the Admin::generateUrl is called
  • code (o): the method name to retrieve the related value
  • associated_tostring (o): (deprecated, use associated_property option) the method to retrieve the “string” representation of the collection element.
  • associated_property (o): property path to retrieve the “string” representation of the collection element.
  • identifier (o): if set to true a link appears on the value to edit the element

9.2.2. Available types and associated options


(m) means that option is mandatory

Type Options Description
actions actions List of available actions
batch   Renders a checkbox
select   Renders a select box
array   Displays an array
boolean ajax_hidden Yes/No; ajax_hidden allows to hide list field during an AJAX context.
boolean editable Yes/No; editable allows to edit directly from the list if authorized.
choice choices Possible choices
multiple Is it a multiple choice option? Defaults to false.
delimiter Separator of values if multiple.
catalogue Translation catalogue.
currency currency (m) A currency string (EUR or USD for instance).
date format A format understandable by Twig’s date function.
datetime format A format understandable by Twig’s date function.
percent   Renders value as a percentage.
string   Renders a simple string.
time   Renders a datetime’s time with format H:i:s.
trans catalogue Translates the value with catalogue catalogue if defined.
url url Adds a link with url url to the displayed value




Give a route to generate the url

Route name

Route parameters

hide_protocol Hide http:// or https:// (default false)

If you have the SonataDoctrineORMAdminBundle installed, you have access to more field types, see SonataDoctrineORMAdminBundle Documentation.

9.3. Customizing the query used to generate the list

You can customize the list query thanks to the createQuery method.


public function createQuery($context = 'list')
    $query = parent::createQuery($context);
        $query->expr()->eq($query->getRootAliases()[0] . '.my_field', ':my_param')
    $query->setParameter('my_param', 'my_value');
    return $query;

9.4. Customizing the sort order

9.4.1. Configure the default ordering in the list view

Configuring the default ordering column can simply be achieved by overriding the datagridValues array property. All three keys _page, _sort_order and _sort_by can be omitted.


use Sonata\AdminBundle\Admin\Admin;

class PageAdmin extends Admin
    // ...

     * Default Datagrid values
     * @var array
    protected $datagridValues = array(
        '_page' => 1,            // display the first page (default = 1)
        '_sort_order' => 'DESC', // reverse order (default = 'ASC')
        '_sort_by' => 'updated'  // name of the ordered field
                                 // (default = the model's id field, if any)

        // the '_sort_by' key can be of the form 'mySubModel.mySubSubModel.myField'.

    // ...

To do:

  • how to sort by multiple fields (this might be a separate recipe?)

9.5. Filters

To do:

  • basic filter configuration and options
  • how to set default filter values
  • targeting submodel fields using dot-separated notation
  • advanced filter options (global_search)

Found a typo? Something is wrong in this documentation? Just fork and edit it!