123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279 |
- Getting started with SonataAdminBundle
- ======================================
- If you followed the installation instructions, SonataAdminBundle should be installed
- but inaccessible. You first need to configure it for your models before you can
- start using it. Here is a quick checklist of what is needed to quickly setup
- SonataAdminBundle and create your first admin interface for the models of your application:
- * Step 1: Create an Admin class
- * Step 2: Create an Admin service
- * Step 3: Configuration
- Create an Admin class
- ---------------------
- SonataAdminBundle helps you manage your data using a graphic interface that
- will let you create, update or search your model's instances. Those actions need to
- be configured, which is done using an Admin class.
- An Admin class represents the mapping of your model to each administration action.
- In it, you decide which fields to show on a listing, which to use as filters or what
- to show in a creation or edition form.
- The easiest way to create an Admin class for your model is to extend
- the ``Sonata\AdminBundle\Admin\AbstractAdmin`` class.
- Suppose your ``AppBundle`` has a ``Post`` entity.
- This is how a basic Admin class for it could look like:
- .. code-block:: php
- <?php
- // src/AppBundle/Admin/PostAdmin.php
- namespace AppBundle\Admin;
- use Sonata\AdminBundle\Admin\AbstractAdmin;
- use Sonata\AdminBundle\Show\ShowMapper;
- use Sonata\AdminBundle\Form\FormMapper;
- use Sonata\AdminBundle\Datagrid\ListMapper;
- use Sonata\AdminBundle\Datagrid\DatagridMapper;
- class PostAdmin extends AbstractAdmin
- {
- // Fields to be shown on create/edit forms
- protected function configureFormFields(FormMapper $formMapper)
- {
- $formMapper
- ->add('title', 'text', array(
- 'label' => 'Post Title'
- ))
- ->add('author', 'entity', array(
- 'class' => 'AppBundle\Entity\User'
- ))
- // if no type is specified, SonataAdminBundle tries to guess it
- ->add('body')
- // ...
- ;
- }
- // Fields to be shown on filter forms
- protected function configureDatagridFilters(DatagridMapper $datagridMapper)
- {
- $datagridMapper
- ->add('title')
- ->add('author')
- ;
- }
- // Fields to be shown on lists
- protected function configureListFields(ListMapper $listMapper)
- {
- $listMapper
- ->addIdentifier('title')
- ->add('slug')
- ->add('author')
- ;
- }
- // Fields to be shown on show action
- protected function configureShowFields(ShowMapper $showMapper)
- {
- $showMapper
- ->add('title')
- ->add('slug')
- ->add('author')
- ;
- }
- }
- Implementing these four functions is the first step to creating an Admin class.
- Other options are available, that will let you further customize the way your model
- is shown and handled. Those will be covered in more advanced chapters of this manual.
- Create an Admin service
- -----------------------
- Now that you have created your Admin class, you need to create a service for it. This
- service needs to have the ``sonata.admin`` tag, which is your way of letting
- SonataAdminBundle know that this particular service represents an Admin class:
- Create either a new ``admin.xml`` or ``admin.yml`` file inside the ``src/AppBundle/Resources/config/`` folder:
- .. configuration-block::
- .. code-block:: xml
- <!-- src/AppBundle/Resources/config/admin.xml -->
- <service id="app.admin.post" class="AppBundle\Admin\PostAdmin">
- <tag name="sonata.admin" manager_type="orm" group="Content" label="Post" />
- <argument />
- <argument>AppBundle\Entity\Post</argument>
- <argument />
- <call method="setTranslationDomain">
- <argument>AppBundle</argument>
- </call>
- </service>
- .. code-block:: yaml
- # src/AppBundle/Resources/config/admin.yml
- services:
- app.admin.post:
- class: AppBundle\Admin\PostAdmin
- tags:
- - { name: sonata.admin, manager_type: orm, group: "Content", label: "Post" }
- arguments:
- - ~
- - AppBundle\Entity\Post
- - ~
- calls:
- - [ setTranslationDomain, [AppBundle]]
- public: true
- The example above assumes that you're using ``SonataDoctrineORMAdminBundle``.
- If you're using ``SonataDoctrineMongoDBAdminBundle``, ``SonataPropelAdminBundle`` or ``SonataDoctrinePhpcrAdminBundle`` instead, set ``manager_type`` option to ``doctrine_mongodb``, ``propel`` or ``doctrine_phpcr`` respectively.
- The basic configuration of an Admin service is quite simple. It creates a service
- instance based on the class you specified before, and accepts three arguments:
- 1. The Admin service's code (defaults to the service's name)
- 2. The model which this Admin class maps (required)
- 3. The controller that will handle the administration actions (defaults to ``SonataAdminBundle:CRUDController()``)
- Usually you just need to specify the second argument, as the first and third's default
- values will work for most scenarios.
- The ``setTranslationDomain`` call lets you choose which translation domain to use when
- translating labels on the admin pages. If you don't call ``setTranslationDomain``, SonataAdmin uses ``messages`` as translation domain.
- More info on the `Symfony translations page`_.
- Now that you have a configuration file with your admin service, you just need to tell
- Symfony to load it. There are two ways to do so:
- Have your bundle load it
- ^^^^^^^^^^^^^^^^^^^^^^^^
- Inside your bundle's extension file, using the ``load()`` method as described in the `Symfony cookbook`_.
- For ``admin.xml`` use:
- .. code-block:: php
- <?php
- // src/AppBundle/DependencyInjection/AppExtension.php
- namespace AppBundle\DependencyInjection;
- use Symfony\Component\HttpKernel\DependencyInjection\Extension;
- use Symfony\Component\DependencyInjection\ContainerBuilder;
- use Symfony\Component\DependencyInjection\Loader;
- use Symfony\Component\Config\FileLocator;
- class AppExtension extends Extension
- {
- public function load(array $configs, ContainerBuilder $container) {
- // ...
- $loader = new Loader\XmlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
- // ...
- $loader->load('admin.xml');
- }
- }
- and for ``admin.yml``:
- .. code-block:: php
- <?php
- // src/AppBundle/DependencyInjection/AppExtension.php
- namespace AppBundle\DependencyInjection;
- use Symfony\Component\HttpKernel\DependencyInjection\Extension;
- use Symfony\Component\DependencyInjection\ContainerBuilder;
- use Symfony\Component\DependencyInjection\Loader;
- use Symfony\Component\Config\FileLocator;
- class AppExtension extends Extension
- {
- public function load(array $configs, ContainerBuilder $container)
- {
- // ...
- $loader = new Loader\YamlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
- // ...
- $loader->load('admin.yml');
- }
- }
- Importing it in the main config.yml
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- We recommend the to load the file in the Extension, but this way is possible, too.
- You can include your new configuration file in the main ``config.yml`` (make sure that you
- use the correct file extension):
- .. configuration-block::
- .. code-block:: yaml
- # app/config/config.yml
- imports:
- # for xml
- - { resource: "@AppBundle/Resources/config/admin.xml" }
- # for yaml
- - { resource: "@AppBundle/Resources/config/admin.yml" }
- Configuration
- -------------
- 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
- your mapped model. You can start creating, listing, editing and deleting instances.
- You probably want to put your own project's name and logo on the top bar.
- Put your logo file here ``src/AppBundle/Resources/public/images/fancy_acme_logo.png``
- Install your assets:
- .. code-block:: bash
- $ php app/console assets:install
- Now you can change your project's main config.yml file:
- .. configuration-block::
- .. code-block:: yaml
- # app/config/config.yml
- sonata_admin:
- title: Acme
- title_logo: bundles/app/images/fancy_acme_logo.png
- Next steps - Security
- ---------------------
- As you probably noticed, you were able to access your dashboard and data by just
- typing in the URL. By default, the SonataAdminBundle does not come with any user
- management for ultimate flexibility. However, it is most likely that your application
- requires such a feature. The Sonata Project includes a ``SonataUserBundle`` which
- integrates the very popular ``FOSUserBundle``. Please refer to the :doc:`security` section of
- this documentation for more information.
- Congratulations! You are ready to start using SonataAdminBundle. You can now map
- additional models or explore advanced functionalities. The following sections will
- each address a specific section or functionality of the bundle, giving deeper
- details on what can be configured and achieved with SonataAdminBundle.
- .. _`Symfony cookbook`: http://symfony.com/doc/master/cookbook/bundles/extension.html#using-the-load-method
- .. _`Symfony translations page`: http://symfony.com/doc/current/book/translation.html#using-message-domains
|