55RoutingAutoBundle
66=================
77
8- .. include :: _not-stable-caution.rst.inc
9-
108 The RoutingAutoBundle allows you to define automatically created routes for
119 documents.
1210
11+ .. include :: ../_not-stable-caution.rst.inc
12+
1313This implies a separation of the ``Route `` and ``Content `` documents. If your
1414needs are simple this bundle may not be for you and you should have a look at
15- :doc: `the SimpleCmsBundle <simple_cms/introduction >`.
15+ :doc: `the SimpleCmsBundle <../ simple_cms/introduction
1616
1717Installation
1818------------
@@ -24,13 +24,14 @@ Features
2424--------
2525
2626Imagine you are going to create a forum application that has two routeable
27- contents, a category and the topics for that forum . These documents are called
27+ content documents - a category and the topics. These documents are called
2828``Category `` and ``Topic ``, and they are called *content documents *.
2929
30- If you create a new category with the title "My New Category", the RoutingAutoBundle
31- automatically create the route ``/forum/my-new-cateogry ``. For each new ``Topic ``
32- it could create a route like ``/forum/my-new-category/my-topic-title ``. This URL
33- resolves to a special type of route that is called an *auto route *.
30+ If you create a new category with the title "My New Category", the
31+ RoutingAutoBundle will automatically create the route
32+ ``/forum/my-new-cateogry ``. For each new ``Topic `` it could create a route
33+ like ``/forum/my-new-category/my-new-topic ``. This URL resolves to a special
34+ type of route that is called an *auto route *.
3435
3536By default, when you update a content document that has an auto route, the
3637corresponding auto route will also be updated. When deleting a content
@@ -70,25 +71,23 @@ Usage
7071The diagram below shows a fictional URL for a forum topic. The first 6 elements
7172of the URL are called the *content path *. The last element is called the *content name *.
7273
73- -- TODO update this image!!
74+ .. image :: ../../_images/bundles/routing_auto_post_schema.png
7475
75- .. image :: ../_images/bundles/routing_auto_post_schema.png
76-
77- The content path is further broken down into *route stacks * and *routes *. A
78- route stack is a group of routes and routes are simply documents in the PHPCR
79- tree.
76+ The content path is further broken down into *path units * and *path elements *. A
77+ path unit is a group of path elements and path elements are simply documents
78+ in the PHPCR tree.
8079
8180.. note ::
8281
83- Although routes can be of any document class in this case, only objects
84- which extend the :class: `Symfony\\ Component\\ Routing\\ Route ` object will
85- be considered when matching a URL.
82+ Although path elements can be of any document class in this case, only
83+ objects which extend the :class: `Symfony\\ Component\\ Routing\\ Route `
84+ object will be considered when matching a URL.
8685
8786 The default behavior is to use ``Generic `` documents when generating a content
8887 path, and these documents will result in a 404 when accessed directly.
8988
90- Internally, each route stack is built up by a *builder unit *. Builder units
91- contain one *path provider * class and two actions classes one action to take
89+ Internally, each path unit is built up by a *builder unit *. Builder units
90+ contain one *path provider * class and two actions classes - one action to take
9291if the provided path exists in the PHPCR tree, the other if it does not. The
9392goal of each builder unit is to generate a path and then provide a route
9493object for each element in that path.
@@ -105,25 +104,19 @@ The configuration for the example above could be as follows:
105104
106105 Acme\ForumBundle\Document\Topic
107106 content_path :
108- # corresponds first route stack in diagram: my-forum
107+ # corresponds first path unit in diagram: my-forum
109108 forum_path :
110109 provider : [specified, { path: my-form }]
111110 exists_action : use
112111 not_exists_action : create
113112
114- # corresponds second route stack in diagram: my-category
113+ # corresponds second path unit in diagram: my-category
115114 category_path :
116115 provider : [content_object, { method: getCategory }]
117116 exists_action : use
118117 not_exists_action : throw_exception
119118
120- # corresponds third route stack in diagram: 2013/04/06
121- date :
122- provider : [content_datetime, { method: getPublishedDate } ]
123- exists_action : use
124- not_exists_action : create
125-
126- # corresponds to the content name: my-topic-title
119+ # corresponds to the content name: my-new-topic
127120 content_name :
128121 provider : [content_method, { method: getTitle }]
129122 exists_action : [auto_increment, { pattern: -%d }]
@@ -140,32 +133,25 @@ The configuration for the example above could be as follows:
140133 <mapping class =" Acme\ForumBundle\Document\Topic"
141134
142135 <content-path >
143- <!-- corresponds first route stack in diagram: my-forum -->
136+ <!-- corresponds first path unit in diagram: my-forum -->
144137 <path-unit name =" forum_path"
145138 <provider name =" specified"
146139 <option name =" path" value =" my-forum"
147140 </provider >
148141 </path-unit >
149142
150- <!-- corresponds second route stack in diagram: my-category -->
143+ <!-- corresponds second path unit in diagram: my-category -->
151144 <path-unit name =" category_path"
152145 <provider name =" content_object"
153146 <option name =" method" value =" getCategory"
154147 </provider >
155148 <exists-action strategy =" use"
156149 <not-exists-action strategy =" throw_exception"
157150 </path-unit >
158-
159- <!-- corresponds third route stack in diagram: 2013/04/06 -->
160- <path-unit name =" date"
161- <provider name =" content_datetime"
162- <option name =" method" value =" getPublishedDate"
163- </provider >
164- </path-unit >
165151 </content-path >
166152
167153
168- <!-- corresponds to the content name: my-topic-title -->
154+ <!-- corresponds to the content name: my-new-topic -->
169155 <content-name >
170156 <provider name =" content_method"
171157 <option name =" method" value =" getTitle"
@@ -186,7 +172,7 @@ The configuration for the example above could be as follows:
186172 'mappings' => array(
187173 'Acme\ForumBundle\Document\Topic' => array(
188174 'content_path' => array(
189- // corresponds first route stack in diagram: my-forum
175+ // corresponds first path unit in diagram: my-forum
190176 'forum_path' => array(
191177 'provider' => array('specified', array(
192178 'path' => 'my-forum',
@@ -195,26 +181,17 @@ The configuration for the example above could be as follows:
195181 'not_exists_action' => 'create',
196182 ),
197183
198- // corresponds second route stack in diagram: my-category
184+ // corresponds second path unit in diagram: my-category
199185 'category_path' => array(
200186 'provider' => array('content_object', array(
201187 'method' => 'getCategory',
202188 )),
203189 'exists_action' => 'use',
204190 'not_exists_action' => 'throw_exception',
205191 ),
206-
207- // corresponds third route stack in diagram: 2013/04/06
208- 'date' => array(
209- 'provider' => array('content_datetime', array(
210- 'method' => 'getPublishedDate',
211- )),
212- 'exists_action' => 'use',
213- 'not_exists_action' => 'create',
214- ),
215192 ),
216193
217- // corresponds to the content name: my-topic-title
194+ // corresponds to the content name: my-new-topic
218195 'content_name' => array(
219196 'provider' => array('content_method', array(
220197 'method' => 'getTitle',
0 commit comments