44The Router
55==========
66
7- Welcome at the third part of the Quick Tour. You seem to have fallen in love
8- with the CMF, getting this far! And that's a good thing, as you will learn
9- about the backbone of the CMF in this chapter: The Router.
7+ Welcome at the third part of the Quick Tour. Well done, making it this far!
8+ And that's a good thing, as you will learn about the backbone of the CMF in
9+ this chapter: The Router.
1010
1111The Backbone of the CMF
1212-----------------------
1313
14- As already said, the router is central to the CMF. To understand this, let us
14+ The router is central to the CMF. To understand this, let us
1515look at what a CMS tries to do. In a normal Symfony application, a route
1616refers to a controller which can handle a specific entity. Another route
1717refers to another controller which can handle another entity. This way, a
1818route is tied to a controller. In fact, using the Symfony core you are also
19- limited at this.
19+ limited by this pattern .
2020
21- But if you look at the base of a CMS, it only needs to handle 1 type of
21+ But if you look at the base of a CMS, it only needs to handle one type of
2222entity: The Content. So most of the routes don't have to be tied to a
2323controller anymore, as only one controller is needed. The Route has to be tied
24- to a specific Content object, which - on its side - can reference a specific
24+ to a specific Content object, which - on its side - may need a specific
2525template and controller.
2626
27- Other parts of the CMF are also related to the Router. To give 2 examples: The
27+ Other parts of the CMF are also related to the Router. Two examples: The
2828menu is created by generating specific routes using the Router and the blocks
2929are displayed to specific routes (as they are related to a template).
3030
@@ -35,10 +35,8 @@ In the first chapter, you have already learned that routes are loaded from the
3535database using a special ``DynamicRouter ``. This way, not all routes need to
3636be loaded each request.
3737
38- Matching routes from a PHPCR is really simple. If you remember the previous
39- chapter, you know that you can get the ``quick_tour `` page from PHPCR using
40- ``/cms/routes/en/quick-tour ``. The URL to get this page is ``en/quick-tour ``. Some
41- other examples:
38+ Matching routes from a PHPCR is straightforward: The router takes the request
39+ path and looks for a document with that path. Some examples:
4240
4341.. code-block :: text
4442
@@ -58,164 +56,62 @@ all routes are prefixed with ``/cms/routes``.
5856You see that a route like ``/company/team ``, which consist of 2 "path units",
5957has 2 documents in the PHPCR tree: ``company `` and ``team ``.
6058
61- Chaining multiple Routers
62- -------------------------
63-
64- You may need to have several prefixes or several routes. For instance, you may
65- want to use both the ``DynamicRouter `` for the page routes, but also the
66- static routing files from Symfony for your custom logic. To be able to do that,
67- the CMF provides a ``ChainRouter ``. This router chains over multiple router
68- and stops whenever a router matches.
69-
70- By default, the ``ChainRouter `` overrides the Symfony router and only has the
71- core router in its chain. You can add more routers to the chain in the
72- configuration or by tagging the router services with ``cmf_routing.router ``.
73-
7459Creating a new Route
7560--------------------
7661
77- Now you know the basics of routing, you can add a new route to the tree. In
78- the configuration file, configure a new chain router so that you can put your
79- new routes in ``/cms/routes ``:
80-
81- .. configuration-block ::
82-
83- .. code-block :: yaml
84-
85- # app/config/config.yml
86-
87- # ...
88- cmf_routing :
89- chain :
90- routers_by_id :
91- # the standard DynamicRouter
92- cmf_routing.dynamic_router : 200
93-
94- # the core symfony router
95- router.default : 100
96- dynamic :
97- persistence :
98- phpcr :
99- route_basepaths :
100- - /cms/routes
101- # /cms/routes is the default base path, the above code is
102- # equivalent to:
103- # phpcr: true
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-
112- <config xmlns =" http://cmf.symfony.com/schema/dic/routing"
113- <chain >
114- <!-- the standard DynamicRouter -->
115- <router-by-id id =" cmf_routing.dynamic_router" router-by-id >
116-
117- <!-- the core symfony router -->
118- <router-by-id id =" router.default" router-by-id >
119- </chain >
120-
121- <dynamic >
122- <persistence >
123- <phpcr >
124- <route-basepath >/cms/routes</route-basepath >
125- </phpcr >
126- <!-- /cms/routes is the default base path, the above
127- code is equivalent to:
128- <phpcr />
129- --->
130- </persistence >
131- </dynamic >
132- </config >
133- </container >
134-
135- code-block :: php
136-
137- // app/config/config.php
138- $container->loadFromExtension('cmf_routing', [
139- 'chain' => [
140- 'routers_by_id' => [
141- // the standard DynamicRouter
142- 'cmf_routing.dynamic_router' => 200,
143-
144- // the core symfony router
145- 'router.default' => 100,
146- ],
147- ],
148- 'dynamic' => [
149- 'persistence' => [
150- 'phpcr' => [
151- 'route_basepaths' => '/cms/routes',
152- ],
153- /* /cms/routes is the default base path, the above code is
154- equivalent to:
155- 'phpcr' => true,
156- */
157- ],
158- ],
159- ]);
160-
161- Route `` to the tree using Doctrine::
162-
163- // src/AppBundle/DataFixtures/PHPCR/LoadExtraRoutingData.php
62+ Now you know the basics of routing, you can add a new route to the tree using
63+ Doctrine::
64+
65+ // src/AppBundle/DataFixtures/PHPCR/LoadQuickTourData.php
16466 namespace AppBundle\DataFixtures\PHPCR;
16567
16668 use Doctrine\Common\Persistence\ObjectManager;
16769 use Doctrine\Common\DataFixtures\FixtureInterface;
16870 use Doctrine\Common\DataFixtures\OrderedFixtureInterface;
16971 use Doctrine\ODM\PHPCR\DocumentManager;
170-
17172 use PHPCR\Util\NodeHelper;
172-
17373 use Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route;
17474
175- class LoadExtraRoutingData implements FixtureInterface, OrderedFixtureInterface
75+ class LoadQuickTourData implements FixtureInterface, OrderedFixtureInterface
17676 {
177- public function getOrder()
178- {
179- return 21;
180- }
181-
18277 public function load(ObjectManager $documentManager)
18378 {
184- if (!$documentManager instanceof DocumentManager) {
185- $class = get_class($documentManager);
186- throw new \RuntimeException("Fixture requires a PHPCR ODM DocumentManager instance, instance of '$class' given.");
187- }
79+ // static content from model chapter, resulting in $content being defined
80+ // ...
18881
18982 $routesRoot = $documentManager->find(null, '/cms/routes');
190-
19183 $route = new Route();
19284 // set $routesRoot as the parent and 'new-route' as the node name,
19385 // this is equal to:
19486 // $route->setName('new-route');
19587 // $route->setParentDocument($routesRoot);
19688 $route->setPosition($routesRoot, 'new-route');
19789
198- $page = $documentManager->find(null, '/cms/content/quick');
199- $route->setContent($page);
90+ $route->setContent($content);
20091
20192 $documentManager->persist($route); // put $route in the queue
20293 $documentManager->flush(); // save it
20394 }
20495 }
20596
206- Above we implemented the ``OrderedFixtureInterface `` so that our routes were loaded in the correct sequence relative to other fixtures.
207-
20897Now execute the ``doctrine:phpcr:fixtures:load `` command again.
20998
21099This creates a new node called ``/cms/routes/new-route ``, which will display
211100our ``quick_tour `` page when you go to ``/new-route ``.
212101
213- .. tip ::
102+ .. image :: ../_images/quick_tour/the-router-new-page.png
214103
215- When doing this in a real app, you may want to use a ``RedirectRoute ``
216- instead.
104+ Chaining multiple Routers
105+ -------------------------
106+
107+ Usually, you want to use both the ``DynamicRouter `` for the editable routes,
108+ but also the static routing files from Symfony for your custom logic. To be
109+ able to do that, the CMF provides a ``ChainRouter ``. This router tries each
110+ registered router and stops on the first router that returns a match.
217111
218- .. TODO write something about templates_by_class, etc.
112+ By default, the ``ChainRouter `` overrides the Symfony router and only has the
113+ core and dynamic router in its chain. You can add more routers to the chain in the
114+ configuration or by tagging the router services with ``cmf_routing.router ``.
219115
220116Final Thoughts
221117--------------
@@ -225,7 +121,7 @@ basics of the Symfony CMF. First, you have learned about the Request flow and
225121quickly learned each new step in this process. After that, you have learned
226122more about the default storage layer and the routing system.
227123
228- The Routing system is created together with some developers from Drupal8 . In
124+ The Routing system is created together with some developers from Drupal 8 . In
229125fact, Drupal 8 uses the Routing component of the Symfony CMF. The Symfony CMF
230126also uses some 3rd party bundles from others and integrated them into PHPCR.
231127In :doc: `the next chapter <the_third_party_bundles >` you'll learn more about
0 commit comments