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

Commit 03b8e3f

Browse files
dantleechdantleech
committed
Added token providers section
1 parent a65b7fb commit 03b8e3f

File tree

7 files changed

+100
-174
lines changed

7 files changed

+100
-174
lines changed

‎bundles/map.rst.inc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,9 @@ library or they introduce a complete new concept.
5050
* :doc:`routing_auto/index`
5151

5252
* :doc:`routing_auto/introduction`
53-
* :doc:`routing_auto/providers`
54-
* :doc:`routing_auto/exists_actions`
55-
* :doc:`routing_auto/not_exists_actions`
53+
* :doc:`routing_auto/token_providers`
54+
* :doc:`routing_auto/conflict_resolvers`
55+
* :doc:`routing_auto/defunct_route_handlers`
5656
* :doc:`routing_auto/customization`
5757

5858
* :doc:`search/index`

‎bundles/routing_auto/conflict_resolvers.rst

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,18 @@
22
single: Conflict Resolvers; RoutingAutoBundle
33

44
Conflict Resolvers
5-
-------------------
5+
------------------
66

7-
These are the conflict resolvers which are provided by default by the
8-
RoutingAutoBundle.
7+
Conflict resolvers are invoked when the system detects that a newly generated
8+
route would conflict with an route already existing in the route repository.
9+
10+
This section details the conflict resolvers which are provided by default.
911

1012
auto_increment
1113
~~~~~~~~~~~~~~
1214

1315
The ``auto_increment`` conflict resolver will add a numerical suffix to the path, for
14-
example ``my/path`` would first become ``my/path-1`` and if that path *also*
16+
example if ``my/path`` already exists, it would first become ``my/path-1`` and if that path *also*
1517
exists it will try ``my/path-2``, ``my/path-3`` and so on into infinity until
1618
it finds a path which *doesn't* exist.
1719

@@ -34,7 +36,7 @@ it finds a path which *doesn't* exist.
3436
throw_exception
3537
~~~~~~~~~~~~~~~
3638

37-
The ``throw_exception`` efficiently resolves conflicts by throwing exceptions.
39+
The ``throw_exception`` efficiently "resolves" conflicts by throwing exceptions.
3840
This is the default action.
3941

4042
.. configuration-block::

‎bundles/routing_auto/customization.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
Customization
55
-------------
66

7-
.. _routingauto_customization_pathproviders:
7+
.. _routingauto_customization_tokenproviders:
88

99
Token Providers
1010
~~~~~~~~~~~~~~~

‎bundles/routing_auto/defunct_route_handlers.rst

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
Defunct Route Handlers
55
----------------------
66

7-
.. _routingauto_customization_pathproviders:
7+
.. _routingauto_customization_defunctroutehandlers:
88

99
When an already-persisted document is updated and the URL generated by the
1010
RoutingAuto system is changed, a *new* route is always created. Defunct route
@@ -64,8 +64,6 @@ path.
6464
</mapping>
6565
</auto-mapping>
6666
67-
68-
6967
For the redirect to work you will also need to configure a redirect controller
7068
in the ``cmf_routing`` configuration::
7169

‎bundles/routing_auto/index.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ RoutingAutoBundle
55
:maxdepth: 2
66

77
introduction
8-
providers
9-
exists_actions
10-
not_exists_actions
8+
token_providers
9+
conflict_resolvers
10+
defunct_route_handlers
1111
customization
12+

‎bundles/routing_auto/introduction.rst

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -69,17 +69,13 @@ Usage
6969
Imagine you have a fictional forum application and that you want to access the
7070
forum topic with the following fictional URL:
7171

72-
.. code-block::
73-
74-
https://mywebsite.com/my-forum/drinks/coffee
72+
- ``https://mywebsite.com/my-forum/drinks/coffee``
7573

7674
The RoutingAutoBundle uses a URL schema to define how routes are generated. A
7775
schema for the above URL would look like this (the bundle does not care about
7876
the host or protocol):
7977

80-
.. code-block::
81-
82-
/my-forum/{category}/{title}
78+
- ``/my-forum/{category}/{title}``
8379

8480
You can see that ``my-forum`` is static (it will not change) but that
8581
``drinks`` has been replaced with ``{category}`` and ``coffee`` with
@@ -161,12 +157,14 @@ This is just a basic example. You can also configure what should happen when
161157
a route already exists (confict resolution) and what to do with old routes
162158
when the generated URL is changed (defunct route handling).
163159

164-
Token Providers, Conflict Resolvers and Defunct Routes
165-
------------------------------------------------------
160+
Read more
161+
---------
162+
163+
* :doc:`token_providers`
164+
* :doc:`conflict_resolvers`
165+
* :doc:`defunct_route_handlers`
166+
* :doc:`customization`
166167

167-
* :doc:`providers`
168-
* :doc:`exists_actions`
169-
* :doc:`not_exists_actions`
170168

171169
Customization
172170
-------------

‎bundles/routing_auto/token_providers.rst

Lines changed: 75 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,18 @@
11
.. index::
22
single: Path Providers; RoutingAutoBundle
33

4-
Path Providers
5-
--------------
4+
Token Providers
5+
---------------
66

7-
Path providers specify a target path which is used by the subsequent path
8-
actions to provide the actual route documents.
9-
10-
**Base** providers must be the first configured as the first builder in the
11-
content path chain. This is because the paths that they provide correspond
12-
directly to an existing path, i.e. they have an absolute reference.
13-
14-
specified (base provider)
15-
~~~~~~~~~~~~~~~~~~~~~~~~~
16-
17-
This is the most basic path provider and allows you to specify an exact
18-
(fixed) path.
19-
20-
Options
21-
.......
22-
23-
* ``path`` - **required** The path to provide.
24-
25-
.. configuration-block::
26-
27-
.. code-block:: yaml
28-
29-
provider: [specified, { path: this/is/a/path }]
30-
31-
.. code-block:: xml
32-
33-
<provider name="specified">
34-
<option name="path" value="this/is/a/path" />
35-
</provider>
36-
37-
.. code-block:: php
38-
39-
array(
40-
// ...
41-
'provider' => array('specified', array('path' => 'this/is/a/path')),
42-
);
43-
44-
.. caution::
45-
46-
You should never specifiy absolute paths in the auto route system. If the
47-
builder unit is the first content path chain it is understood that it is
48-
the base of an absolute path.
49-
50-
content_object (base provider)
51-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52-
53-
The content object provider will try and provide a path from an object
54-
implementing ``RouteReferrersInterface`` provided by a designated method on the
55-
content document. For example, if you have a ``Topic`` class, which has a
56-
``getCategory`` method, using this provider you can tell the ``Topic`` auto route
57-
to use the route of the category as a base.
58-
59-
So basically, if your category document has a path of ``/this/is/my/category``,
60-
you can use this path as the base of your ``Category`` auto-route.
61-
62-
Options
63-
.......
64-
65-
- ``method``: **required** Method used to return the document whose route path you wish to use.
66-
67-
.. configuration-block::
68-
69-
.. code-block:: yaml
70-
71-
provider: [content_object, { method: getCategory }]
72-
73-
.. code-block:: xml
74-
75-
<provider name="content_object">
76-
<option name="method" value="getCategory" />
77-
</provider>
78-
79-
.. code-block:: php
80-
81-
array(
82-
// ...
83-
'provider' => array('content_object', array('method' => 'getCategory')),
84-
);
85-
86-
.. note::
87-
88-
At the time of writing translated objects are not supported. But a patch
89-
is already created for this feature.
7+
Token providers provide values for the tokens specified in the URL schemas.
908

919
content_method
9210
~~~~~~~~~~~~~~
9311

9412
The ``content_method`` provider allows the content object (e.g. a forum
9513
``Topic``) to specify a path using one of its methods. This is quite a powerful
9614
method as it allows the content document to do whatever it can to produce the
97-
route, the disadvantage is that your content document will have extra code in
98-
it.
15+
route.
9916

10017
Options
10118
.......
@@ -107,94 +24,104 @@ Options
10724

10825
.. code-block:: yaml
10926
110-
provider: [content_method, { method: getTitle }]
111-
112-
.. code-block:: xml
113-
114-
<provider name="content_method">
115-
<option name="method" value="getTitle" />
116-
</provider>
27+
# src/Acme/ForumBundle/Resources/config/routing_auto.yml
28+
Acme\ForumBundle\Document\Topic:
29+
url_schema: /my-forum/{title}
30+
token_providers:
31+
title: [content_method, {method: getTitle} ]
11732
118-
.. code-block:: php
33+
.. code-block: xml
11934
120-
array(
121-
// ...
122-
'provider' => array('content_method', array('method' => 'getTitle')),
123-
);
35+
<?xml version="1.0" ?>
36+
<!-- src/Acme/ForumBundle/Resources/config/routing_auto.xml -->
37+
<auto-mapping xmlns="http://cmf.symfony.com/schema/routing_auto">
38+
<mapping class="Acme\ForumBundle\Document\Topic" url-schema="/my-forum/{title}">
39+
<token-provider token="category" name="content_method">
40+
<option name="method">getCategoryName</option>
41+
</token-provider>
42+
</mapping>
43+
</auto-mapping>
12444
12545
This example will use the existing method "getTitle" of the ``Topic`` document
12646
to retrieve the title. By default all strings are *slugified*.
12747

128-
The method can return the path either as a single string, an array of path
129-
elements or an object which can be converted into a string, as shown in the
130-
following example::
131-
132-
class Topic
133-
{
134-
/* Using a string */
135-
public function getTitle()
136-
{
137-
return "This is a topic";
138-
}
139-
140-
/* Using an array */
141-
public function getPathElements()
142-
{
143-
return array('this', 'is', 'a', 'path');
144-
}
145-
146-
/* Using an object */
147-
public function getStringObject()
148-
{
149-
$object = ...; // an object which has a __toString() method
150-
151-
return $object;
152-
}
153-
}
48+
Options
49+
.......
50+
51+
* ``method``: **required** Method used to return the route name/path/path
52+
elements.
53+
* ``slugify``: If the return value should be slugified, default is ``true``.
15454

15555
content_datetime
15656
~~~~~~~~~~~~~~~~
15757

158-
The ``content_datettime`` provider will provide a path from a ``DateTime``
58+
The ``content_datetime`` provider will provide a path from a ``DateTime``
15959
object provided by a designated method on the content document.
16060

16161
.. configuration-block::
16262

16363
.. code-block:: yaml
16464
165-
provider: [content_datetime, { method: getDate, date_format: Y/m/d }]
65+
# src/Acme/ForumBundle/Resources/config/routing_auto.yml
66+
Acme\ForumBundle\Document\Topic:
67+
url_schema: /blog/{date}/my-post
68+
token_providers:
69+
date: [content_datetime, {method: getDate} ]
70+
71+
.. code-block: xml
16672
167-
.. code-block:: xml
73+
<?xml version="1.0" ?>
74+
<!-- src/Acme/ForumBundle/Resources/config/routing_auto.xml -->
75+
<auto-mapping xmlns="http://cmf.symfony.com/schema/routing_auto">
76+
<mapping class="Acme\ForumBundle\Document\Topic" url-schema="/blog/{date}/my-post">
77+
<token-provider token="date" name="content_datetime">
78+
<option name="method">getDate</option>
79+
</token-provider>
80+
</mapping>
81+
</auto-mapping>
16882
169-
<provider name="content_datetime">
170-
<option name="method" value="getDate" />
171-
<option name="date_format" value="Y/m/d" />
172-
</provider>
83+
Options
84+
.......
17385

174-
.. code-block:: php
86+
* ``method``: **required** Method used to return the route name/path/path
87+
elements.
88+
* ``slugify``: If the return value should be slugified, default is ``true``.
89+
* ``date_format``: Any date format accepted by the `DateTime` class, default
90+
``Y-m-d``.
17591

176-
array(
177-
// ...
178-
'provider' => array('content_datetime', array(
179-
'method' => 'getDate',
180-
'date_format' => 'Y/m/d',
181-
)),
182-
);
92+
content_locale
93+
~~~~~~~~~~~~~~
18394

184-
.. note::
95+
The ``content_locale`` provider will provide the locale (e.g. ``fr``, ``de``,
96+
etc) from the subject object. It ultimately it determines the locale from the
97+
storage specific adapter - so it is dependent upon the adapter supporting this
98+
feature.
18599

186-
This method extends `content_method`_ and inherits the slugify feature.
187-
Internally, it returns a string using the `DateTime->format()` method. This
188-
means that you can specify your date in anyway you like and it will be
189-
automatically slugified. Also, by adding path separators in the
190-
``date_format`` you are effectively creating routes for each date component
191-
as slugify applies to **each element** of the path.
100+
.. configuration-block::
101+
102+
.. code-block:: yaml
103+
104+
# src/Acme/ForumBundle/Resources/config/routing_auto.yml
105+
Acme\ForumBundle\Document\Topic:
106+
url_schema: /blog/{locale}/my-post
107+
token_providers:
108+
locale: [content_locale ]
109+
110+
.. code-block: xml
111+
112+
<?xml version="1.0" ?>
113+
<!-- src/Acme/ForumBundle/Resources/config/routing_auto.xml -->
114+
<auto-mapping xmlns="http://cmf.symfony.com/schema/routing_auto">
115+
<mapping class="Acme\ForumBundle\Document\Topic" url-schema="/blog/{locale}/my-post">
116+
<token-provider token="locale" name="content_locale" />
117+
</mapping>
118+
</auto-mapping>
192119
193120
Options
194121
.......
195122

196123
* ``method``: **required** Method used to return the route name/path/path
197124
elements.
198125
* ``slugify``: If the return value should be slugified, default is ``true``.
199-
* ``date_format``: Any date format accepted by the `DateTime` class, default
126+
* ``locale_format``: Any locale format accepted by the `DateTime` class, default
200127
``Y-m-d``.

0 commit comments

Comments
 (0)