RouteBundle
===========

The RouteBundle provides the feature of managing website-routes for
custom-entities. These routes will be generated by calling the
`RouteManager` which uses a configurable schema for creating the
route-path.

Every Entity can be combined with a route. You only have to call the
`create` method of the service `sulu_route.manager.route_manager`
with an entity implementing the `RoutableInterface`.

The `update` method will update the route-path with the configured
schema and hold "history" (301 redirects) routes for the old routes.

To resolve the route on request you have to provide a
`RouteDefaultsProvider` which defines the controller and attributes
of the route.

Further Topics
--------------

.. toctree::
    :maxdepth: 1

    custom_route_generator

Example
-------

This example will create a simple example-entity which will be
available on the website with an own route.

Entity
******

First extend your entity with the propertie's `id`, `locale` and a new many-to-one relation `route`:

reciepe.orm.xml:

.. code-block:: xml

    ...

    <field name="id" type="int"/>
    <field name="locale" type="string" length="5"/>

    <many-to-one field="route" target-entity="Sulu\Bundle\RouteBundle\Entity\Route">
        <cascade>
            <cascade-all/>
        </cascade>
        <join-column name="idRoutes" referenced-column-name="id" nullable="true" on-delete="SET NULL"/>
    </many-to-one>

Reciepe.php:

.. code-block:: php

    namespace AppBundle\Entity;

    use Sulu\Bundle\RouteBundle\Model\RoutableInterface;
    use Sulu\Bundle\RouteBundle\Model\RouteInterface;

    class Recipe implements RoutableInterface
    {
        /**
         * @var string
         */
        private $title;

        /**
         * @var RouteInterface
         */
        private $route;

        public function getTitle() { ... }

        public function setTitle() { ... }

        /**
         * {@inheritdoc}
         */
        public function getId() { ... }

        /**
         * {@inheritdoc}
         */
        public function getLocale() { ... }

        /**
         * {@inheritdoc}
         */
        public function setRoute(RouteInterface $route) { ... }

        /**
         * {@inheritdoc}
         */
        public function getRoute() { ... }
    }

Route-Schema
************

Configure the route-schema in the file `app/config/config.yml`:

.. code-block:: yaml

    sulu_route:
        mappings:
            AppBundle\Entity\Recipe:
                generator: schema
                options:
                    route_schema: /{translator.trans('recipe')}/{object.getTitle()}

.. note::

    You can use the `translator` in the schema to create translated routes.

RecipeController
****************

.. code-block:: php

    namespace AppBundle\Controller;

    use AppBundle\Entity\Recipe;
    use Symfony\Bundle\FrameworkBundle\Controller\Controller;

    class RecipeController extends Controller
    {
        public function indexAction(Recipe $recipe)
        {
            return $this->render('AppBundle:website:recipe.html.twig', ['recipe' => $recipe]);
        }
    }

RouteDefaultsProvider
*********************

.. code-block:: php

    namespace AppBundle\Routing;

    use AppBundle\Entity\Recipe;
    use AppBundle\Entity\RecipeRepository;
    use Sulu\Bundle\RouteBundle\Routing\Defaults\RouteDefaultsProviderInterface;

    class RecipeRouteDefaultProvider implements RouteDefaultsProviderInterface
    {
        protected $recipeRepository;

        public function __construct(RecipeRepository $recipeRepository)
        {
            $this->recipeRepository = $recipeRepository;
        }

        public function getByEntity($entityClass, $id, $locale, $object = null)
        {
            return [
                '_controller' => 'AppBundle:Recipe:index',
                'recipe' => $object ?: $this->recipeRepository->find($id, $locale),
            ];
        }

        public function isPublished($entityClass, $id, $locale)
        {
            return true;
        }

        public function supports($entityClass)
        {
            return $entityClass === Recipe::class;
        }
    }

Register this class as a service with the tag `<tag name="sulu_route.defaults_provider"/>`.

After that the entity is ready to get a route. To create a route for the new entities
simple call the `save` method of the service `sulu_route.manager.route_manager`.

.. note::

    To update already existing entities you can run the command
    `bin/console sulu:route:update AppBundle:Recipe` which updates or creates
    the route for all the entities of this type.