templates.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
  1. Templates
  2. =========
  3. ``SonataAdminBundle`` comes with a significant amount of ``twig`` files used to display the
  4. different parts of each ``Admin`` action's page. If you read the ``Templates`` part of the
  5. :doc:`architecture` section of this guide, you should know by now how these are organized in
  6. the ``views`` folder. If you haven't, now would be a good time to do it.
  7. Besides these, some other views files are included from the storage layer. As their content and
  8. structure are specific to each implementation, they are not discussed here, but it's important
  9. that you keep in mind that they exist and are as relevant as the view files included
  10. directly in ``SonataAdminBundle``.
  11. Global Templates
  12. ----------------
  13. ``SonataAdminBundle`` views are implemented using ``twig`` files, and take full advantage of its
  14. inheritance capabilities. As such, even the most simple page is actually rendered using many
  15. different ``twig`` files. At the end of that ``twig`` inheritance hierarchy is always one of two files:
  16. * layout: SonataAdminBundle::standard_layout.html.twig
  17. * ajax: SonataAdminBundle::ajax_layout.html.twig
  18. As you might have guessed from their names, the first is used in 'standard' request and the other
  19. for AJAX calls. The ``SonataAdminBundle::standard_layout.html.twig`` contains several elements which
  20. exist across the whole page, like the logo, title, upper menu and menu. It also includes the base CSS
  21. and JavaScript files and libraries used across the whole administration section. The AJAX template
  22. doesn't include any of these elements.
  23. Dashboard Template
  24. ------------------
  25. The template used for rendering the dashboard can also be configured. See the :doc:`dashboard` page
  26. for more information
  27. CRUDController Actions Templates
  28. --------------------------------
  29. As seen before, the ``CRUDController`` has several actions that allow you to manipulate your
  30. model instances. Each of those actions uses a specific template file to render its content.
  31. By default, ``SonataAdminBundle`` uses the following templates for their matching action:
  32. * ``list`` : SonataAdminBundle:CRUD:list.html.twig
  33. * ``show`` : SonataAdminBundle:CRUD:show.html.twig
  34. * ``edit`` : SonataAdminBundle:CRUD:edit.html.twig
  35. * ``history`` : SonataAdminBundle:CRUD:history.html.twig
  36. * ``preview`` : SonataAdminBundle:CRUD:preview.html.twig
  37. * ``delete`` : SonataAdminBundle:CRUD:delete.html.twig
  38. * ``batch_confirmation`` : SonataAdminBundle:CRUD:batch_confirmation.html.twig
  39. * ``acl`` : SonataAdminBundle:CRUD:acl.html.twig
  40. Notice that all these templates extend other templates, and some do only that. This inheritance
  41. architecture is designed to help you easily make customizations by extending these templates
  42. in your own bundle, rather than rewriting everything.
  43. If you look closely, all of these templates ultimately extend the ``base_template`` variable that's
  44. passed from the controller. This variable will always take the value of one of the above mentioned
  45. global templates, and this is how changes made to those files affect all the ``SonataAdminBundle``
  46. interface.
  47. Row Templates
  48. -------------
  49. It is possible to completely change how each row of results is rendered in the
  50. list view, by customizing the ``inner_list_row`` and ``base_list_field`` templates.
  51. For more information about this, see the :doc:`../cookbook/recipe_row_templates`
  52. cookbook entry.
  53. Other Templates
  54. ---------------
  55. There are several other templates that can be customized, enabling you to fine-tune
  56. ``SonataAdminBundle``:
  57. * ``user_block`` : customizes the Twig block rendered by default in the top right
  58. corner of the admin interface, containing user information.
  59. Empty by default, see ``SonataUserBundle`` for a real example.
  60. * ``add_block`` : customizes the Twig block rendered by default in the top right
  61. corner of the admin interface, providing quick access to create operations on
  62. available admin classes.
  63. * ``history_revision_timestamp:`` customizes the way timestamps are rendered when
  64. using history related actions.
  65. * ``action`` : a generic template you can use for your custom actions
  66. * ``short_object_description`` : used by the ``getShortObjectDescriptionAction``
  67. action from the ``HelperController``, this template displays a small
  68. description of a model instance.
  69. * ``list_block`` : the template used to render the dashboard's admin mapping lists.
  70. More info on the :doc:`dashboard` page.
  71. * batch: template used to render the checkboxes that precede each instance on list views.
  72. * ``select`` : when loading list views as part of sonata_admin form types, this
  73. template is used to create a button that allows you to select the matching line.
  74. * ``pager_links`` : renders the list of pages displayed at the end of the list view
  75. (when more than one page exists)
  76. * ``pager_results`` : renders the dropdown that lets you choose the number of
  77. elements per page on list views
  78. Configuring templates
  79. ---------------------
  80. Like said before, the main goal of this template structure is to make it easy for you
  81. to customize the ones you need. You can simply extend the ones you want in your own bundle,
  82. and tell ``SonataAdminBundle`` to use your templates instead of the default ones. You can do so
  83. in several ways.
  84. You can specify your templates in the config.yml file, like so:
  85. .. configuration-block::
  86. .. code-block:: yaml
  87. # app/config/config.yml
  88. sonata_admin:
  89. templates:
  90. layout: SonataAdminBundle::standard_layout.html.twig
  91. ajax: SonataAdminBundle::ajax_layout.html.twig
  92. list: SonataAdminBundle:CRUD:list.html.twig
  93. show: SonataAdminBundle:CRUD:show.html.twig
  94. show_compare: SonataAdminBundle:CRUD:show_compare.html.twig
  95. edit: SonataAdminBundle:CRUD:edit.html.twig
  96. history: SonataAdminBundle:CRUD:history.html.twig
  97. preview: SonataAdminBundle:CRUD:preview.html.twig
  98. delete: SonataAdminBundle:CRUD:delete.html.twig
  99. batch: SonataAdminBundle:CRUD:list__batch.html.twig
  100. acl: SonataAdminBundle:CRUD:acl.html.twig
  101. action: SonataAdminBundle:CRUD:action.html.twig
  102. select: SonataAdminBundle:CRUD:list__select.html.twig
  103. filter: SonataAdminBundle:Form:filter_admin_fields.html.twig
  104. dashboard: SonataAdminBundle:Core:dashboard.html.twig
  105. search: SonataAdminBundle:Core:search.html.twig
  106. batch_confirmation: SonataAdminBundle:CRUD:batch_confirmation.html.twig
  107. inner_list_row: SonataAdminBundle:CRUD:list_inner_row.html.twig
  108. base_list_field: SonataAdminBundle:CRUD:base_list_field.html.twig
  109. list_block: SonataAdminBundle:Block:block_admin_list.html.twig
  110. user_block: SonataAdminBundle:Core:user_block.html.twig
  111. add_block: SonataAdminBundle:Core:add_block.html.twig
  112. pager_links: SonataAdminBundle:Pager:links.html.twig
  113. pager_results: SonataAdminBundle:Pager:results.html.twig
  114. tab_menu_template: SonataAdminBundle:Core:tab_menu_template.html.twig
  115. history_revision_timestamp: SonataAdminBundle:CRUD:history_revision_timestamp.html.twig
  116. short_object_description: SonataAdminBundle:Helper:short-object-description.html.twig
  117. search_result_block: SonataAdminBundle:Block:block_search_result.html.twig
  118. action_create: SonataAdminBundle:CRUD:dashboard__action_create.html.twig
  119. button_acl: SonataAdminBundle:Button:acl_button.html.twig
  120. button_create: SonataAdminBundle:Button:create_button.html.twig
  121. button_edit: SonataAdminBundle:Button:edit_button.html.twig
  122. button_history: SonataAdminBundle:Button:history_button.html.twig
  123. button_list: SonataAdminBundle:Button:list_button.html.twig
  124. button_show: SonataAdminBundle:Button:show_button.html.twig
  125. Notice that this is a global change, meaning it will affect all model mappings automatically,
  126. both for ``Admin`` mappings defined by you and by other bundles.
  127. If you wish, you can specify custom templates on a per ``Admin`` mapping basis. Internally,
  128. the ``CRUDController`` fetches this information from the ``Admin`` class instance, so you can
  129. specify the templates to use in the ``Admin`` service definition:
  130. .. configuration-block::
  131. .. code-block:: xml
  132. <service id="app.admin.post" class="AppBundle\Admin\PostAdmin">
  133. <tag name="sonata.admin" manager_type="orm" group="Content" label="Post" />
  134. <argument />
  135. <argument>AppBundle\Entity\Post</argument>
  136. <argument />
  137. <call method="setTemplate">
  138. <argument>edit</argument>
  139. <argument>AppBundle:PostAdmin:edit.html.twig</argument>
  140. </call>
  141. </service>
  142. .. code-block:: yaml
  143. services:
  144. app.admin.post:
  145. class: AppBundle\Admin\PostAdmin
  146. tags:
  147. - { name: sonata.admin, manager_type: orm, group: "Content", label: "Post" }
  148. arguments:
  149. - ~
  150. - AppBundle\Entity\Post
  151. - ~
  152. calls:
  153. - [ setTemplate, [edit, AppBundle:PostAdmin:edit.html.twig]]
  154. public: true
  155. .. note::
  156. A ``setTemplates(array $templates)`` (notice the plural) function also exists, that allows
  157. you to set multiple templates at once. Notice that, if used outside of the service definition
  158. context, ``setTemplates(array $templates)`` will replace the whole template list for that
  159. ``Admin`` class, meaning you have to explicitly pass the full template list in the
  160. ``$templates`` argument.
  161. Changes made using the ``setTemplate()`` and ``setTemplates()`` functions override the customizations
  162. made in the configuration file, so you can specify a global custom template and then override that
  163. customization on a specific ``Admin`` class.