dashboard.rst 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419
  1. Dashboard
  2. =========
  3. The Dashboard is the main landing page. By default it lists your mapped models,
  4. as defined by your ``Admin`` services. This is useful to help you start using
  5. ``SonataAdminBundle`` right away, but there is much more that you can do to take
  6. advantage of the Dashboard.
  7. The Dashboard is, by default, available at ``/admin/dashboard``, which is handled by
  8. the ``SonataAdminBundle:Core:dashboard`` controller action. The default view file for
  9. this action is ``SonataAdminBundle:Core:dashboard.html.twig``, but you can change
  10. this in your ``config.yml``:
  11. .. configuration-block::
  12. .. code-block:: yaml
  13. # app/config/config.yml
  14. sonata_admin:
  15. templates:
  16. dashboard: SonataAdminBundle:Core:dashboard.html.twig
  17. .. note::
  18. This view, like most of the ``SonataAdminBundle`` views, extends a global
  19. template file, which also contains significant parts to the page. More information
  20. about this is available in the :doc:`templates` chapter.
  21. Blocks
  22. ------
  23. The Dashboard is actually built using ``Blocks`` from ``SonataBlockBundle``. You
  24. can learn more about this bundle and how to build your own Blocks on the
  25. `SonataBlock documentation page`_.
  26. The ``Admin`` list block
  27. ------------------------
  28. The ``Admin`` list is a ``Block`` that fetches information from the ``Admin`` service's
  29. ``Pool`` and prints it in the nicely formatted list you have on your default Dashboard.
  30. The ``Admin`` list is defined by the ``sonata.admin.block.admin_list`` service, which is
  31. implemented by the ``Block\AdminListBlockService`` class. It is then rendered using the
  32. ``SonataAdminBundle:Block:block_admin_list.html.twig`` template file.
  33. Feel free to take a look at these files. You'll find the code rather short and easy to
  34. understand, and it will be a great help when implementing your own blocks.
  35. Configuring the ``Admin`` list
  36. ------------------------------
  37. As you probably noticed by now, the ``Admin`` list groups ``Admin`` mappings together.
  38. There are several ways in which you can configure these groups.
  39. By default the admins are ordered the way you defined them. With the setting ``sort_admins``
  40. groups and admins will be ordered by their respective label with a fallback to the admin id.
  41. Using the ``Admin`` service declaration
  42. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  43. The first, and most commonly used, method is to set a group when defining your ``Admin``
  44. services:
  45. .. configuration-block::
  46. .. code-block:: xml
  47. <service id="app.admin.post" class="AppBundle\Admin\PostAdmin">
  48. <tag name="sonata.admin" manager_type="orm"
  49. group="Content"
  50. label="Post" />
  51. <argument />
  52. <argument>AppBundle\Entity\Post</argument>
  53. <argument />
  54. </service>
  55. .. code-block:: yaml
  56. services:
  57. app.admin.post:
  58. class: AppBundle\Admin\PostAdmin
  59. tags:
  60. - name: sonata.admin
  61. manager_type: orm
  62. group: "Content"
  63. label: "Post"
  64. arguments:
  65. - ~
  66. - AppBundle\Entity\Post
  67. - ~
  68. public: true
  69. In these examples, notice the ``group`` tag, stating that this particular ``Admin``
  70. service belongs to the ``Content`` group.
  71. .. configuration-block::
  72. .. code-block:: xml
  73. <service id="app.admin.post" class="AppBundle\Admin\PostAdmin">
  74. <tag name="sonata.admin" manager_type="orm"
  75. group="app.admin.group.content"
  76. label="app.admin.model.post" label_catalogue="AppBundle" />
  77. <argument />
  78. <argument>AppBundle\Entity\Post</argument>
  79. <argument />
  80. </service>
  81. .. code-block:: yaml
  82. services:
  83. app.admin.post:
  84. class: AppBundle\Admin\PostAdmin
  85. tags:
  86. - name: sonata.admin
  87. manager_type: orm
  88. group: "app.admin.group.content"
  89. label: "app.admin.model.post"
  90. label_catalogue: "AppBundle"
  91. arguments:
  92. - ~
  93. - AppBundle\Entity\Post
  94. - ~
  95. In this example, the labels are translated by ``AppBundle``, using the given
  96. ``label_catalogue``. So, you can use the above examples to support multiple languages
  97. in your project.
  98. .. note::
  99. You can use parameters (e.g. ``%app_admin.group_post%``) for the group names
  100. in either scenario.
  101. Using the ``config.yml``
  102. ^^^^^^^^^^^^^^^^^^^^^^^^
  103. You can also configure the ``Admin`` list in your ``config.yml`` file. This
  104. configuration method overrides any settings defined in the Admin service
  105. declarations.
  106. .. configuration-block::
  107. .. code-block:: yaml
  108. # app/config/config.yml
  109. sonata_admin:
  110. dashboard:
  111. groups:
  112. app.admin.group.content:
  113. label: app.admin.group.content
  114. label_catalogue: AppBundle
  115. items:
  116. - app.admin.post
  117. app.admin.group.blog:
  118. items: ~
  119. item_adds:
  120. - sonata.admin.page
  121. roles: [ ROLE_ONE, ROLE_TWO ]
  122. app.admin.group.misc: ~
  123. .. note::
  124. This is an academic, full configuration, example. In real cases, you will usually
  125. not need to use all the displayed options. To use a default value for any setting
  126. either leave out that key or use the ``~`` value for that option.
  127. This configuration specifies that the ``app.admin.group.content`` group uses the
  128. ``app.admin.group.content`` label, which is translated using the ``AppBundle``
  129. translation catalogue (the same label and translation configuration that we declared
  130. previously, in the service definition example).
  131. It also states that the ``app.admin.group.content`` group contains just the
  132. ``app.admin.post`` ``Admin`` mapping, meaning that any other ``Admin`` services
  133. declared as belonging to this group will not be displayed here.
  134. Secondly, we declare a ``app.admin.group.blog`` group as having all its default items
  135. (i.e. the ones specified in the ``Admin`` service declarations), plus an *additional*
  136. ``sonata.admin.page`` mapping, that was not initially part of this group.
  137. We also use the ``roles`` option here, which means that only users with the ``ROLE_ONE``
  138. or ``ROLE_TWO`` privileges will be able to see this group, as opposed to the default setting
  139. which allows everyone to see a given group. Users with ``ROLE_SUPER_ADMIN`` are always
  140. able to see groups that would otherwise be hidden by this configuration option.
  141. The third group, ``app.admin.group.misc``, is set up as a group which uses all its
  142. default values, as declared in the service declarations.
  143. Adding more Blocks
  144. ------------------
  145. Like we said before, the Dashboard comes with a default ``Admin`` list block, but
  146. you can create and add more blocks to it.
  147. .. figure:: ../images/dashboard.png
  148. :align: center
  149. :alt: Dashboard
  150. :width: 500
  151. In this screenshot, in addition to the default ``Admin`` list block on the left, we added
  152. a text block and RSS feed block on the right. The configuration for this scenario would be:
  153. .. configuration-block::
  154. .. code-block:: yaml
  155. # app/config/config.yml
  156. sonata_admin:
  157. dashboard:
  158. blocks:
  159. -
  160. position: left
  161. type: sonata.admin.block.admin_list
  162. -
  163. position: right
  164. type: sonata.block.service.text
  165. settings:
  166. content: >
  167. <h2>Welcome to the Sonata Admin</h2>
  168. <p>This is a <code>sonata.block.service.text</code> from the Block
  169. Bundle, you can create and add new block in these area by configuring
  170. the <code>sonata_admin</code> section.</p> <br /> For instance, here
  171. a RSS feed parser (<code>sonata.block.service.rss</code>):
  172. -
  173. position: right
  174. type: sonata.block.service.rss
  175. roles: [POST_READER]
  176. settings:
  177. title: Sonata Project's Feeds
  178. url: https://sonata-project.org/blog/archive.rss
  179. .. note::
  180. Blocks may accept/require additional settings to be passed in order to
  181. work properly. Refer to the associated documentation/implementation to
  182. get more information on each block's options and requirements.
  183. You can also configure the ``roles`` section to configure users that can
  184. view the block.
  185. Display two ``Admin`` list blocks with different dashboard groups
  186. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  187. The same block can have multiple instances, and be displayed multiple times
  188. across the Dashboard using different configuration settings for each instance.
  189. A particular example is the ``Admin`` list block, which can be configured to
  190. suit this scenario.
  191. .. configuration-block::
  192. .. code-block:: yaml
  193. # app/config/config.yml
  194. sonata_admin:
  195. dashboard:
  196. blocks:
  197. # display two dashboard blocks
  198. -
  199. position: left
  200. type: sonata.admin.block.admin_list
  201. settings:
  202. groups: [sonata_page1, sonata_page2]
  203. -
  204. position: right
  205. type: sonata.admin.block.admin_list
  206. settings:
  207. groups: [sonata_page3]
  208. groups:
  209. sonata_page1:
  210. items:
  211. - sonata.page.admin.myitem1
  212. sonata_page2:
  213. items:
  214. - sonata.page.admin.myitem2
  215. - sonata.page.admin.myitem3
  216. sonata_page3:
  217. items:
  218. - sonata.page.admin.myitem4
  219. In this example, you would have two ``admin_list`` blocks on your dashboard, each
  220. of them containing just the respectively configured groups.
  221. .. _`SonataBlock documentation page`: https://sonata-project.org/bundles/block/master/doc/index.html
  222. Statistic Block
  223. ~~~~~~~~~~~~~~~
  224. A statistic block can be used to display a simple counter with a color, an font awesome icon and a text. A
  225. counter is related to the filters from one admin
  226. .. configuration-block::
  227. .. code-block:: yaml
  228. sonata_admin:
  229. dashboard:
  230. blocks:
  231. -
  232. class: col-lg-3 col-xs-6 # twitter bootstrap responsive code
  233. position: top # zone in the dashboard
  234. type: sonata.admin.block.stats # block id
  235. settings:
  236. code: sonata.page.admin.page # admin code - service id
  237. icon: fa-magic # font awesome icon
  238. text: Edited Pages
  239. color: bg-yellow # colors: bg-green, bg-red and bg-aqua
  240. filters: # filter values
  241. edited: { value: 1 }
  242. Dashboard Layout
  243. ~~~~~~~~~~~~~~~~
  244. Supported positions right now are the following:
  245. * top
  246. * left
  247. * center
  248. * right
  249. * bottom
  250. The layout is as follows:
  251. .. code-block:: bash
  252. TOP TOP TOP
  253. LEFT CENTER RIGHT
  254. LEFT CENTER RIGHT
  255. LEFT CENTER RIGHT
  256. BOTTOM BOTTOM BOTTOM
  257. On ``top`` and ``bottom`` positions, you can also specify an optional ``class`` option to set the width of the block.
  258. .. configuration-block::
  259. .. code-block:: yaml
  260. # app/config/config.yml
  261. sonata_admin:
  262. dashboard:
  263. blocks:
  264. # display dashboard block in the top zone with a col-md-6 css class
  265. -
  266. position: top
  267. class: col-md-6
  268. type: sonata.admin.block.admin_list
  269. Configuring what actions are available for each item on the dashboard
  270. ---------------------------------------------------------------------
  271. By default. A "list" and a "create" option are available for each item on the
  272. dashboard. If you created a custom action and want to display it along the
  273. other two on the dashboard, you can do so by overriding the
  274. ``getDashboardActions()`` method of your admin class:
  275. .. code-block:: php
  276. <?php
  277. // src/AppBundle/Admin/PostAdmin.php
  278. class PostAdmin extends AbstractAdmin
  279. {
  280. // ...
  281. public function getDashboardActions()
  282. {
  283. $actions = parent::getDashboardActions();
  284. $actions['import'] = array(
  285. 'label' => 'Import',
  286. 'url' => $this->generateUrl('import'),
  287. 'icon' => 'import',
  288. 'translation_domain' => 'SonataAdminBundle', // optional
  289. 'template' => 'SonataAdminBundle:CRUD:dashboard__action.html.twig', // optional
  290. );
  291. return $actions;
  292. }
  293. }
  294. You can also hide an action from the dashboard by unsetting it:
  295. .. code-block:: php
  296. <?php
  297. // src/AppBundle/Admin/PostAdmin.php
  298. class PostAdmin extends AbstractAdmin
  299. {
  300. // ...
  301. public function getDashboardActions()
  302. {
  303. $actions = parent::getDashboardActions();
  304. unset($actions['list']);
  305. return $actions;
  306. }
  307. }
  308. If you do this, you need to be aware that the action is only hidden. it will
  309. still be available by directly calling its URL, unless you prevent that using
  310. proper security measures (e.g. ACL or role based).