Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

Commit 4d1a74d

Browse files
dbudbu
authored
Merge pull request #833 from symfony-cmf/review-routing-auto
review routing auto docs
2 parents 94ecfd0 + 92e917e commit 4d1a74d

File tree

3 files changed

+139
-30
lines changed

3 files changed

+139
-30
lines changed

‎bundles/routing_auto/configuration.rst‎

Lines changed: 114 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ Configuration
1010
``adapter``
1111
~~~~~~~~~~~
1212

13-
**type**: ``scalar`` **default**: ``doctrine_phpcr_odm`` if ``persistence`` configuration option is set ``phpcr``
13+
**type**: ``scalar`` **default**: ``doctrine_phpcr_odm`` if ``persistence`` configuration option is set to ``phpcr``
1414

15-
This defines the adapter used to manage routes.
15+
Alias of the :doc:`adapter <adapter>` used to manage routes.
1616

1717
``auto_mapping``
1818
~~~~~~~~~~~~~~~~
@@ -22,10 +22,120 @@ This defines the adapter used to manage routes.
2222
Look for the configuration file ``cmf_routing_auto.yml`` in `Resource/config` folder of all
2323
available bundles.
2424

25+
``mapping``
26+
~~~~~~~~~~~
27+
28+
Specify files with auto routing mapping.
29+
30+
.. configuration-block::
31+
32+
.. code-block:: yaml
33+
34+
# app/config/config.yml
35+
cmf_routing_auto:
36+
mapping:
37+
resources:
38+
-
39+
path: app/Resources/routing_auto.yml
40+
type: yaml
41+
42+
.. code-block:: xml
43+
44+
<!-- app/config/config.xml -->
45+
<?xml version="1.0" encoding="UTF-8" ?>
46+
<container xmlns="http://symfony.com/schema/dic/services">
47+
48+
<config xmlns="http://cmf.symfony.com/schema/dic/routing_auto">
49+
<mapping>
50+
<resource path="app/Resources/routing_auto.yml" type="yaml"/>
51+
</mapping>
52+
</config>
53+
54+
</container>
55+
56+
.. code-block:: php
57+
58+
// app/config/config.php
59+
$container->loadFromExtension('cmf_routing_auto', [
60+
'mapping' => [
61+
'resources' => [
62+
[
63+
'path' => 'app/Resources/routing_auto.yml',
64+
'type' => 'yaml',
65+
],
66+
],
67+
],
68+
]);
69+
70+
``path``
71+
........
72+
73+
**type**: ``scalar`` **required**
74+
75+
Path to the auto route mapping file in the project.
76+
77+
``type``
78+
........
79+
80+
**type**: ``enum`` **values**: ``yaml``|``xml`` **optional**
81+
82+
Type of the configuration file, for the Symfony configuration loader.
83+
2584
``persistence``
2685
~~~~~~~~~~~~~~~
2786

87+
Select persistence mode. Only PHPCR is provided by this bundle.
88+
2889
``phpcr``
29-
.........
90+
~~~~~~~~~
91+
92+
Use this section to configure the PHPCR adapter.
93+
94+
.. configuration-block::
95+
96+
.. code-block:: yaml
97+
98+
# app/config/config.yml
99+
cmf_routing_auto:
100+
persistence:
101+
phpcr:
102+
enabled: true
103+
route_basepath: /cms/routes
104+
105+
.. code-block:: xml
106+
107+
<!-- app/config/config.xml -->
108+
<?xml version="1.0" encoding="UTF-8" ?>
109+
<container xmlns="http://symfony.com/schema/dic/services">
110+
111+
<config xmlns="http://cmf.symfony.com/schema/dic/routing_auto">
112+
<persistence>
113+
<phpcr enabled="true" route-basepath="/cms/routes"/>
114+
</persistence>
115+
</config>
116+
117+
</container>
118+
119+
.. code-block:: php
120+
121+
// app/config/config.php
122+
$container->loadFromExtension('cmf_routing_auto', [
123+
'persistence' => [
124+
'phpcr' => [
125+
'enabled' => true,
126+
'route_basepath' => '/cms/routes',
127+
],
128+
],
129+
]);
130+
131+
``enabled``
132+
...........
133+
134+
**type**: ``Boolean`` **default**: ``false``
135+
136+
``route_basepath``
137+
..................
138+
139+
**type**: ``scalar`` **default**: ``/cms/routes``
30140

31-
.. todo
141+
Path to the root route to know where to add auto routes.

‎bundles/routing_auto/defunct_route_handlers.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -112,11 +112,11 @@ can be configured as follows:
112112
Creating a Custom Defunct Route Handler
113113
---------------------------------------
114114

115-
To create a custom default route handler, you have to implement
116-
``DefunctRouteHandlerInterface``. This requires a method ``handleDefunctRoutes()``.
115+
To create your own custom defunct route handler, you implement
116+
``DefunctRouteHandlerInterface`` which specifies one method called
117+
``handleDefunctRoutes()``.
117118

118-
They are not all-together trivial - the following handler removes old routes and is
119-
the default handler::
119+
To get an idea, lets look at the default handler that removes the old route::
120120

121121
namespace Symfony\Cmf\Component\RoutingAuto\DefunctRouteHandler;
122122

‎bundles/routing_auto/introduction.rst‎

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,6 @@ RoutingAutoBundle
88
The RoutingAutoBundle allows you to automatically persist routes when
99
documents are persisted based on URI schemas and contextual information.
1010

11-
This implies a separation of the ``Route`` and ``Content`` documents. If your
12-
needs are simple this bundle may not be for you and you should have a look at
13-
:doc:`the SimpleCmsBundle <../simple_cms/introduction>`.
14-
1511
Installation
1612
------------
1713

@@ -44,20 +40,22 @@ Features
4440
--------
4541

4642
Imagine you are going to create a forum application that has two routeable
47-
content documents - a category and the topics. These documents are called
48-
``Category`` and ``Topic``, and they are called *content documents*.
49-
50-
If you create a new category with the title "My New Category", the
51-
RoutingAutoBundle will automatically create the route
52-
``/forum/my-new-cateogry``. For each new ``Topic`` it could create a route
53-
like ``/forum/my-new-category/my-new-topic``. This URI resolves to a special
54-
type of route that is called an *auto route*.
55-
56-
By default, when you update a content document that has an auto route, the
57-
corresponding auto route will also be updated. When deleting a content
58-
document, the corresponding auto route will also be deleted.
59-
60-
If required, the bundle can also be configured to do extra stuff, like, for
43+
content documents - the categories and the topics. They are defined in the
44+
document classes ``Category`` and ``Topic``. In general, we speak of them as
45+
*content documents*.
46+
47+
With the proper setup, routing auto automatically creates the route
48+
``/forum/my-new-cateogry`` when you create a new category with the title
49+
"My New Category". For each new ``Topic``, it creates a route like
50+
``/forum/my-new-category/my-new-topic``.
51+
52+
The routes created by this bundle are documents of a special class
53+
``AutoRoute`` so that they can be recognized by the application as having been
54+
auto created. By default, when you update a content document that has an auto
55+
route, the corresponding auto route will also be updated. When deleting such a
56+
content document, the corresponding auto route will also be deleted.
57+
58+
If required, the bundle can also be configured to do extra things, like, for
6159
example, leaving a ``RedirectRoute`` when the location of a content document
6260
changes or automatically displaying an index page when an unconfigured
6361
intermediate path is accessed (for example, listing all the children when requesting
@@ -89,7 +87,7 @@ Usage
8987
-----
9088

9189
Imagine you have a fictional forum application and that you want to access the
92-
forum topic with the following fictional URI:
90+
forum topic with the following URI:
9391

9492
- ``https://mywebsite.com/my-forum/drinks/coffee``
9593

@@ -168,8 +166,8 @@ follows::
168166
}
169167
}
170168

171-
After persisting this object, the route will be created. You will of course
172-
be wanting to return property values and not static strings, but you get the
169+
After persisting this object, the route will be created. Your classes will of
170+
course be returning property values and not static strings, but you get the
173171
idea.
174172

175173
.. note::
@@ -178,7 +176,8 @@ idea.
178176
object. Imagine you have 2 documents, ``ContactPage`` and ``Page``, which
179177
both extend ``AbstractPage``. When you map the ``AbstractPage`` class, it
180178
will be applied to both documents. You can also use the ``extend`` keyword
181-
to achieve the same thing with objects which are not related.
179+
in the auto routing configuration file to achieve the same thing with
180+
objects which are not related.
182181

183182
This is just a basic example. You can also configure what should happen when
184183
a route already exists (conflict resolution) and what to do with old routes

0 commit comments

Comments
 (0)