SonataAdminBundle/Resources/doc/reference/routing.rst

Routing
=======

The default routes used in the CRUD controller are accessible through the
``Admin`` class.

The ``Admin`` class contains two routing methods:

* ``getRoutes()``: Returns the available routes;
* ``generateUrl($name, $options)``: Generates the related routes.

Routing Definition
------------------

You can set a ``baseRouteName`` property inside your ``Admin`` class, which
represents the route prefix.

.. code-block:: php

    <?php
    class PostAdmin extends Admin
    {
        protected $baseRouteName = 'news_post_admin';
    }

If no ``baseRouteName`` is defined then the Admin will pick one for you, built
in the following format: 'admin_vendor_bundlename_entityname_action'. If the
Admin fails to find the best baseRouteName then a ``RuntimeException`` will
be thrown.

You can also use ``baseRoutePattern`` to set a custom URL for a given ``Admin`` class.

For example, to use ``http://yourdomain.com/admin/foo`` as the base URL for 
the ``FooAdmin`` class (instead of the default of ``http://yourdomain.com/admin/vendor/bundle/foo``)
use the following code:

.. code-block:: php

    <?php
    class FooAdmin extends Admin
    {
        protected $baseRouteName = 'foo';
    }

You will then have route URLs like ``http://yourdomain.com/admin/foo/list`` and 
``http://yourdomain.com/admin/foo/1/edit``

Routing usage
-------------

Inside a CRUD template, a route can be generated by using the ``Admin`` class.

.. code-block:: html+jinja

    <a href="{{ admin.generateUrl('list') }}">List</a>

    <a href="{{ admin.generateUrl('list', params|merge('page': 1) }}">List</a>

Create a route
--------------

You can easily register new routes by defining them in the ``Admin`` class.
Only Admin routes should be registered this way. Of course this requires the
related action to be defined in the controller.

As route is always generated with the ``Admin`` context, it can only be
defined by its name.

.. code-block:: php

    <?php
    use Sonata\AdminBundle\Route\RouteCollection;

    class MediaAdmin extends Admin
    {
        protected function configureRoutes(RouteCollection $collection)
        {
            $collection->add('duplicate');
            $collection->add('view', $this->getRouterIdParameter().'/view');
        }
    }

Removing a route
--------------

Any registered route can be easily removed.

.. code-block:: php

    <?php
    use Sonata\AdminBundle\Route\RouteCollection;

    class MediaAdmin extends Admin
    {
        protected function configureRoutes(RouteCollection $collection)
        {
            $collection->remove('delete');
        }
    }


If you want to disable all default Sonata routes except few whitelisted ones, you can use ``clearExcept()`` method.
This method accepts an array of routes you want to keep active.

.. code-block:: php

    <?php
    use Sonata\AdminBundle\Route\RouteCollection;

    class MediaAdmin extends Admin
    {
        protected function configureRoutes(RouteCollection $collection)
        {
            //Only `list` and `edit` route will be active
            $collection->clearExcept(array('list', 'edit'));
        }
    }

If you want to remove all default routes, you can use ``clear()`` method.

.. code-block:: php

    <?php
    use Sonata\AdminBundle\Route\RouteCollection;

    class MediaAdmin extends Admin
    {
        protected function configureRoutes(RouteCollection $collection)
        {
            //All routes are removed
            $collection->clear();
        }
    }

To prevent some routes from being available when one Admin is embedded inside another one
(e.g. to remove the "add new" option when you embed ``TagAdmin`` within ``PostAdmin``) you 
can use ``hasParentFieldDescription()`` to detect this case and remove the routes.

.. code-block:: php

    <?php
    use Sonata\AdminBundle\Route\RouteCollection;

    class TagAdmin extends Admin
    {
        protected function configureRoutes(RouteCollection $collection)
        {
            if($this->hasParentFieldDescription()) { // prevent display of "Add new" when embedding this form
                $collection->remove('create');
            }
        }
    }


Persistent parameters
---------------------

In some cases, the interface might be required to pass the same parameters
across the different ``Admin``'s actions. Instead of setting them in the
template or doing other weird hacks, you can define a ``getPersistentParameters``
method. This method will be used when a link is being generated.

.. code-block:: php

    <?php
    class MediaAdmin extends Admin
    {
        public function getPersistentParameters()
        {
            if (!$this->getRequest()) {
                return array();
            }

            return array(
                'provider' => $this->getRequest()->get('provider'),
                'context'  => $this->getRequest()->get('context', 'default'),
            );
        }
    }

    // the result :
    //   $admin->generateUrl('create') => /admin/module/create?context=default