action_show.rst 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. The Show action
  2. ===============
  3. .. note::
  4. This document is a stub representing a new work in progress. If you're reading
  5. this you can help contribute, **no matter what your experience level with Sonata
  6. is**. Check out the `issues on GitHub`_ for more information about how to get involved.
  7. This document will cover the Show action and related configuration options.
  8. Basic configuration
  9. -------------------
  10. .. note::
  11. **TODO**:
  12. * a note about Routes and how disabling them disables the related action
  13. * a note about lifecycle events triggered by delete?
  14. * options available when adding general fields, inc custom templates
  15. * targeting submodel fields using dot-separated notation
  16. * (Note, if this is very similar to the form documentation it can be combined)
  17. Group options
  18. ~~~~~~~~~~~~~
  19. When adding a group to your show page, you may specify some options for the group itself.
  20. - ``collapsed``: unused at the moment
  21. - ``class``: the class for your group in the admin; by default, the value is set to ``col-md-12``.
  22. - ``fields``: the fields in your group (you should NOT override this unless you know what you're doing).
  23. - ``box_class``: the class for your group box in the admin; by default, the value is set to ``box box-primary``.
  24. - ``description``: to complete
  25. - ``translation_domain``: to complete
  26. To specify options, do as follow:
  27. .. code-block:: php
  28. <?php
  29. // src/AppBundle/Admin/PersonAdmin.php
  30. use Sonata\AdminBundle\Admin\AbstractAdmin;
  31. use Sonata\AdminBundle\Show\ShowMapper;
  32. class PersonAdmin extends AbstractAdmin
  33. {
  34. public function configureShowFields(ShowMapper $showMapper)
  35. {
  36. $showMapper
  37. ->tab('General') // the tab call is optional
  38. ->with('Addresses', array(
  39. 'class' => 'col-md-8',
  40. 'box_class' => 'box box-solid box-danger',
  41. 'description' => 'Lorem ipsum',
  42. ))
  43. ->add('title')
  44. // ...
  45. ->end()
  46. ->end()
  47. ;
  48. }
  49. }
  50. When extending an existing Admin, you may want to remove some fields, groups or tabs.
  51. Here is an example of how to achieve this :
  52. .. code-block:: php
  53. <?php
  54. // src/AppBundle/Admin/PersonAdmin.php
  55. use Sonata\AdminBundle\Show\ShowMapper;
  56. class PersonAdmin extends ParentAdmin
  57. {
  58. public function configureShowFields(ShowMapper $showMapper)
  59. {
  60. parent::configureShowFields($showMapper);
  61. // remove just one field
  62. $showMapper->remove('field_to_remove');
  63. // remove a group from the "default" tab
  64. $showMapper->removeGroup('GroupToRemove1');
  65. // remove a group from a specific tab
  66. $showMapper->removeGroup('GroupToRemove2', 'Tab2');
  67. // remove a group from a specific tab and also remove the tab if it ends up being empty
  68. $showMapper->removeGroup('GroupToRemove3', 'Tab3', true);
  69. }
  70. }
  71. Customising the query used to show the object from within your Admin class
  72. --------------------------------------------------------------------------
  73. Setting up a showAction is pretty much the same as a form, which we did in the initial setup.
  74. It is actually a bit easier, because we are only concerned with displaying information.
  75. Smile, the hard part is already done.
  76. The following is a working example of a ShowAction
  77. .. code-block:: php
  78. <?php
  79. // src/AppBundle/Admin/PostAdmin.php
  80. use Sonata\AdminBundle\Show\ShowMapper;
  81. class ClientAdmin extends AbstractAdmin
  82. {
  83. protected function configureShowFields(ShowMapper $showMapper)
  84. {
  85. // here we set the fields of the ShowMapper variable,
  86. // $showMapper (but this can be called anything)
  87. $showMapper
  88. // The default option is to just display the
  89. // value as text (for boolean this will be 1 or 0)
  90. ->add('name')
  91. ->add('phone')
  92. ->add('email')
  93. // The boolean option is actually very cool
  94. // true shows a check mark and the 'yes' label
  95. // false shows a check mark and the 'no' label
  96. ->add('dateCafe', 'boolean')
  97. ->add('datePub', 'boolean')
  98. ->add('dateClub', 'boolean')
  99. ;
  100. }
  101. }
  102. .. tip::
  103. To customize the displayed label of a show field you can use the ``label`` option:
  104. .. code-block:: php
  105. $showMapper->add('name', null, array('label' => 'UserName'));
  106. Setting this option to ``false`` will make the label empty.
  107. Setting up a custom show template (very useful)
  108. ===============================================
  109. The first thing you need to do is define it in app/config/config/yml:
  110. .. configuration-block::
  111. .. code-block:: yaml
  112. sonata_admin:
  113. title: Acme
  114. title_logo: img/logo_small.png
  115. templates:
  116. show: AppBundle:Admin:Display_Client.html.twig
  117. Once you have defined this, Sonata Admin looks for it in the following location:
  118. ``src/AppBundle/Resources/views/Admin/Display_Client.html.twig``
  119. Now that you have told Sonata Admin where to find the template, it is time to put one in there.
  120. The recommended way to start is to copy the default template, and paste it into its new home.
  121. This ensures that you can update Sonata Admin and keep all of your hard work.
  122. The original template can be found in the following location:
  123. ``vendor/sonata-project/admin-bundle/Resources/views/CRUD/base_show.html.twig``
  124. Now that you have a copy of the default template, check to make sure it works.
  125. That's it, now go code.
  126. .. _`issues on GitHub`: https://github.com/sonata-project/SonataAdminBundle/issues/1519