123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198 |
- 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
- # app/config/config.yml
- 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
- show_compare: SonataAdminBundle:CRUD:show_compare.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
- tab_menu_template: SonataAdminBundle:Core:tab_menu_template.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
- action_create: SonataAdminBundle:CRUD:dashboard__action_create.html.twig
- button_acl: SonataAdminBundle:Button:acl_button.html.twig
- button_create: SonataAdminBundle:Button:create_button.html.twig
- button_edit: SonataAdminBundle:Button:edit_button.html.twig
- button_history: SonataAdminBundle:Button:history_button.html.twig
- button_list: SonataAdminBundle:Button:list_button.html.twig
- button_show: SonataAdminBundle:Button:show_button.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
- <service id="app.admin.post" class="AppBundle\Admin\PostAdmin">
- <tag name="sonata.admin" manager_type="orm" group="Content" label="Post" />
- <argument />
- <argument>AppBundle\Entity\Post</argument>
- <argument />
- <call method="setTemplate">
- <argument>edit</argument>
- <argument>AppBundle:PostAdmin:edit.html.twig</argument>
- </call>
- </service>
- .. code-block:: yaml
- services:
- app.admin.post:
- class: AppBundle\Admin\PostAdmin
- tags:
- - { name: sonata.admin, manager_type: orm, group: "Content", label: "Post" }
- arguments:
- - ~
- - AppBundle\Entity\Post
- - ~
- calls:
- - [ setTemplate, [edit, AppBundle:PostAdmin:edit.html.twig]]
- public: true
- .. 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.
|