recipe_knp_menu.rst 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293
  1. KnpMenu
  2. =======
  3. The admin comes with `KnpMenu`_ integration.
  4. It integrates a menu with the KnpMenu library. This menu can be a SonataAdmin service, a menu created with a Knp menu provider or a route of a custom controller.
  5. Add a custom controller entry in the menu
  6. -----------------------------------------
  7. To add a custom controller entry in the admin menu:
  8. Create your controller:
  9. .. code-block:: php
  10. class BlogController
  11. {
  12. /**
  13. * @Route("/blog", name="blog_home")
  14. */
  15. public function blogAction()
  16. {
  17. // ...
  18. }
  19. /**
  20. * @Route("/blog/article/{articleId}", name="blog_article")
  21. */
  22. public function ArticleAction($articleId)
  23. {
  24. // ...
  25. }
  26. }
  27. Add the controller route as an item of the menu:
  28. .. configuration-block::
  29. .. code-block:: yaml
  30. # app/config/config.yml
  31. sonata_admin:
  32. dashboard:
  33. groups:
  34. news:
  35. label: ~
  36. label_catalogue: ~
  37. items:
  38. - sonata.news.admin.post
  39. - route: blog_home
  40. label: Blog
  41. - route: blog_article
  42. route_params: { articleId: 3 }
  43. label: Article
  44. If you want to show your route to user with different roles, you can configure this for each route. If this is not set,
  45. group roles will be checked.
  46. .. configuration-block::
  47. .. code-block:: yaml
  48. # app/config/config.yml
  49. sonata_admin:
  50. dashboard:
  51. groups:
  52. news:
  53. label: ~
  54. label_catalogue: ~
  55. items:
  56. - sonata.news.admin.post
  57. - route: blog_home
  58. label: Blog
  59. roles: [ ROLE_FOO, ROLE_BAR ]
  60. - route: blog_article
  61. route_params: { articleId: 3 }
  62. label: Article
  63. roles: [ ROLE_ADMIN, ROLE_SONATA_ADMIN]
  64. You can also override the template of knp_menu used by sonata. The default one is `SonataAdminBundle:Menu:sonata_menu.html.twig`:
  65. .. configuration-block::
  66. .. code-block:: yaml
  67. # app/config/config.yml
  68. sonata_admin:
  69. templates:
  70. knp_menu_template: ApplicationAdminBundle:Menu:custom_knp_menu.html.twig
  71. And voilà, now you have a menu group which contains a link to a sonata admin via its id, to your blog and to a specific article.
  72. Using a menu provider
  73. ---------------------
  74. As seen above, the main way to declare your menu is by declaring items in your sonata admin config file. In some case you may have to create a more complex menu depending on your business logic. This is possible by using a menu provider to populate a whole menu group. This is done with the ``provider`` config value.
  75. The following configuration uses a menu provider to populate the menu group ``my_group``:
  76. .. configuration-block::
  77. .. code-block:: yaml
  78. # app/config/config.yml
  79. sonata_admin:
  80. dashboard:
  81. groups:
  82. my_group:
  83. provider: 'MyBundle:MyMenuProvider:getMyMenu'
  84. icon: '<i class="fa fa-edit"></i>'
  85. With KnpMenuBundle you can create a custom menu by using a builder class or by declaring it as a service. Please see the `Knp documentation`_ for further information.
  86. In sonata, whatever the implementation you choose, you only have to provide the menu alias to the provider config key:
  87. * If you are using a builder class, your menu alias should be something like ``MyBundle:MyMenuProvider:getMyMenu``.
  88. * If you are using a service, your menu alias is the alias set in the ``knp_menu.menu`` tag. In the following example this is ``my_menu_alias``:
  89. .. configuration-block::
  90. .. code-block:: xml
  91. <service id="my_menu_provider" class="MyBundle/MyDirectory/MyMenuProvider">
  92. <tag name="knp_menu.menu" alias="my_menu_alias" />
  93. </service>
  94. Please note that when using the provider option, you can't set the menu label via the configuration. It is done in your custom menu.
  95. Extending the menu
  96. ------------------
  97. You can modify the menu via events easily. You can register as many listeners as you want for the event with name ``sonata.admin.event.configure.menu.sidebar``:
  98. .. code-block:: php
  99. <?php
  100. // src/AppBundle/EventListener/MenuBuilderListener.php
  101. namespace AppBundle\EventListener;
  102. use Sonata\AdminBundle\Event\ConfigureMenuEvent;
  103. class MenuBuilderListener
  104. {
  105. public function addMenuItems(ConfigureMenuEvent $event)
  106. {
  107. $menu = $event->getMenu();
  108. $child = $menu->addChild('reports', [
  109. 'label' => 'Daily and monthly reports',
  110. 'route' => 'app_reports_index',
  111. ])->setExtras([
  112. 'icon' => '<i class="fa fa-bar-chart"></i>',
  113. ]);
  114. }
  115. }
  116. .. configuration-block::
  117. .. code-block:: yaml
  118. # src/AppBundle/Resources/config/services.yml
  119. services:
  120. app.menu_listener:
  121. class: AppBundle\EventListener\MenuBuilderListener
  122. tags:
  123. - { name: kernel.event_listener, event: sonata.admin.event.configure.menu.sidebar, method: addMenuItems }
  124. Please see the `Using events to allow a menu to be extended`_ for further information.
  125. Hiding menu items
  126. -----------------
  127. You can modify the menu to hide some menu items. You need to add the ``show_in_dashboard`` option in
  128. your admin services or simply remove menu items from the ``sonata_admin`` dashboard group configuration:
  129. .. code-block:: yaml
  130. sonata_admin.admin.post:
  131. class: Sonata\AdminBundle\Admin\PostAdmin
  132. arguments: [~, Sonata\AdminBundle\Entity\Post, SonataAdminBundle:CRUD]
  133. tags:
  134. - {name: sonata.admin, manager_type: orm, group: admin, label: Post, show_in_dashboard: false}
  135. public: true
  136. .. code-block:: yaml
  137. # app/config/config.yml
  138. sonata_admin:
  139. dashboard:
  140. groups:
  141. news:
  142. label: ~
  143. label_catalogue: ~
  144. items:
  145. # just comment or remove the sonata.news.admin.post declaration to hide it from the menu.
  146. # - sonata.news.admin.post
  147. - route: blog_home
  148. label: Blog
  149. - sonata.news.admin.news
  150. Keeping menu group open
  151. -----------------------
  152. You can add the ``keep_open`` option to menu group to keep that group always
  153. open and ignore open/close effects:
  154. .. code-block:: yaml
  155. # app/config/config.yml
  156. sonata_admin:
  157. dashboard:
  158. groups:
  159. sonata.admin.group.content:
  160. keep_open: true
  161. label: sonata_media
  162. label_catalogue: SonataMediaBundle
  163. icon: '<i class="fa fa-image"></i>'
  164. items:
  165. - sonata.media.admin.media
  166. - sonata.media.admin.gallery
  167. .. figure:: ../images/keep_open.png
  168. :align: center
  169. :alt: The navigation side bar with a group which uses "keep_open" option
  170. Show menu item without treeview
  171. -------------------------------
  172. You can modify the menu to show menu item without treeview. You need to add option ``on_top`` in your admin services
  173. or in sonata_admin dashboard group configuration:
  174. .. code-block:: yaml
  175. sonata_admin.admin.post:
  176. class: Sonata\AdminBundle\Admin\PostAdmin
  177. arguments: [~, Sonata\AdminBundle\Entity\Post, SonataAdminBundle:CRUD]
  178. tags:
  179. - {name: sonata.admin, manager_type: orm, group: admin, label: Post, on_top: true}
  180. public: true
  181. .. code-block:: yaml
  182. # app/config/config.yml
  183. sonata_admin:
  184. dashboard:
  185. groups:
  186. news:
  187. on_top: true
  188. label: ~
  189. label_catalogue: ~
  190. items:
  191. - sonata.news.admin.post
  192. .. figure:: ../images/demo_on_top.png
  193. :align: center
  194. :alt: on_top option
  195. :width: 500
  196. In this screenshot, we add ``on_top`` option to ``Tag`` and ``Blog Post`` admin services.
  197. Your can't use this option for two or more items in the same time, for example:
  198. .. code-block:: yaml
  199. # app/config/config.yml
  200. sonata_admin:
  201. dashboard:
  202. groups:
  203. news:
  204. on_top: true
  205. label: ~
  206. label_catalogue: ~
  207. items:
  208. - sonata.news.admin.post
  209. - route: blog_home
  210. label: Blog
  211. In this case you have an exception: "You can't use ``on_top`` option with multiple same name groups".
  212. .. _KnpMenu: https://github.com/KnpLabs/KnpMenu
  213. .. _Knp documentation: http://symfony.com/doc/current/bundles/KnpMenuBundle/index.html#create-your-first-menu
  214. .. _Using events to allow a menu to be extended: http://symfony.com/doc/master/bundles/KnpMenuBundle/events.html