getting_started.rst 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279
  1. Getting started with SonataAdminBundle
  2. ======================================
  3. If you followed the installation instructions, SonataAdminBundle should be installed
  4. but inaccessible. You first need to configure it for your models before you can
  5. start using it. Here is a quick checklist of what is needed to quickly setup
  6. SonataAdminBundle and create your first admin interface for the models of your application:
  7. * Step 1: Create an Admin class
  8. * Step 2: Create an Admin service
  9. * Step 3: Configuration
  10. Create an Admin class
  11. ---------------------
  12. SonataAdminBundle helps you manage your data using a graphic interface that
  13. will let you create, update or search your model's instances. Those actions need to
  14. be configured, which is done using an Admin class.
  15. An Admin class represents the mapping of your model to each administration action.
  16. In it, you decide which fields to show on a listing, which to use as filters or what
  17. to show in a creation or edition form.
  18. The easiest way to create an Admin class for your model is to extend
  19. the ``Sonata\AdminBundle\Admin\AbstractAdmin`` class.
  20. Suppose your ``AppBundle`` has a ``Post`` entity.
  21. This is how a basic Admin class for it could look like:
  22. .. code-block:: php
  23. <?php
  24. // src/AppBundle/Admin/PostAdmin.php
  25. namespace AppBundle\Admin;
  26. use Sonata\AdminBundle\Admin\AbstractAdmin;
  27. use Sonata\AdminBundle\Show\ShowMapper;
  28. use Sonata\AdminBundle\Form\FormMapper;
  29. use Sonata\AdminBundle\Datagrid\ListMapper;
  30. use Sonata\AdminBundle\Datagrid\DatagridMapper;
  31. class PostAdmin extends AbstractAdmin
  32. {
  33. // Fields to be shown on create/edit forms
  34. protected function configureFormFields(FormMapper $formMapper)
  35. {
  36. $formMapper
  37. ->add('title', 'text', array(
  38. 'label' => 'Post Title'
  39. ))
  40. ->add('author', 'entity', array(
  41. 'class' => 'AppBundle\Entity\User'
  42. ))
  43. // if no type is specified, SonataAdminBundle tries to guess it
  44. ->add('body')
  45. // ...
  46. ;
  47. }
  48. // Fields to be shown on filter forms
  49. protected function configureDatagridFilters(DatagridMapper $datagridMapper)
  50. {
  51. $datagridMapper
  52. ->add('title')
  53. ->add('author')
  54. ;
  55. }
  56. // Fields to be shown on lists
  57. protected function configureListFields(ListMapper $listMapper)
  58. {
  59. $listMapper
  60. ->addIdentifier('title')
  61. ->add('slug')
  62. ->add('author')
  63. ;
  64. }
  65. // Fields to be shown on show action
  66. protected function configureShowFields(ShowMapper $showMapper)
  67. {
  68. $showMapper
  69. ->add('title')
  70. ->add('slug')
  71. ->add('author')
  72. ;
  73. }
  74. }
  75. Implementing these four functions is the first step to creating an Admin class.
  76. Other options are available, that will let you further customize the way your model
  77. is shown and handled. Those will be covered in more advanced chapters of this manual.
  78. Create an Admin service
  79. -----------------------
  80. Now that you have created your Admin class, you need to create a service for it. This
  81. service needs to have the ``sonata.admin`` tag, which is your way of letting
  82. SonataAdminBundle know that this particular service represents an Admin class:
  83. Create either a new ``admin.xml`` or ``admin.yml`` file inside the ``src/AppBundle/Resources/config/`` folder:
  84. .. configuration-block::
  85. .. code-block:: xml
  86. <!-- src/AppBundle/Resources/config/admin.xml -->
  87. <service id="app.admin.post" class="AppBundle\Admin\PostAdmin">
  88. <tag name="sonata.admin" manager_type="orm" group="Content" label="Post" />
  89. <argument />
  90. <argument>AppBundle\Entity\Post</argument>
  91. <argument />
  92. <call method="setTranslationDomain">
  93. <argument>AppBundle</argument>
  94. </call>
  95. </service>
  96. .. code-block:: yaml
  97. # src/AppBundle/Resources/config/admin.yml
  98. services:
  99. app.admin.post:
  100. class: AppBundle\Admin\PostAdmin
  101. tags:
  102. - { name: sonata.admin, manager_type: orm, group: "Content", label: "Post" }
  103. arguments:
  104. - ~
  105. - AppBundle\Entity\Post
  106. - ~
  107. calls:
  108. - [ setTranslationDomain, [AppBundle]]
  109. public: true
  110. The example above assumes that you're using ``SonataDoctrineORMAdminBundle``.
  111. If you're using ``SonataDoctrineMongoDBAdminBundle``, ``SonataPropelAdminBundle`` or ``SonataDoctrinePhpcrAdminBundle`` instead, set ``manager_type`` option to ``doctrine_mongodb``, ``propel`` or ``doctrine_phpcr`` respectively.
  112. The basic configuration of an Admin service is quite simple. It creates a service
  113. instance based on the class you specified before, and accepts three arguments:
  114. 1. The Admin service's code (defaults to the service's name)
  115. 2. The model which this Admin class maps (required)
  116. 3. The controller that will handle the administration actions (defaults to ``SonataAdminBundle:CRUDController()``)
  117. Usually you just need to specify the second argument, as the first and third's default
  118. values will work for most scenarios.
  119. The ``setTranslationDomain`` call lets you choose which translation domain to use when
  120. translating labels on the admin pages. If you don't call ``setTranslationDomain``, SonataAdmin uses ``messages`` as translation domain.
  121. More info on the `Symfony translations page`_.
  122. Now that you have a configuration file with your admin service, you just need to tell
  123. Symfony to load it. There are two ways to do so:
  124. Have your bundle load it
  125. ^^^^^^^^^^^^^^^^^^^^^^^^
  126. Inside your bundle's extension file, using the ``load()`` method as described in the `Symfony cookbook`_.
  127. For ``admin.xml`` use:
  128. .. code-block:: php
  129. <?php
  130. // src/AppBundle/DependencyInjection/AppExtension.php
  131. namespace AppBundle\DependencyInjection;
  132. use Symfony\Component\HttpKernel\DependencyInjection\Extension;
  133. use Symfony\Component\DependencyInjection\ContainerBuilder;
  134. use Symfony\Component\DependencyInjection\Loader;
  135. use Symfony\Component\Config\FileLocator;
  136. class AppExtension extends Extension
  137. {
  138. public function load(array $configs, ContainerBuilder $container) {
  139. // ...
  140. $loader = new Loader\XmlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
  141. // ...
  142. $loader->load('admin.xml');
  143. }
  144. }
  145. and for ``admin.yml``:
  146. .. code-block:: php
  147. <?php
  148. // src/AppBundle/DependencyInjection/AppExtension.php
  149. namespace AppBundle\DependencyInjection;
  150. use Symfony\Component\HttpKernel\DependencyInjection\Extension;
  151. use Symfony\Component\DependencyInjection\ContainerBuilder;
  152. use Symfony\Component\DependencyInjection\Loader;
  153. use Symfony\Component\Config\FileLocator;
  154. class AppExtension extends Extension
  155. {
  156. public function load(array $configs, ContainerBuilder $container)
  157. {
  158. // ...
  159. $loader = new Loader\YamlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
  160. // ...
  161. $loader->load('admin.yml');
  162. }
  163. }
  164. Importing it in the main config.yml
  165. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  166. We recommend the to load the file in the Extension, but this way is possible, too.
  167. You can include your new configuration file in the main ``config.yml`` (make sure that you
  168. use the correct file extension):
  169. .. configuration-block::
  170. .. code-block:: yaml
  171. # app/config/config.yml
  172. imports:
  173. # for xml
  174. - { resource: "@AppBundle/Resources/config/admin.xml" }
  175. # for yaml
  176. - { resource: "@AppBundle/Resources/config/admin.yml" }
  177. Configuration
  178. -------------
  179. At this point you have basic administration actions for your model. If you visit ``http://yoursite.local/admin/dashboard`` again, you should now see a panel with
  180. your mapped model. You can start creating, listing, editing and deleting instances.
  181. You probably want to put your own project's name and logo on the top bar.
  182. Put your logo file here ``src/AppBundle/Resources/public/images/fancy_acme_logo.png``
  183. Install your assets:
  184. .. code-block:: bash
  185. $ php app/console assets:install
  186. Now you can change your project's main config.yml file:
  187. .. configuration-block::
  188. .. code-block:: yaml
  189. # app/config/config.yml
  190. sonata_admin:
  191. title: Acme
  192. title_logo: bundles/app/images/fancy_acme_logo.png
  193. Next steps - Security
  194. ---------------------
  195. As you probably noticed, you were able to access your dashboard and data by just
  196. typing in the URL. By default, the SonataAdminBundle does not come with any user
  197. management for ultimate flexibility. However, it is most likely that your application
  198. requires such a feature. The Sonata Project includes a ``SonataUserBundle`` which
  199. integrates the very popular ``FOSUserBundle``. Please refer to the :doc:`security` section of
  200. this documentation for more information.
  201. Congratulations! You are ready to start using SonataAdminBundle. You can now map
  202. additional models or explore advanced functionalities. The following sections will
  203. each address a specific section or functionality of the bundle, giving deeper
  204. details on what can be configured and achieved with SonataAdminBundle.
  205. .. _`Symfony cookbook`: http://symfony.com/doc/master/cookbook/bundles/extension.html#using-the-load-method
  206. .. _`Symfony translations page`: http://symfony.com/doc/current/book/translation.html#using-message-domains