Split introduction in seperate articles

Author: wouterj

bundles/routing_auto/customization.rst

@@ -0,0 +1,136 @@
+Customization
+-------------
+
+.. _routingauto_customization_pathproviders:
+
+Adding Path Providers
+~~~~~~~~~~~~~~~~~~~~~
+
+The goal of a ``PathProvider`` class is to add one or several path elements to
+the route stack. For example, the following provider will add the path
+``foo/bar`` to the route stack::
+
+    <?php
+
+    use Symfony\Cmf\Bundle\RoutingAutoBundle\AutoRoute\PathProviderInterface;
+    use Symfony\Cmf\Bundle\RoutingAutoBundle\AutoRoute\RouteStack;
+
+    class FoobarProvider implements PathProviderInterface
+    {
+        public function providePath(RouteStack $routeStack)
+        {
+            $routeStack->addPathElements(array('foo', 'bar'));
+        }
+    }
+
+To use the path provider you must register it in the **DIC** and add the
+``cmf_routing_auto.provider`` tag and set the **alias** accordingly.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        my_cms.some_bundle.path_provider.foobar:
+            class: "FoobarProvider"
+            scope: prototype
+            tags:
+                - { name: cmf_routing_auto.provider, alias: "foobar"}
+
+    .. code-block:: xml
+
+        <service
+            id="my_cms.some_bundle.path_provider.foobar"
+            class="FoobarProvider"
+            scope="prototype"
+        >
+            <tag name="cmf_routing_auto.provider" alias="foobar"/>
+        </service>
+
+    .. code-block:: php
+
+        use Symfony\Component\DependencyInjection\Definition;
+
+        $definition = new Definition('FooBarProvider');
+        $definition->addTag('cmf_routing_auto.provider', array('alias' => 'foobar'));
+        $definition->setScope('prototype');
+
+        $container->setDefinition('my_cms.some_bundle.path_provider.foobar', $definition);
+
+The **foobar** path provider is now available as **foobar**.
+
+.. note::
+
+    The that both path providers and path actions need to be defined with a
+    scope of "prototype". This ensures that each time the auto routing system
+    requests the class a new one is given and we do not have any state
+    problems.
+
+Adding Path Actions
+~~~~~~~~~~~~~~~~~~~
+
+In the auto routing system, a "path action" is an action to take if the path
+provided by the "path provider" exists or not.
+
+You can add a path action by extending the ``PathActionInterface`` and
+registering your new class correctly in the DI configuration.
+
+This is a very simple implementation from the bundle - it is used to throw an
+exception when a path already exists::
+
+    namespace Symfony\Cmf\Bundle\RoutingAutoBundle\AutoRoute\PathNotExists;
+
+    use Symfony\Cmf\Bundle\RoutingAutoBundle\AutoRoute\PathActionInterface;
+    use Symfony\Cmf\Bundle\RoutingAutoBundle\AutoRoute\Exception\CouldNotFindRouteException;
+    use Symfony\Cmf\Bundle\RoutingAutoBundle\AutoRoute\RouteStack;
+
+    class ThrowException implements PathActionInterface
+    {
+        public function init(array $options)
+        {
+        }
+
+        public function execute(RouteStack $routeStack)
+        {
+            throw new CouldNotFindRouteException('/'.$routeStack->getFullPath());
+        }
+    }
+
+It is registered in the DI configuration as follows:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        cmf_routing_auto.not_exists_action.throw_exception
+            class: "My\Cms\AutoRoute\PathNotExists\ThrowException"
+            scope: prototype
+            tags:
+                - { name: cmf_routing_auto.provider, alias: "throw_exception"}
+
+    .. code-block:: xml
+
+        <service
+            id="my_cms.not_exists_action.throw_exception"
+            class="My\Cms\AutoRoute\PathNotExists\ThrowException"
+            scope="prototype"
+            >
+            <tag name="cmf_routing_auto.not_exists_action" alias="throw_exception"/>
+        </service>
+
+    .. code-block:: php
+
+        use Symfony\Component\DependencyInjection\Definition;
+
+        $definition = new Definition('My\Cms\AutoRoute\PathNotExists\ThrowException');
+        $definition->addTag('cmf_routing_auto.provider', array('alias' => 'throw_exception'));
+        $definition->setScope('prototype');
+
+        $container->setDefinition('my_cms.some_bundle.path_provider.throw_exception', $definition);
+
+Note the following:
+
+* **Scope**: Must *always* be set to *prototype*;
+* **Tag**: The tag registers the service with the auto routing system, it can be one of the following;
+    * ``cmf_routing_auto.exists.action`` - if the action is to be used when a path exists;
+    * ``cmf_routing_auto.not_exists.action`` - if the action is to be used when a path does not exist;
+* **Alias**: The alias of the tag is the name by which you will reference this action in the auto routing schema.

bundles/routing_auto/exists_actions.rst

@@ -0,0 +1,72 @@
+.. index::
+    single: Exists Actions; RoutingAutoBundle
+
+Path Exists Actions
+-------------------
+
+These are the default actions available to take if the path provided by a
+`path_provider` already exists and so creating a new path would create a
+conflict.
+
+auto_increment
+~~~~~~~~~~~~~~
+
+The ``auto_increment`` action will add a numerical suffix to the path, for
+example ``my/path`` would first become ``my/path-1`` and if that path *also*
+exists it will try ``my/path-2``, ``my/path-3`` and so on into infinity until
+it finds a path which *doesn't* exist.
+
+This action should typically be used in the ``content_name`` builder unit to
+resolve conflicts. Using it in the ``content_path`` builder chain would not
+make much sense (I can't imagine any use cases at the moment).
+
+Example:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        exists_action: auto_increment
+
+    .. code-block:: xml
+
+        <exists-action name="auto_increment" />
+
+    .. code-block:: php
+
+        array(
+            // ...
+            'exists_action' => 'auto_increment',
+        );
+
+use
+~~~
+
+The ``use`` action will simply take the existing path and use it. For example,
+in our post example the first builder unit must first determine the blogs
+path, ``/my/blog``, if this path exists (and it should) then we will *use* it
+in the stack.
+
+This action should typically be used in one of the content path builder units
+to specify that we should use the existing route, on the other hand, using
+this as the content name builder action should cause the old route to be
+overwritten.
+
+Example:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        exists_action: use
+
+    .. code-block:: xml
+
+        <exists-action name="use" />
+
+    .. code-block:: php
+
+        array(
+            // ...
+            'exists_action' => 'use',
+        );