Skip to content

mention CMF ChainRouter, restructure documentation for extending routing #6020

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

mention CMF ChainRouter, restructure documentation for extending routing #6020

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion book/routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1526,6 +1526,6 @@ should also be used to generate URLs.
Learn more from the Cookbook
----------------------------

* :doc:`/cookbook/routing/scheme`
* :doc:`/cookbook/routing/index`

.. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle
2 changes: 2 additions & 0 deletions cookbook/map.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,8 @@
* :doc:`/cookbook/routing/custom_route_loader`
* :doc:`/cookbook/routing/redirect_trailing_slash`
* :doc:`/cookbook/routing/extra_information`
* :doc:`/cookbook/routing/extending_routing`
* :doc:`/cookbook/routing/multiple_routers`

* :doc:`Security Authentication (Identifying/Logging in the User) </cookbook/security/index>`

Expand Down
15 changes: 15 additions & 0 deletions cookbook/routing/extending_routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
Extending the Routing System
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is the overview of the subsection on extending the routing, trying to give an overview.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea, but I think adding articles to the cookbook and putting "how do I...?" entires in the cookbook TOC is much more useful - e.g. potentially "How do I convert controller arguments to objects" - which would be something very short pointing to FrameworkExtraBundle. That's arguably overkill... but more findable.

============================

The routing system has several extension points:

* You can use the ``@ParamConverter`` mechanism of FrameworkExtraBundle_
to convert controller arguments into objects.
* You can write :doc:`custom route loaders <custom_route_loader>`;
* You can write your own ``Router`` instance and
:doc:`combine several routers <multiple_routers>`;
* Some bundles overwrite core routing services to alter the route loading
process, e.g. JmsI18nRoutingBundle_.

.. _FrameworkExtraBundle: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
.. _JMSI18nRoutingBundle: https://github.com/schmittjoh/JMSI18nRoutingBundle
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should link here: http://jmsyst.com/bundles/JMSI18nRoutingBundle - the GitHub page just points you there.

4 changes: 3 additions & 1 deletion cookbook/routing/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ Routing
redirect_in_config
method_parameters
service_container_parameters
custom_route_loader
redirect_trailing_slash
extra_information
extending_routing
custom_route_loader
multiple_routers
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if its ok to add multiple levels of navigation here, but i think it would make sense. also not sure if this is the right syntax for rst.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't work in the table of contents. You will probably want to update /cookbook/routing/map.rst.inc instead. But I am not sure if the symfony.com theme is able to render that properly (the platform.sh preview will tell us though).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is no /cookbook/routing/map.rst.inc file i think. do you have an idea how we should do this? or should we give up on making this a sub-group and just cram it into one article? or a series that repeat part of the title: "Extending Routing: ..."?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh sorry about that. :( The right file is /cookbook/map.rst.inc.

Copy link
Contributor Author

@dbu dbu Dec 18, 2015 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

19 changes: 19 additions & 0 deletions cookbook/routing/multiple_routers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
.. index::
single: Routing; Multiple Routers

Using the Symfony CMF ChainRouter to Combine Multiple Routers
=============================================================

The Symfony CMF ``ChainRouter`` allows to use more than one router. A main
use case is to keep the :doc:`default symfony routing system </book/routing>`
available when writing a custom router.

.. caution::

If you simply need a way to load routes determined in a different
way, using :doc:`a custom route loader <custom_route_loader>` is
simpler than writing your own controller.
Writing a custom controller is justified when the routes can not be
statically determined.

TODO: a bit of code examples?
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i need to wrap this up, if we agree that this PR is going in the right direction.