diff --git a/bundles/_partials/sonata_admin_enabled.rst.inc b/bundles/_partials/sonata_admin_enabled.rst.inc new file mode 100644 index 00000000..95d13f8d --- /dev/null +++ b/bundles/_partials/sonata_admin_enabled.rst.inc @@ -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 diff --git a/bundles/routing/configuration.rst b/bundles/routing/configuration.rst index 0970ce61..bb5b2bfb 100644 --- a/bundles/routing/configuration.rst +++ b/bundles/routing/configuration.rst @@ -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. @@ -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 `. @@ -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`` ....................... @@ -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:: @@ -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`` ............... @@ -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 @@ -350,9 +346,6 @@ disables the limit entirely. /cms/routes @@ -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, ], ], @@ -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`` ********************** @@ -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 `. +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 `. ``orm`` """"""" @@ -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: @@ -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 diff --git a/bundles/routing/dynamic.rst b/bundles/routing/dynamic.rst index 43c500d0..536e3f40 100644 --- a/bundles/routing/dynamic.rst +++ b/bundles/routing/dynamic.rst @@ -305,7 +305,7 @@ omit setting a content document on the route document. per locale, all referencing the same multilingual content instance. The ``ContentAwareGenerator`` respects the ``_locale`` when generating routes from content instances. When resolving the route, the ``_locale`` gets - into the request and is picked up by the Symfony2 locale system. + into the request and is picked up by the Symfony locale system. Make sure you configure the valid locales in the configuration so that the bundle can optimally handle locales. The @@ -322,79 +322,6 @@ omit setting a content document on the route document. create one route per language for the same content. The route generator will pick the correct route if available. -Sonata Doctrine PHPCR-ODM Admin classes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If the SonataDoctrinePHPCRAdminBundle_ is loaded in the application kernel, -route and redirect route documents can be administrated in sonata admin. For -instructions on how to configure Sonata, see `configuring sonata admin`_. - -By default, ``use_sonata_admin`` is automatically set based on whether -SonataDoctrinePHPCRAdminBundle is available, but you can explicitly -disable it to not have it even if sonata is enabled, or explicitly enable to -get an error if Sonata becomes unavailable. - -Sonata admin is using the ``content_basepath`` to show the tree of content to -select the route target. - -The root path to add Routes defaults to the first entry in ``route_basepaths``, -but you can overwrite this with the ``admin_basepath`` if you need a different -base path. - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - cmf_routing: - dynamic: - persistence: - phpcr: - # use true/false to force using / not using sonata admin - use_sonata_admin: auto - - # used with Sonata Admin to manage content; defaults to %cmf_core.basepath%/content - content_basepath: ~ - - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('cmf_routing', [ - 'dynamic' => [ - 'persistence' => [ - 'phpcr' => [ - // use true/false to force using / not using sonata admin - 'use_sonata_admin' => 'auto', - - // used with Sonata Admin to manage content; defaults to %cmf_core.basepath%/content - 'content_basepath' => null, - ], - ], - ], - ]); - .. _bundle-routing-entity: Doctrine ORM integration @@ -417,7 +344,7 @@ URL generation with the DynamicRouter Apart from matching an incoming request to a set of parameters, a Router is also responsible for generating an URL from a route and its parameters. The ``DynamicRouter`` adds more power to the -`URL generating capabilities of Symfony2`_. +`URL generating capabilities of Symfony`_. .. tip:: @@ -585,130 +512,6 @@ documents. You need to configure the route enhancer for this interface: ], ]); -RouteReferrersInterface Sonata Admin Extension ----------------------------------------------- - -This bundle provides an extension to edit referring routes for content that -implements the ``RouteReferrersInterface``. - -To enable the extensions in your admin classes, simply define the extension -configuration in the ``sonata_admin`` section of your project configuration: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - sonata_admin: - # ... - extensions: - cmf_routing.admin_extension.route_referrers: - implements: - - Symfony\Cmf\Component\Routing\RouteReferrersInterface - - .. code-block:: xml - - - - - - - Symfony\Cmf\Component\Routing\RouteReferrersInterface - - - - - .. code-block:: php - - // app/config/config.php - use Symfony\Cmf\Bundle\Routing\RedirectRouteInterface; - - $container->loadFromExtension('sonata_admin', [ - 'extensions' => [ - 'cmf_routing.admin_extension.route_referrers' => [ - 'implements' => [ - RouteReferrersInterface::class, - ], - ], - ], - ]); - -See the `Sonata Admin extension documentation`_ for more information. - -FrontendLink Sonata Admin Extension ------------------------------------ - -This bundle provides an extension to show a button in Sonata Admin, which links on the actual -frontend representation of a document. Documents which implement the ``RouteReferrersReadInterface`` -and Routes itself (``Symfony\Component\Routing\Route``) are supported. - -To enable the extension in your admin classes, simply define the extension -configuration in the ``sonata_admin`` section of your project configuration: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - sonata_admin: - # ... - extensions: - cmf_routing.admin_extension.frontend_link: - implements: - - Symfony\Cmf\Component\Routing\RouteReferrersReadInterface - extends: - - Symfony\Component\Routing\Route - - .. code-block:: xml - - - - - - - Symfony\Cmf\Component\Routing\RouteReferrersReadInterface - Symfony\Component\Routing\Route - - - - .. code-block:: php - - // app/config/config.php - use Symfony\Cmf\Component\Routing\RouteReferrersReadInterface; - use Symfony\Component\Routing\Route; - - $container->loadFromExtension('sonata_admin', [ - 'extensions' => [ - 'cmf_routing.admin_extension.frontend_link' => [ - 'implements' => [ - RouteReferrersReadInterface::class, - ], - 'extends' => [ - Route::class, - ], - ], - ], - ]); - -See the `Sonata Admin extension documentation`_ for more information. - -Styling -~~~~~~~ - -Feel free to use your own styles. The frontend link button can be customized -using the following example CSS rules: - -.. code-block:: css - - .sonata-admin-menu-item a.sonata-admin-frontend-link { - font-weight: bold; - } - - .sonata-admin-menu-item a.sonata-admin-frontend-link:before { - font-family: FontAwesome; - content: "\f08e"; - } - Customize the DynamicRouter --------------------------- @@ -718,8 +521,5 @@ Read on in the chapter :doc:`customizing the dynamic router ` .. _`CMF Routing component`: https://github.com/symfony-cmf/Routing .. _`Doctrine ORM`: http://www.doctrine-project.org/projects/orm.html .. _`PHPCR-ODM`: http://www.doctrine-project.org/projects/phpcr-odm.html -.. _`Sonata Admin extension documentation`: https://sonata-project.org/bundles/admin/master/doc/reference/extensions.html -.. _`URL generating capabilities of Symfony2`: https://symfony.com/doc/current/book/routing.html#generating-urls -.. _SonataDoctrinePHPCRAdminBundle: https://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/index.html -.. _`configuring sonata admin`: https://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/reference/configuration.html +.. _`URL generating capabilities of Symfony`: https://symfony.com/doc/current/book/routing.html#generating-urls .. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle diff --git a/bundles/routing/introduction.rst b/bundles/routing/introduction.rst index 5e88c9ff..24c2cd98 100644 --- a/bundles/routing/introduction.rst +++ b/bundles/routing/introduction.rst @@ -14,11 +14,11 @@ RoutingBundle The ``ChainRouter`` is meant to replace the default Symfony Router. All it does is manage a prioritized list of routers and try to match requests and generate URLs with all of them. One of the routers in that chain can of course -be the default router so you can still use the Symfony2 standard way of +be the default router so you can still use the Symfony standard way of specifying routes where it makes sense. Additionally, this bundle delivers useful router implementations. It provides -the ``DynamicRouter`` that routes based on a custom loader logic for Symfony2 +the ``DynamicRouter`` that routes based on a custom loader logic for Symfony Route objects. The provider can be implemented using a database. This bundle provides default implementations for Doctrine PHPCR-ODM and Doctrine ORM. @@ -88,7 +88,7 @@ will look like this ->addTag('router', ['priority' => 300]) ; -See also official Symfony2 `documentation for DependencyInjection tags`_ +See also official Symfony `documentation for DependencyInjection tags`_ Sections -------- @@ -106,7 +106,7 @@ For more information on Routing in the Symfony CMF, please refer to: * The :doc:`routing introduction chapter <../../book/routing>` of the book; * The :doc:`routing component documentation <../../components/routing/introduction>` for implementation details of the routers; -* Symfony2's `Routing`_ component documentation. +* Symfony's `Routing`_ component documentation. .. _`with composer`: https://getcomposer.org .. _`symfony-cmf/routing-bundle`: https://packagist.org/packages/symfony-cmf/routing-bundle diff --git a/bundles/sonata_phpcr_admin_integration/routing.rst b/bundles/sonata_phpcr_admin_integration/routing.rst index c1f201a0..b64670b8 100644 --- a/bundles/sonata_phpcr_admin_integration/routing.rst +++ b/bundles/sonata_phpcr_admin_integration/routing.rst @@ -1,2 +1,213 @@ RoutingBundle ============= + +Both content routes and redirect routes can be administrated. When creating +content routes, a tree of content documents is shown. The administrator can +select a content document to bind to the route. This tree is configured with +the ``content_basepath`` setting. + +The root path to add routes defaults to the first entry in ``route_basepaths`` +configuration of the RoutingBundle. You can overwrite this with the +``basepath`` option if you need a different base path. + +Routes can also be handled in the content admin page. The admin integration +provides an admin extension that allows adding routes to any route aware +objects. Another extension provides a frontend link on all admin pages that +objects that refer to routes. + +Configuration +------------- + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + cmf_sonata_phpcr_admin_integration: + bundles: + routing: + enabled: false + basepath: ~ + content_basepath: ~ + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('cmf_sonata_phpcr_admin_integration', [ + 'bundles' => [ + 'routing' => [ + 'enabled' => false, + 'basepath' => null, + 'content_basepath' => null, + ], + ], + ]; + +.. include:: ../_partials/sonata_admin_enabled.rst.inc + +The routing admins are ``cmf_sonata_phpcr_admin_integration.routing.route_admin`` +and ``cmf_sonata_phpcr_admin_integration.routing.redirect_route_admin``. + +``basepath`` +************ + +**type**: ``string`` **default**: first value of ``cmf_routing.dynamic.persistence.phpcr.route_basepaths`` + +The path at which to create routes with Sonata admin. There can be additional +route basepaths for the routing, but you will need to set up separate admin +services to edit those. + +``content_basepath`` +******************** + +**type**: ``string`` **default**: ``/ or cmf_content.persistence.phpcr.content_basepath`` + +The basepath for content objects in the PHPCR tree. This information is used +to offer the correct subtree to select the target content document for a route. + +If the :doc:`ContentBundle <../content/introduction>` is registered, this will +default to ``cmf_content.persistence.phpcr.content_basepath``. Otherwise, it +defaults to ``/`` to show the whole tree. + +RouteReferrersInterface Admin Extension +--------------------------------------- + +This bundle provides an extension to edit referring routes for content that +implements the ``RouteReferrersInterface``. + +To enable the extensions in your admin classes, define the extension +configuration in the ``sonata_admin`` section of your project configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + sonata_admin: + # ... + extensions: + cmf_sonata_phpcr_admin_integration.routing.extension.route_referrers: + implements: + - Symfony\Cmf\Component\Routing\RouteReferrersInterface + + .. code-block:: xml + + + + + + + Symfony\Cmf\Component\Routing\RouteReferrersInterface + + + + + .. code-block:: php + + // app/config/config.php + use Symfony\Cmf\Bundle\Routing\RedirectRouteInterface; + + $container->loadFromExtension('sonata_admin', [ + 'extensions' => [ + 'cmf_sonata_phpcr_admin_integration.routing.extension.route_referrers' => [ + 'implements' => [ + RouteReferrersInterface::class, + ], + ], + ], + ]); + +See the `Sonata Admin extension documentation`_ for more information. + +FrontendLink Admin Extension +---------------------------- + +This bundle provides an extension to show a button in Sonata Admin, which links +to the frontend representation of a document. Documents which implement the +``RouteReferrersReadInterface`` and Routes themselves are supported. + +To enable the extension in your admin classes, define the extension +configuration in the ``sonata_admin`` section of your project configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + sonata_admin: + # ... + extensions: + cmf_sonata_phpcr_admin_integration.routing.extension.frontend_link: + implements: + - Symfony\Cmf\Component\Routing\RouteReferrersReadInterface + extends: + - Symfony\Component\Routing\Route + + .. code-block:: xml + + + + + + + Symfony\Cmf\Component\Routing\RouteReferrersReadInterface + Symfony\Component\Routing\Route + + + + .. code-block:: php + + // app/config/config.php + use Symfony\Cmf\Component\Routing\RouteReferrersReadInterface; + use Symfony\Component\Routing\Route; + + $container->loadFromExtension('sonata_admin', [ + 'extensions' => [ + 'cmf_sonata_phpcr_admin_integration.routing.extension.frontend_link' => [ + 'implements' => [ + RouteReferrersReadInterface::class, + ], + 'extends' => [ + Route::class, + ], + ], + ], + ]); + +See the `Sonata Admin extension documentation`_ for more information. + +Styling the Frontend Link +************************* + +The frontend link button can be customized using the +``.sonata-admin-frontend-link`` selector. For instance, to show a link icon and +make the label bold, use the following CSS: + +.. code-block:: css + + .sonata-admin-menu-item a.sonata-admin-frontend-link { + font-weight: bold; + } + + .sonata-admin-menu-item a.sonata-admin-frontend-link:before { + font-family: FontAwesome; + content: "\f08e"; + } + +.. _`Sonata Admin extension documentation`: https://sonata-project.org/bundles/admin/master/doc/reference/extensions.html