|
|
@@ -1,87 +1,170 @@
|
|
|
Dashboard
|
|
|
=========
|
|
|
|
|
|
-The dashboard is the main landing page. By default the dashboard lists the different admin areas available.
|
|
|
-The admin list is a block defined by the ``sonata.admin.block.admin_list`` service. More block can be added, just
|
|
|
-follow the instruction in the `BlockBundle documentation`_.
|
|
|
+The Dashboard is the main landing page. By default it lists your mapped models,
|
|
|
+as defined by you using ``Admin`` services. This is useful to help you start using
|
|
|
+``SonataAdminBundle`` right away, but there's much more that you can do to take
|
|
|
+advantage of the Dashboard.
|
|
|
|
|
|
-If you want to customize the dashboard, add the following code to your
|
|
|
-application's config file:
|
|
|
+The Dashboard is, by default, available at ``/admin/dashboard``, which is handled by
|
|
|
+the ``SonataAdminBundle:Core:dashboard`` controller action. The default view file for
|
|
|
+this action is ``SonataAdminBundle:Core:dashboard.html.twig``, but you can easily change
|
|
|
+it in your ``config.yml``:
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
# app/config/config.yml
|
|
|
sonata_admin:
|
|
|
- blocks:
|
|
|
- # display a dashboard block
|
|
|
- - { position: left, type: sonata.admin.block.admin_list }
|
|
|
+ templates:
|
|
|
+ dashboard: SonataAdminBundle:Core:dashboard.html.twig
|
|
|
|
|
|
- dashboard
|
|
|
- groups:
|
|
|
- ... your config ...
|
|
|
+.. note::
|
|
|
+ This view, like most of ``SonataAdminBundle`` views, extends a global
|
|
|
+ template file, which also contains significant parts to the page. More information
|
|
|
+ about this is available in the :doc:`templates` chapter.
|
|
|
|
|
|
-.. figure:: ../images/dashboard.png
|
|
|
- :align: center
|
|
|
- :alt: The dashboard
|
|
|
- :width: 400px
|
|
|
+Blocks
|
|
|
+------
|
|
|
+
|
|
|
+The Dashboard is actually built using ``Blocks`` from ``SonataBlockBundle``. You
|
|
|
+can learn more about this bundle and how to build your own Blocks in its `documentation page`_.
|
|
|
+
|
|
|
+An example of a ``Block`` is the above mentioned ``Admin`` list. It is actually implemented as a
|
|
|
+``SonataBlockBundle`` block, that displays your configured ``Admin`` services in a nicely
|
|
|
+formated list.
|
|
|
+
|
|
|
+The ``Admin`` list
|
|
|
+------------------
|
|
|
|
|
|
- The dashboard
|
|
|
+The ``Admin`` list is a ``Block`` that fetches information from the ``Admin`` services ``Pool``
|
|
|
+and prints it in the nicely formated list you have on your default Dashboard.
|
|
|
+The ``Admin`` list is defined by the ``sonata.admin.block.admin_list`` service, which is
|
|
|
+implemented by the ``Block\AdminListBlockService`` class. It is then rendered using the
|
|
|
+``SonataAdminBundle:Block:block_admin_list.html.twig`` template file.
|
|
|
|
|
|
+Feel free to take a look at these files. You'll find the code rather small and easy to
|
|
|
+understand, and will be a great help when implementing your own blocks.
|
|
|
|
|
|
-Examples
|
|
|
---------
|
|
|
+Configuring the ``Admin`` list
|
|
|
+------------------------------
|
|
|
|
|
|
-Set the label group & add all the default items
|
|
|
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
+As you probably noticed by now, the ``Admin`` list groups ``Admin`` mappings together.
|
|
|
+There are several ways in which you can configure these groups.
|
|
|
|
|
|
+Using the ``Admin`` service declaration
|
|
|
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
+
|
|
|
+The first, and most commonly
|
|
|
+used, is when defining your ``Admin`` service:
|
|
|
+
|
|
|
+.. code-block:: xml
|
|
|
+
|
|
|
+ <service id="sonata.admin.post" class="Acme\DemoBundle\Admin\PostAdmin">
|
|
|
+ <tag name="sonata.admin" manager_type="orm" group="Content" label="Post"/>
|
|
|
+ <argument />
|
|
|
+ <argument>Acme\DemoBundle\Entity\Post</argument>
|
|
|
+ <argument />
|
|
|
+ </service>
|
|
|
+
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
- # app/config/config.yml
|
|
|
- sonata_admin:
|
|
|
- dashboard:
|
|
|
- blocks:
|
|
|
- # display a dashboard block
|
|
|
- - { position: left, type: sonata.admin.block.admin_list }
|
|
|
+ services:
|
|
|
+ sonata.admin.post:
|
|
|
+ class: Acme\DemoBundle\Admin\PostAdmin
|
|
|
+ tags:
|
|
|
+ - { name: sonata.admin, manager_type: orm, group: "Content", label: "Post" }
|
|
|
+ arguments:
|
|
|
+ - ~
|
|
|
+ - Acme\DemoBundle\Entity\Post
|
|
|
+ - ~
|
|
|
+
|
|
|
+In these examples, notice the ``group`` tag, stating that this particular ``Admin`` service
|
|
|
+belongs to the ``Content`` group.
|
|
|
+
|
|
|
+.. code-block:: xml
|
|
|
+
|
|
|
+ <service id="sonata.admin.post" class="Acme\DemoBundle\Admin\PostAdmin">
|
|
|
+ <tag name="sonata.admin" manager_type="orm" group="acme.admin.group.content" label="acme.admin.model.post" label_catalogue="AcmeDemoBundle"/>
|
|
|
+ <argument />
|
|
|
+ <argument>Acme\DemoBundle\Entity\Post</argument>
|
|
|
+ <argument />
|
|
|
+ </service>
|
|
|
+
|
|
|
+.. code-block:: yaml
|
|
|
|
|
|
- groups:
|
|
|
- sonata_page:
|
|
|
- label: Page
|
|
|
- items: ~
|
|
|
+ services:
|
|
|
+ sonata.admin.post:
|
|
|
+ class: Acme\DemoBundle\Admin\PostAdmin
|
|
|
+ tags:
|
|
|
+ - { name: sonata.admin, manager_type: orm, group: "acme.admin.group.content", label: "acme.admin.model.post", label_catalogue: "AcmeDemoBundle" }
|
|
|
+ arguments:
|
|
|
+ - ~
|
|
|
+ - Acme\DemoBundle\Entity\Post
|
|
|
+ - ~
|
|
|
+
|
|
|
+The provided labels are actually translated by ``SonataAdminBundle``, using the given
|
|
|
+``label_catalogue``. So, you can use the above examples to support multilanguage
|
|
|
+in your project.
|
|
|
+
|
|
|
+Using the ``config.yml``
|
|
|
+^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
-Set items group
|
|
|
-^^^^^^^^^^^^^^^
|
|
|
+You can also configure the ``Admin`` list in your ``config.yml`` file. This
|
|
|
+configuration method overrides the configuration defined as part of the
|
|
|
+``Admin`` services declaration.
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
# app/config/config.yml
|
|
|
sonata_admin:
|
|
|
dashboard:
|
|
|
- blocks:
|
|
|
- # display a dashboard block
|
|
|
- - { position: left, type: sonata.admin.block.admin_list }
|
|
|
-
|
|
|
groups:
|
|
|
- sonata_page:
|
|
|
+ acme.admin.group.content:
|
|
|
+ label: acme.admin.group.content
|
|
|
+ label_catalogue: AcmeDemoBundle
|
|
|
items:
|
|
|
- - sonata.page.admin.page
|
|
|
+ - sonata.admin.post
|
|
|
+ acme.admin.group.blog:
|
|
|
+ items: ~
|
|
|
+ item_adds:
|
|
|
+ - sonata.admin.page
|
|
|
+ acme.admin.group.misc: ~
|
|
|
|
|
|
-Add a group with all the default items
|
|
|
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
+.. note::
|
|
|
+ This is an academic, full configuration example, meaning that in real cases, you may
|
|
|
+ not need to use all the displayed options. Default values can be used by either
|
|
|
+ leaving them out of the configuration or by using the ``~`` value in the respective option.
|
|
|
|
|
|
-.. code-block:: yaml
|
|
|
+This configuration specifies that the ``acme.admin.group.content`` group uses the
|
|
|
+``acme.admin.group.content`` label, which is translated using the ``AcmeDemoBundle``
|
|
|
+translation catalogue. In other words, it's the same configuration that we declared
|
|
|
+previously, on the ``Admin`` service.
|
|
|
|
|
|
- # app/config/config.yml
|
|
|
- sonata_admin:
|
|
|
- dashboard:
|
|
|
- blocks:
|
|
|
- # display a dashboard block
|
|
|
- - { position: left, type: sonata.admin.block.admin_list }
|
|
|
+It also states that the ``acme.admin.group.content`` group contains just the
|
|
|
+``sonata.admin.post`` ``Admin`` mapping, meaning that any other ``Admin`` services
|
|
|
+declared as belonging to this group will not be displayed here.
|
|
|
|
|
|
- groups:
|
|
|
- sonata_page: ~
|
|
|
+Secondly, we declare a ``acme.admin.group.blog`` as having all its default items
|
|
|
+(by default we mean the ones specified in the ``Admin`` services declaration), plus
|
|
|
+an additional ``sonata.admin.page`` mapping, that was not initially part of this group.
|
|
|
+
|
|
|
+The third group keeps all the default values, as declared on the ``Admin`` service
|
|
|
+declaration.
|
|
|
|
|
|
-Add some items to a group
|
|
|
-^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
+
|
|
|
+Adding more Blocks
|
|
|
+------------------
|
|
|
+
|
|
|
+Like we said before, the Dashboard comes with a default ``Admin`` list block, but
|
|
|
+you can create and add more blocks to it.
|
|
|
+
|
|
|
+.. figure:: ../images/dashboard.png
|
|
|
+ :align: center
|
|
|
+ :alt: Dashboard
|
|
|
+ :width: 500
|
|
|
+
|
|
|
+In this screenshot, you can see how, besides the ``Admin`` list block on the left, we added
|
|
|
+a text block and a RSS feed block to the right. The configuration for this scenario would be:
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
@@ -89,23 +172,22 @@ Add some items to a group
|
|
|
sonata_admin:
|
|
|
dashboard:
|
|
|
blocks:
|
|
|
- # display a dashboard block
|
|
|
- - { position: left, type: sonata.admin.block.admin_list }
|
|
|
+ - { position: left, type: sonata.admin.block.admin_list }
|
|
|
+ - { position: right, type: sonata.block.service.text, settings: { content: "<h2>Welcome to the Sonata Admin</h2> <p>This is a <code>sonata.block.service.text</code> from the Block Bundle, you can create and add new block in these area by configuring the <code>sonata_admin</code> section.</p> <br /> For instance, here a RSS feed parser (<code>sonata.block.service.rss</code>):"} }
|
|
|
+ - { position: right, type: sonata.block.service.rss, settings: { title: Sonata Project's Feeds, url: http://sonata-project.org/blog/archive.rss }}
|
|
|
|
|
|
- groups:
|
|
|
- sonata_page:
|
|
|
- item_adds:
|
|
|
- - sonata.page.admin.myitem1
|
|
|
- - sonata.page.admin.myitem2
|
|
|
|
|
|
+.. note::
|
|
|
+ Blocks may accept/require additional settings to be passed in order to
|
|
|
+ work properly. Refer to the associated documentation/implementation to
|
|
|
+ get more information on each block's options and requirements.
|
|
|
|
|
|
-.. figure:: ../images/dashboard.png
|
|
|
- :align: center
|
|
|
- :alt: Dashboard
|
|
|
- :width: 500
|
|
|
+Display two ``Admin`` list blocks with different dashboard groups
|
|
|
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
-Display two blocks with different dashboard groups
|
|
|
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
+The same block can have multiple instances, and displayed multiple time
|
|
|
+across the Dashboard. An particular example is the ``Admin`` list block,
|
|
|
+which can be configured to better fit this scenario.
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
@@ -129,4 +211,7 @@ Display two blocks with different dashboard groups
|
|
|
items:
|
|
|
- sonata.page.admin.myitem4
|
|
|
|
|
|
-.. _`BlockBundle documentation`: http://sonata-project.org/bundles/block/master/doc/index.html
|
|
|
+In this example, you would have two ``Admin`` list blocks on your dashboard, each of
|
|
|
+them containing just the respectively configured groups.
|
|
|
+
|
|
|
+.. _`documentation page`: http://sonata-project.org/bundles/block/master/doc/index.html
|
Tiago Garcia