Templates ========= ``SonataAdminBundle`` comes with a significant amount of ``twig`` files used to display the different parts of each ``Admin`` action's page. If you read the ``Templates`` part of the :doc:`architecture` section of this guide, you should know by now how these are organized in the ``views`` folder. If you haven't, now would be a good time to do it. Besides these, some other views files are included from the storage layer. As their content and structure are specific to each implementation, they are not discussed here, but it's important that you keep in mind that they exist and are as relevant as the view files included directly in ``SonataAdminBundle``. Global Templates ---------------- ``SonataAdminBundle`` views are implemented using ``twig`` files, and take full advantage of its inheritance capabilities. As such, even the most simple page is actually rendered using many different ``twig`` files. At the end of that ``twig`` inheritance hierarchy is always one of two files: * layout: SonataAdminBundle::standard_layout.html.twig * ajax: SonataAdminBundle::ajax_layout.html.twig As you might have guessed from their names, the first is used in 'standard' request and the other for AJAX calls. The ``SonataAdminBundle::standard_layout.html.twig`` contains several elements which exist across the whole page, like the logo, title, upper menu and menu. It also includes the base CSS and JavaScript files and libraries used across the whole administration section. The AJAX template doesn't include any of these elements. Dashboard Template ------------------ The template used for rendering the dashboard can also be configured. See the :doc:`dashboard` page for more information CRUDController Actions Templates -------------------------------- As seen before, the ``CRUDController`` has several actions that allow you to manipulate your model instances. Each of those actions uses a specific template file to render its content. By default, ``SonataAdminBundle`` uses the following templates for their matching action: * list: SonataAdminBundle:CRUD:list.html.twig * show: SonataAdminBundle:CRUD:show.html.twig * edit: SonataAdminBundle:CRUD:edit.html.twig * history: SonataAdminBundle:CRUD:history.html.twig * preview: SonataAdminBundle:CRUD:preview.html.twig * delete: SonataAdminBundle:CRUD:delete.html.twig * batch_confirmation: SonataAdminBundle:CRUD:batch_confirmation.html.twig * acl: SonataAdminBundle:CRUD:acl.html.twig Notice that all these templates extend other templates, and some do only that. This inheritance architecture is designed to help you easily make customizations by extending these templates in your own bundle, rather than rewriting everything. If you look closely, all of these templates ultimately extend the ``base_template`` variable that's passed from the controller. This variable will always take the value of one of the above mentioned global templates, and this is how changes made to those files affect all the ``SonataAdminBundle`` interface. Row Templates ------------- It is possible to completely change how each row of results is rendered in the list view, by customizing the ``inner_list_row`` and ``base_list_field`` templates. For more information about this, see the :doc:`../cookbook/recipe_row_templates` cookbook entry. Other Templates --------------- There are several other templates that can be customized, enabling you to fine-tune ``SonataAdminBundle``: * user_block: customizes the Twig block rendered by default in the top right corner of the admin interface, containing user information. Empty by default, see ``SonataUserBundle`` for a real example. * add_block: customizes the Twig block rendered by default in the top right corner of the admin interface, providing quick access to create operations on available admin classes. * history_revision_timestamp: customizes the way timestamps are rendered when using history related actions. * action: a generic template you can use for your custom actions * short_object_description: used by the ``getShortObjectDescriptionAction`` action from the ``HelperController``, this template displays a small description of a model instance. * list_block: the template used to render the dashboard's admin mapping lists. More info on the :doc:`dashboard` page. * batch: template used to render the checkboxes that precede each instance on list views. * select: when loading list views as part of sonata_admin form types, this template is used to create a button that allows you to select the matching line. * pager_links: renders the list of pages displayed at the end of the list view (when more than one page exists) * pager_results: renders the dropdown that lets you choose the number of elements per page on list views Configuring templates --------------------- Like said before, the main goal of this template structure is to make it easy for you to customize the ones you need. You can simply extend the ones you want in your own bundle, and tell ``SonataAdminBundle`` to use your templates instead of the default ones. You can do so in several ways. You can specify your templates in the config.yml file, like so: .. configuration-block:: .. code-block:: yaml sonata_admin: templates: layout: SonataAdminBundle::standard_layout.html.twig ajax: SonataAdminBundle::ajax_layout.html.twig list: SonataAdminBundle:CRUD:list.html.twig show: SonataAdminBundle:CRUD:show.html.twig edit: SonataAdminBundle:CRUD:edit.html.twig history: SonataAdminBundle:CRUD:history.html.twig preview: SonataAdminBundle:CRUD:preview.html.twig delete: SonataAdminBundle:CRUD:delete.html.twig batch: SonataAdminBundle:CRUD:list__batch.html.twig acl: SonataAdminBundle:CRUD:acl.html.twig action: SonataAdminBundle:CRUD:action.html.twig select: SonataAdminBundle:CRUD:list__select.html.twig filter: SonataAdminBundle:Form:filter_admin_fields.html.twig dashboard: SonataAdminBundle:Core:dashboard.html.twig search: SonataAdminBundle:Core:search.html.twig batch_confirmation: SonataAdminBundle:CRUD:batch_confirmation.html.twig inner_list_row: SonataAdminBundle:CRUD:list_inner_row.html.twig base_list_field: SonataAdminBundle:CRUD:base_list_field.html.twig list_block: SonataAdminBundle:Block:block_admin_list.html.twig user_block: SonataAdminBundle:Core:user_block.html.twig add_block: SonataAdminBundle:Core:add_block.html.twig pager_links: SonataAdminBundle:Pager:links.html.twig pager_results: SonataAdminBundle:Pager:results.html.twig history_revision_timestamp: SonataAdminBundle:CRUD:history_revision_timestamp.html.twig short_object_description: SonataAdminBundle:Helper:short-object-description.html.twig search_result_block: SonataAdminBundle:Block:block_search_result.html.twig Notice that this is a global change, meaning it will affect all model mappings automatically, both for ``Admin`` mappings defined by you and by other bundles. If you wish, you can specify custom templates on a per ``Admin`` mapping basis. Internally, the ``CRUDController`` fetches this information from the ``Admin`` class instance, so you can specify the templates to use in the ``Admin`` service definition: .. configuration-block:: .. code-block:: xml Acme\DemoBundle\Entity\Post edit AcmeDemoBundle:PostAdmin:edit.html.twig .. code-block:: yaml services: sonata.admin.post: class: Acme\DemoBundle\Admin\PostAdmin tags: - { name: sonata.admin, manager_type: orm, group: "Content", label: "Post" } arguments: - ~ - Acme\DemoBundle\Entity\Post - ~ calls: - [ setTemplate, [edit, AcmeDemoBundle:PostAdmin:edit.html.twig]] .. note:: A ``setTemplates(array $templates)`` (notice the plural) function also exists, that allows you to set multiple templates at once. Notice that, if used outside of the service definition context, ``setTemplates(array $templates)`` will replace the whole template list for that ``Admin`` class, meaning you have to explicitly pass the full template list in the ``$templates`` argument. Changes made using the ``setTemplate()`` and ``setTemplates()`` functions override the customizations made in the configuration file, so you can specify a global custom template and then override that customization on a specific ``Admin`` class.