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

cleanup routing documentation #814

Merged
merged 2 commits into from
Feb 6, 2017
Merged

cleanup routing documentation #814

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ab4ad8
cleanup routing documentation
dbu Feb 3, 2017
68909bc
A quick review of the RoutingBundle docs
wouterj Feb 4, 2017
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
15 changes: 15 additions & 0 deletions bundles/_partials/sonata_admin_enabled.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
``enabled``
***********

**type**: ``bool`` **default**: ``false``

If ``true``, the admin classes and extensions of this package are loaded and
available for Sonata Admin.

.. tip::

If you do not see this admin on the Sonata dashboard, you need to configure
the dashboard to show the admin service in question. Read more about this
in `the Sonata Admin documentation`_.

.. _the Sonata Admin documentation: https://sonata-project.org/bundles/admin/3-x/doc/reference/dashboard.html
104 changes: 24 additions & 80 deletions bundles/routing/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Configuration

**prototype**: ``array`` **default**: ``{ router.default: 100 }``

This defines the routers to use in the chain. By default, only the Symfony2
This defines the routers to use in the chain. By default, only the Symfony
router is used. The key is the name of the service and the value is the
priority. The chain is sorted from the highest to the lowest priority.

Expand Down Expand Up @@ -72,9 +72,9 @@ To add the ``DynamicRouter``, use the following configuration:

**type**: ``Boolean`` **default**: ``true``

If this option is set to ``false``, the default Symfony2 router will *not* be
If this option is set to ``false``, the default Symfony router will *not* be
overridden by the ``ChainRouter``. By default, the ``ChainRouter`` will
override the default Symfony2 router, but it will pass all requests to the
override the default Symfony router, but it will pass all requests to the
default router, because :ref:`no other routers were set <reference-config-routing-chain_routers>`.


Expand Down Expand Up @@ -142,10 +142,9 @@ defaults to ``cmf_content.controller:indexAction``.

**type**: ``string`` **default**: value of ``generic_controller``

The default controller to use if none of the enhancers found a controller. The
value is the name of a controller using either the
``AppBundle::Page::index`` or ``app.page_controller:indexAction``
notation.
The default controller to use if none of the enhancers found a controller.
Accepts any valid Symfony controller reference.


``controllers_by_type``
.......................
Expand Down Expand Up @@ -203,7 +202,7 @@ This object is checked for being ``instanceof`` the class names in this map.
other extending classes. The order in which the classes are specified, matters.
The first match is taken.

If matched, the controller will be set as ``_controller``, making Symfony2
If matched, the controller will be set as ``_controller``, making Symfony
choose this controller to handle the request.

.. configuration-block::
Expand Down Expand Up @@ -307,10 +306,10 @@ setting is set as controller.

**type**: ``scalar``, **default**: ``0``

If this value is set to a number bigger than 0, the routes from the database
are returned in the ``getRouteCollection``. The limit serves to prevent huge
route lists if you have a large database. Setting the limit to ``false``
disables the limit entirely.
If this value is set to a number bigger than 0, the ``getRouteCollection()``
method returns a collection of routes read from the database. The limit serves
to prevent huge route lists if you have a large database. Setting the limit to
``false`` disables the limit entirely and attempts to return all routes.

``persistence``
...............
Expand All @@ -334,9 +333,6 @@ disables the limit entirely.
route_basepaths:
- /cms/routes
- /cms/simple
content_basepath: /cms/content
admin_basepath: /cms/routes
use_sonata_admin: auto
enable_initializer: true

.. code-block:: xml
Expand All @@ -350,9 +346,6 @@ disables the limit entirely.
<phpcr
enabled="false"
manager-name="null"
content-basepath="/cms/content"
admin-basepath="/cms/routes"
use-sonata-admin="auto"
enable_initializer="true"
>
<route-basepath>/cms/routes</route-basepath>
Expand All @@ -376,9 +369,6 @@ disables the limit entirely.
'/cms/routes',
'/cms/simple',
],
'content_basepath' => '/cms/content',
'admin_basepath' => '/cms/routes',
'use_sonata_admin' => 'auto',
'enable_initializer' => true,
],
],
Expand Down Expand Up @@ -407,46 +397,7 @@ manager_name
A set of paths where routes are located in the PHPCR tree.

If the :doc:`CoreBundle <../core/introduction>` is registered, this will
default to ``%cmf_core.persistence.phpcr.basepath%/routes``. If the
:doc:`SimpleCmsBundle <../simple_cms/introduction>` is registered as well,
the SimpleCmsBundle basepath will be added as an additional route basepath.

``content_basepath``
********************

**type**: ``string`` **default**: ``/cms/content``

The basepath for content objects in the PHPCR tree. This information is used
with the sonata admin to offer the correct subtree to select content documents.

If the :doc:`CoreBundle <../core/introduction>` is registered, this will default to
``%cmf_core.persistence.phpcr.basepath%/content``.

``admin_basepath``
******************

**type**: ``string`` **default**: first value of ``route_basepaths``

The path at which to create routes with Sonata admin. There can be additional
route basepaths, but you will need your own tools to edit those.

``use_sonata_admin``
********************

**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``

If ``true``, the admin classes for the routing are loaded and available for
sonata. If set to ``auto``, the admin services are activated only if the
SonataPhpcrAdminBundle is present.

.. note::

To see the route administration on the sonata dashboard, you still need to
configure it to show the items ``cmf_routing.route_admin`` and
``cmf_routing.redirect_route_admin``.

If the :doc:`CoreBundle <../core/introduction>` is registered, this will
default to the value of ``cmf_core.persistence.phpcr.use_sonata_admin``.
default to ``%cmf_core.persistence.phpcr.basepath%/routes``.

``enable_initializer``
**********************
Expand All @@ -456,18 +407,12 @@ default to the value of ``cmf_core.persistence.phpcr.use_sonata_admin``.
.. versionadded:: 1.3
This configuration option was introduced in RoutingBundle 1.3.

The bundle comes with an initializer that creates the nodes for the ``admin_basepath``
automatically when initializing the repository or loading fixtures. Sometimes this
is not what you want, as the created node is of type 'Generic' and sometimes this
already needs to be a route (for the homepage). Set this to false to disable the
initializer when you create your nodes your self (e.g. using Alice_).

.. caution::

Initializers are forced to be disabled when Sonata Admin is not enabled.
In such cases, you might have multiple route basepaths which are created
by other sources. If the route basepath isn't created by another source,
you have to configure an :ref:`initializer <phpcr-odm-repository-initializers>`.
The bundle comes with an initializer that creates the necessary nodes for all
``route_basepaths`` roots to exist automatically when initializing the
repository or loading fixtures. Sometimes this is not what you want, as the
created node is of type 'Generic' and you might want the document to be a route
(for the homepage). Set this to false to disable the initializer when you
create your nodes yourself in your own :ref:`initializer <phpcr-odm-repository-initializers>`.

``orm``
"""""""
Expand Down Expand Up @@ -564,14 +509,15 @@ priority.

**type**: ``scalar`` **default**: ``null``

To use a content repository when creating URLs, this option can be set to the
content repository service.
One way for routes to specify content is by specifying the content ID. The
responsible route enhancer asks the content repository specified here for the
content. The repository has to implement ``Symfony\Cmf\Component\Routing\ContentRepositoryInterface``.

.. note::

If PHPCR is enabled, it'll automatically use the phpcr content repository.
This can be overridden by this option. ORM doesn't have a content
repository at the moment.
If PHPCR is enabled, this setting will default to a generic PHPCR content
repository that tries to use the content ID as PHPCR path. ORM doesn't have
a content repository at the moment.

.. _reference-config-routing-locales:

Expand Down Expand Up @@ -641,5 +587,3 @@ no locale in their static pattern get the ``auto_locale_pattern`` option set.

This is ignored if there are no ``locales`` configured. It makes no sense to
enable this option when ``match_implicit_locale`` is disabled.

.. _Alice: https://github.com/nelmio/alice
Loading