From 793094494f4858b5b41df02b57668187699d82e7 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Thu, 8 Jun 2017 22:29:47 +0200 Subject: [PATCH] update menu bundle documentation for cmf 2.0 --- bundles/map.rst.inc | 1 - bundles/menu/configuration.rst | 128 +-------- bundles/menu/index.rst | 1 - bundles/menu/introduction.rst | 43 ++- bundles/menu/menu_documents.rst | 9 +- bundles/menu/menu_factory.rst | 33 +-- bundles/menu/menu_provider.rst | 19 +- bundles/menu/sonata_admin.rst | 250 ----------------- bundles/menu/voters.rst | 33 +-- bundles/simple_cms/menus.rst | 5 +- .../content.rst | 57 +++- .../sonata_phpcr_admin_integration/menu.rst | 253 ++++++++++++++++++ 12 files changed, 386 insertions(+), 446 deletions(-) delete mode 100644 bundles/menu/sonata_admin.rst diff --git a/bundles/map.rst.inc b/bundles/map.rst.inc index 8ab19a8a..33829b45 100644 --- a/bundles/map.rst.inc +++ b/bundles/map.rst.inc @@ -29,7 +29,6 @@ library or they introduce a complete new concept. * :doc:`menu/menu_factory` * :doc:`menu/menu_provider` * :doc:`menu/voters` - * :doc:`menu/sonata_admin` * :doc:`menu/configuration` * :doc:`routing/index` diff --git a/bundles/menu/configuration.rst b/bundles/menu/configuration.rst index 72fbf1bc..b5f78fcc 100644 --- a/bundles/menu/configuration.rst +++ b/bundles/menu/configuration.rst @@ -26,16 +26,11 @@ persistence configuration has the following configuration: phpcr: enabled: false menu_basepath: /cms/menu - content_basepath: ~ - prefetch: 10 + content_basepath: /cms/content manager_name: ~ + prefetch: 10 menu_document_class: Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu node_document_class: Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode - use_sonata_admin: ~ - menu_admin_class: Symfony\Cmf\Bundle\MenuBundle\Admin\MenuAdmin - node_admin_class: Symfony\Cmf\Bundle\MenuBundle\Admin\MenuNodeAdmin - admin_recursive_breadcrumbs: true - .. code-block:: xml @@ -47,15 +42,11 @@ persistence configuration has the following configuration: @@ -69,15 +60,11 @@ persistence configuration has the following configuration: 'phpcr' => [ 'enabled' => false, 'menu_basepath' => '/cms/menu', - 'content_basepath' => null, - 'prefetch' => 10, + 'content_basepath' => '/cms/content', 'manager_name' => null, - 'menu_document_class' => null, - 'node_document_class' => null, - 'use_sonata_admin' => 'auto', - 'menu_admin_class' => null, - 'node_admin_class' => null, - 'admin_recursive_breadcrumbs' => true, + 'prefetch' => 10, + 'menu_document_class' => \Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu::class, + 'node_document_class' => \Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode::class, ], ], ]); @@ -109,8 +96,8 @@ the value of ``%cmf_core.persistence.phpcr.basepath%/menu`` **type**: ``string`` **default**: ``/cms/content`` Specifies the path in the PHPCR-ODM document hierarchy under which the -content documents can be found. This is used by the admin class to pre-select -the content branch of the document hierarchy in forms. +content documents can be found. This is used by the sonata admin integration to +know which subtree to show when selecting content for menu nodes. If the :doc:`CoreBundle <../core/introduction>` is registered, this will default to the value of ``%cmf_core.persistence.phpcr.basepath%/content`` @@ -156,33 +143,6 @@ Specifies the document class which should represent a single menu node. This setting is used by the admin class. -``use_sonata_admin`` -"""""""""""""""""""" - -.. include:: ../_partials/persistence_phpcr_sonata_admin_enabled.rst.inc - -``menu_admin_class`` -"""""""""""""""""""" - -**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\MenuBundle\Admin\MenuAdmin`` - -The Sonata admin class to use for the menu. - -``node_admin_class`` -"""""""""""""""""""" - -**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\MenuBundle\Admin\MenuNodeAdmin`` - -The Sonata admin class to use for the menu node. - -``admin_recursive_breadcrumbs`` -""""""""""""""""""""""""""""""" - -**type**: ``boolean`` **default**: ``true`` - -When editing a node, this setting will cause the Sonata admin breadcrumb to -include ancestors of the node being edited. - content_url_generator ~~~~~~~~~~~~~~~~~~~~~ @@ -203,70 +163,6 @@ allow_empty_items Whether menu nodes without URL should be hidden or rendered as text without a link. -Admin Extensions ----------------- - -The ``admin_extensions`` section contains the configurations of the admin extensions that comes with the menu bundle. - -``menu_options`` -~~~~~~~~~~~~~~~~ - -You can configure the menu options extension in this sections. - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - cmf_menu: - # ... - cmf_menu: - admin_extensions: - menu_options: - enabled: auto - advanced: false - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('cmf_menu', [ - 'admin_extensions' => [ - 'menu_options' => [ - 'enabled' => 'auto', - 'advanced' => false, - ], - ], - ]); - -``enabled`` -""""""""""" -**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto`` - -If ``true``, the admin extension is activated. If set to ``auto``, it will be -activated only if the SonataAdminBundle is present. - -``advanced`` -"""""""""""" -**type**: ``boolean`` **default**: ``false`` - -if set to ``true`` it will expose the advanced options in the admin. -To enable this options you need ``BurgovKeyValueFormBundle`` - Voter ----- diff --git a/bundles/menu/index.rst b/bundles/menu/index.rst index 725f3f25..68226b66 100644 --- a/bundles/menu/index.rst +++ b/bundles/menu/index.rst @@ -9,5 +9,4 @@ MenuBundle menu_factory menu_provider voters - sonata_admin configuration diff --git a/bundles/menu/introduction.rst b/bundles/menu/introduction.rst index 691b550d..2b79658c 100644 --- a/bundles/menu/introduction.rst +++ b/bundles/menu/introduction.rst @@ -11,14 +11,15 @@ features: * Render menus stored in the persistence layer; * Generate menu node URLs from linked Content or Route. -Note that only the Doctrine PHPCR-ODM persistence layer is currently supported. +Note that this bundle currently only provides models for the Doctrine PHPCR-ODM +persistence layer. .. caution:: Make sure you understand how the `KnpMenuBundle`_ works when you want to customize the CmfMenuBundle. The CMF menu bundle is just adding - functionality on top of the Knp menu bundle and this documentation is - focused on the additional functionality. + functionality on top of KnpMenuBundle and this documentation is focused on + the additional functionality. Installation ------------ @@ -27,7 +28,7 @@ You can install this bundle `with composer`_ using the `symfony-cmf/menu-bundle`_ package. As the bundle is using the `KnpMenuBundle`_, you need to instantiate that -bundles in addition to the CmfMenuBundle:: +bundle in addition to the CmfMenuBundle:: // app/AppKernel.php @@ -51,19 +52,17 @@ bundles in addition to the CmfMenuBundle:: Creating a Simple Persistent Menu --------------------------------- -A menu created using the KnpMenuBundle is made up of a hierarchy of class -instances implementing ``NodeInterface``. This is also true of a menu created -using MenuBundle documents. +For KnpMenu_, a menu is made up of a hierarchy of objects implementing +``ItemInterface``. KnpMenu provides the concept of factories to create menus +from ``NodeInterface``. This bundle contains a provider to load menu nodes from +PHPCR. -It is recommended that the root document of the menu tree is a ``Menu`` -document, all descendant documents should be ``MenuNode`` instances. +The root document of each menu tree is a ``Menu`` document, all descendant +documents should be ``MenuNode`` instances. The menu roots are placed under the +``cmf_menu.persistence.phpcr.menu_basepath``, which defaults to ``/cms/menu``. -The root document should be a child of the document specified in the configuration -by the parameter ``persistence.phpcr.menu_basepath``, which defaults to ``/cms/menu``. Note -that if this document does not exist it must be created. - -The example below creates a new menu with two items, "Home" and "Contact", -each of which specifies a URI:: +The example below creates a new menu called "Main Menu" with two nodes, "Home" +and "Contact", each of which specifies a URI:: use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode; use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu; @@ -99,8 +98,8 @@ each of which specifies a URI:: .. note:: - When the bundle is registered, it will create the ``/cms/menu`` path - when executing ``doctrine:phpcr:repository:init``. For more information, + When the bundle is registered, it will create the ``menu_basepath`` as part + of the ``doctrine:phpcr:repository:init`` command. For more information, see :ref:`Repository Initializers ` Rendering Menus @@ -136,9 +135,8 @@ will render an unordered list as follows: .. tip:: - Sometimes, the menu is not located within the ``persistence.phpcr.menu_basepath``. - In this case, you can use an absolute path (starting with a forward slash) to render - the menu: + To render a menu that is not a child of the ``menu_basepath``, you can use + an absolute path (starting with a forward slash): .. configuration-block:: @@ -165,9 +163,9 @@ will render an unordered list as follows: .. caution:: If you want to render the menu from Twig, make sure you have not disabled - Twig in the ``knp_menu`` configuration section. + the Twig integration in the ``knp_menu`` configuration section. -For more information see the `rendering menus`_ section of the KnpMenuBundle documentation. +For more information, see the `rendering menus`_ section of the KnpMenuBundle documentation. Read On ------- @@ -176,7 +174,6 @@ Read On * :doc:`menu_factory` * :doc:`menu_provider` * :doc:`voters` -* :doc:`sonata_admin` * :doc:`configuration` .. _`KnpMenu`: https://github.com/knplabs/KnpMenu diff --git a/bundles/menu/menu_documents.rst b/bundles/menu/menu_documents.rst index 8ae067f2..92ae271f 100644 --- a/bundles/menu/menu_documents.rst +++ b/bundles/menu/menu_documents.rst @@ -19,10 +19,11 @@ the KnpMenu component documentation for more information. .. code-block:: php + use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu; use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNodeBase; // find the menu tree root - $mainMenu = $dm->find('Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu', '/cms/menu/main'); + $mainMenu = $dm->find(Menu::class, '/cms/menu/main'); $node = new MenuNodeBase(); $mainMenu->addChild($node); @@ -83,7 +84,7 @@ content document from which the URL can be generated:: The content document can be any document which implements the ``RouteReferrersInterface``. See :ref:`bundles-routing-dynamic-generator`. -This content document will then be passed to the ``ContentAwareFactory`` see +This content document will then be handled by the ``ContentExtension``, see :ref:`URL Generation ` for more details. Link Type Specification @@ -101,8 +102,8 @@ more information. Translation ~~~~~~~~~~~ -The standard menu node supports translation when it is enabled, allowing the -locale to be set via. the ``setLocale`` method:: +The standard menu node supports translation if enabled, allowing the +locale to be set via the ``setLocale`` method:: $menuItem = ...; $menuItem->setLocale('fr'); diff --git a/bundles/menu/menu_factory.rst b/bundles/menu/menu_factory.rst index 64e31e78..3bfb1754 100644 --- a/bundles/menu/menu_factory.rst +++ b/bundles/menu/menu_factory.rst @@ -4,10 +4,11 @@ Menu Factory ============ -The menu documents are only used for persisting the menu data, they are not -actually used when rendering a menu. Menu items are the objects that are needed -to render a menu. A menu factory creates such *menu items* from the *menu -nodes* provided by the menu provider. +The menu node documents are only used for persisting the menu data, they are +not actually used when rendering a menu. The KnpMenu rendering engine needs +menu items. KnpMenu uses a factory to create the *menu items* from the *menu +nodes* provided by the menu provider. The menu factory can be customized with +extensions for additional functionality. .. _bundles_menu_menu_factory_url_generation: @@ -28,7 +29,7 @@ from content objects. The ``content`` menu node option, if specified, must contain something that the content URL generator can work with. When using the :ref:`dynamic router -`, this needs to be a class implementing the +`, this means an instance of ``RouteReferrersInterface``. .. tip:: @@ -40,21 +41,21 @@ content URL generator can work with. When using the :ref:`dynamic router .. versionadded:: 1.2 The ``content_url_generator`` option was introduced in CmfMenuBundle 1.2. -How to handle Items without a URL -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How to handle Items without an URL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When menu nodes refer to content that has been deleted or there is another -error during route generation, a menu node is skipped by default. You can set -the ``allow_empty_items`` setting of the CmfMenuBundle to ``true`` to render -these nodes as plain text instead. +error during route generation, that menu node (and its children) are ignored. +You can set ``cmf_menu.allow_empty_items`` to ``true`` to render these nodes as +plain text instead. .. _bundles_menu_menu_factory_link_type: Specifying the Link Type ~~~~~~~~~~~~~~~~~~~~~~~~ -The CMF provides a ``linkType`` option, which enables you to specify which URL -generation technique (URI, route or content) should be used. +The menu nodes has a ``linkType`` option, which enables you to specify which +URL generation technique (URI, route or content) should be used. The values for this options can be one of the following: @@ -81,7 +82,7 @@ Publish Workflow The CmfMenuBundle provides a ``MenuContentVoter``, which checks if the referenced content is published using the :doc:`publish workflow checker <../core/publish_workflow>`. If the content is -not yet published, the menu item not will not be rendered. +not yet published, the menu node (and its children) are ignored. Customizing Menus using Events ------------------------------ @@ -100,9 +101,9 @@ skipping nodes using the ``setSkipNode()`` and ``setSkipChildren()`` methods. If you mark the ``Menu`` document (the root node of each menu) as skipped, an empty item is still created to avoid errors when rendering a menu. -You can use the ``setItem()`` method to set the menu item to use instead of one -generated using the menu node. The child nodes are still processed like normal -and added to this new item. +You can use the ``setItem()`` method to set the menu item to use instead of the +one generated using the menu node. The child nodes are still processed like +normal and added to this new item. .. tip:: diff --git a/bundles/menu/menu_provider.rst b/bundles/menu/menu_provider.rst index 9444bbe2..dba3da7d 100644 --- a/bundles/menu/menu_provider.rst +++ b/bundles/menu/menu_provider.rst @@ -5,19 +5,20 @@ Menu Provider ============= A menu provider is responsible for loading a menu when it is requested. KnpMenu -supports having several providers. The MenuBundle provides the ``PhpcrMenuProvider`` -to load menu items using the PHPCR-ODM. +supports having several providers. The CmfMenuBundle provides the +``PhpcrMenuProvider`` to load menu items using Doctrine PHPCR-ODM. -Every menu is identified by the name of the node. These paths are relative to -the path configured by the ``cmf_menu.persistence.phpcr.menu_basepath`` -setting. This defaults to ``/cmf/menu``. In order to get a menu located in -``/cms/menu/main-menu``, you can use the identifier ``main-menu``. You can also -use an absolute path to get menus that are not located in the menu basepath. +Every menu is identified by the name of the root node. The provider looks for +the root node under the the path configured in +``cmf_menu.persistence.phpcr.menu_basepath``. This defaults to ``/cmf/menu``. +In order to get a menu located at ``/cms/menu/main-menu``, you use the +identifier ``main-menu``. You can also use an absolute path to load menus that +are not located under the menu basepath. .. tip:: - You can use custom document classes for menu nodes if needed. But KnpMenu - requires all nodes to implement ``Knp\Menu\NodeInterface``. + You can use custom document classes for menu nodes if needed, as long as + they implement ``Knp\Menu\NodeInterface``. .. note:: diff --git a/bundles/menu/sonata_admin.rst b/bundles/menu/sonata_admin.rst deleted file mode 100644 index fe43a646..00000000 --- a/bundles/menu/sonata_admin.rst +++ /dev/null @@ -1,250 +0,0 @@ -.. index:: - single: Menu; MenuAdmin - -Menu Admin with Sonata PHPCR-ODM -================================ - -If the SonataDoctrinePHPCRAdminBundle_ is loaded in the application kernel, -menu nodes and documents can be administrated in the Sonata admin panel. For -instructions on how to configure Sonata, see `the sonata admin documentation`_. - -The ``use_sonata_admin`` option configures whether to enable the menu admin. -This defaults to ``auto``, meaning it will be enabled when the -SonataAdminBundle is registered. Other values are ``true`` and ``false``, -forcing the admin to respectively be enabled or disabled. - -The menu admin uses the ``content_basepath`` to show the tree of nodes to -select the menu node target. - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - cmf_menu: - 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_menu', [ - '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, - ], - ], - ]); - - -MenuNodeReferrersInterface Sonata Admin Extension -------------------------------------------------- - -This bundle provides an extension to edit referring menu nodes for content that -implements the ``MenuNodeReferrersInterface``. - -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_menu.admin_extension.menu_node_referrers: - implements: - - Symfony\Cmf\Bundle\MenuBundle\Model\MenuNodeReferrersInterface - - .. code-block:: xml - - - - - - - - - Symfony\Cmf\Bundle\MenuBundle\Model\MenuNodeReferrersInterface - - - - - .. code-block:: php - - // app/config/config.php - use Symfony\Cmf\Bundle\MenuBundle\Model\MenuNodeReferrersInterface; - - $container->loadFromExtension('sonata_admin', [ - 'extensions' => [ - 'cmf_menu.admin_extension.menu_node_referrers' => [ - 'implements' => [ - MenuNodeReferrersInterface::class, - ], - ], - ], - ]); - -See the `Sonata Admin extension documentation`_ for more information. - -MenuOptionInterface Sonata Admin Extension ------------------------------------------- - -This bundle provides an extension that allows user to edit different menu -options using the Sonata admin interface. - -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_menu.admin_extension.menu_options: - implements: - - Symfony\Cmf\Bundle\MenuBundle\Model\MenuOptionsInterface - - .. code-block:: xml - - - - - - - - - Symfony\Cmf\Bundle\MenuBundle\Model\MenuOptionsInterface - - - - - .. code-block:: php - - // app/config/config.php - use Symfony\Cmf\Bundle\MenuBundle\Model\MenuOptionsInterface; - - $container->loadFromExtension('sonata_admin', [ - 'extensions' => [ - 'cmf_menu.admin_extension.menu_options' => [ - 'implements' => [ - MenuOptionsInterface::class, - ], - ], - ], - ]); - -See the `Sonata Admin extension documentation`_ for more information. - -These are the list of available options: - - * Display; - * Display children; - * Menu attributes (advanced); - * Label attributes (advanced); - * Children attributes (advanced); - * Link attributes (advanced). - -See the `KnpMenuBundle documentation`_ for more information about these -attributes. - -Advanced Menu Options -~~~~~~~~~~~~~~~~~~~~~ - -By default the only available options are **Display** and **Display Children**. -You can enable advanced options, but need to add the BurgovKeyValueFormBundle_ -to your project. Run ``composer require burgov/key-value-form-bundle``, -instantiate the bundle in the kernel and extend the template -``SonataAdminBundle:Form:form_admin_fields.html.twig`` to add: - -.. code-block:: jinja - - {% block burgov_key_value_widget %} - {{- block('sonata_type_native_collection_widget') -}} - {% endblock %} - -Once you enabled the bundle, you can enable the advanced menu options in your -configuration: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - cmf_menu: - admin_extensions: - menu_options: - advanced: true - - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('cmf_menu', [ - 'admin_extensions' => [ - 'menu_options' => [ - 'advanced' => true, - ], - ], - ]); - -.. _`Sonata Admin extension documentation`: https://sonata-project.org/bundles/admin/master/doc/reference/extensions.html -.. _SonataDoctrinePHPCRAdminBundle: https://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/index.html -.. _`the sonata admin documentation`: https://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/reference/configuration.html -.. _`KnpMenuBundle documentation`: https://github.com/KnpLabs/KnpMenu/blob/master/doc/01-Basic-Menus.markdown#menu-attributes -.. _BurgovKeyValueFormBundle: https://github.com/Burgov/KeyValueFormBundle diff --git a/bundles/menu/voters.rst b/bundles/menu/voters.rst index 07347768..ec1b0370 100644 --- a/bundles/menu/voters.rst +++ b/bundles/menu/voters.rst @@ -5,8 +5,8 @@ Current Menu Item Voters ======================== One of the aims of any menu system is to inform the user about where they are -in relation to the rest of the site. To do this the system needs to know which of -its menu items correspond to the page the user is currently viewing. +in relation to the rest of the site. To do this, the system needs to know which +of its menu items correspond to the page the user is currently viewing. To determine which menu item should be marked as the current item, KnpMenu includes voters. By default, KnpMenu comes with a voter that uses the Symfony @@ -15,19 +15,15 @@ item. This works well for static pages, highlighting the "About" item when viewing the about page. However, in a dynamic CMS website, you want more flexibility. -For instance, each blog post does not have its own menu item, instead only the -index page listing the posts has an item. When viewing a blog post, you want -the listings page to be highlighted. +In a blog for instance, individual posts do not have their own menu entry. +Instead, the menu entry for the index page with the listing of all posts should +be highlighted to indicate that the user is inside the blog section of the +page. .. note:: The voting process isn't using a democratic approach. Instead, the first - voter to return either ``true`` or ``false`` is used to make the decision. - -.. versionadded:: 2.0 - Voters were introduced in KnpMenu 2.0, which is first supported by - CmfMenuBundle 2.0. Prior to version 2.0, the CmfMenuBundle provided voter - support. + voter to return either ``true`` or ``false`` determines the decision. Provided Voters --------------- @@ -41,7 +37,8 @@ This voter looks at the ``content`` field of the menu item extras and compares it with the main content attribute of the request. The name for the main content attribute in the request is configurable with the ``content_key`` option - if not set it defaults to the constant -``Symfony\Cmf\Bundle\RoutingBundle\Routing\DynamicRouter::CONTENT_KEY`` (which resolves to ``contentDocument``). +``Symfony\Cmf\Bundle\RoutingBundle\Routing\DynamicRouter::CONTENT_KEY`` +(which is ``contentDocument``). You can enable this voter by adding the ``cmf_menu.voters.content_identity`` setting to your configuration. Example config: @@ -175,9 +172,10 @@ RequestParentContentIdentityVoter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This voter is similar in concept to the -:ref:`bundles_menu_voters_request_identity_voter` but instead of comparing +:ref:`bundles_menu_voters_request_identity_voter`, but instead of comparing request content with the menu item content, it compares the *parent* of the -request content with the menu item content. +request content with the menu item content. This voter can not be configured +but you instead need to configure custom services with it. Imagine you are creating a blogging platform. Each blog is represented by a document in the PHPCR-ODM tree. The posts of the blog are the children of this @@ -247,13 +245,6 @@ voters (see below), except you do not need to write your own PHP code: RequestParentContentIdentityVoter, ['contentDocument', Article::class] )); - $definition->addMethodCall('setRequest', [ - new Reference( - 'request', - ContainerInterface::NULL_ON_INVALID_REFERENCE, - false - ) - ]); $definition->addTag('knp_menu.voter', ['request' => true]); $container->setDefinition('app.menu_voter_parent', $definition); diff --git a/bundles/simple_cms/menus.rst b/bundles/simple_cms/menus.rst index 0ccbcd74..60416003 100644 --- a/bundles/simple_cms/menus.rst +++ b/bundles/simple_cms/menus.rst @@ -46,7 +46,8 @@ Menu options can be customized for each `Page` using the following public method .. tip:: If you use Sonata Admin in your project you can edit the menu options - using the MenuOptionsExtension that comes with the menu bundle. For more - information on how to use it take a look at the :doc:`menu bundle documentation <../menu/sonata_admin>` + using the MenuOptionsExtension that comes with the Sonata integration + bundle. For more information on how to use it, take a look at the + :doc:`menu admin documentation <../sonata_phpcr_admin_integration/menu>` .. _`Knp Menu Bundle`: https://github.com/KnpLabs/KnpMenuBundle diff --git a/bundles/sonata_phpcr_admin_integration/content.rst b/bundles/sonata_phpcr_admin_integration/content.rst index f7fd112b..c0e1e667 100644 --- a/bundles/sonata_phpcr_admin_integration/content.rst +++ b/bundles/sonata_phpcr_admin_integration/content.rst @@ -42,13 +42,64 @@ document. Enable this admin using: ], ]); -.. tip:: +WYSIWYG Editing with CKEditor +----------------------------- - Install the IvoryCKEditorBundle_ to enable a CKEditor to edit the content - body: +The content admin comes with an optional integration for the CK WYSIWYG +editor. To use CK instead of plain text, install the IvoryCKEditorBundle_: .. code-block:: bash $ composer require egeloen/ckeditor-bundle +When using the editor, you need to specify the name of the editor configuration +to use (see the IvoryCKEditorBundle_ documentation for more information on this +configuration): + + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + cmf_sonata_phpcr_admin_integration: + bundles: + content: + ivory_ckeditor: + enabled: true + config_name: cmf_sonata_phpcr_admin_integration + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('cmf_sonata_phpcr_admin_integration', [ + 'bundles' => [ + 'content' => [ + 'ivory_ckeditor' => [ + 'enabled' => true, + 'config_name' => 'cmf_sonata_phpcr_admin_integration', + ], + ], + ], + ]); + .. _IvoryCKEditorBundle: https://github.com/egeloen/IvoryCKEditorBundle diff --git a/bundles/sonata_phpcr_admin_integration/menu.rst b/bundles/sonata_phpcr_admin_integration/menu.rst index aa62c182..917eb22f 100644 --- a/bundles/sonata_phpcr_admin_integration/menu.rst +++ b/bundles/sonata_phpcr_admin_integration/menu.rst @@ -1,2 +1,255 @@ MenuBundle ========== + + This integration becomes available once the :doc:`CmfMenuBundle + <../menu/introduction>` is installed. + +The menu admin tools are the admins for menus and menu nodes, as well as an +admin extension to edit which menu nodes point to a content from within the +content page. + +The menu admin uses the ``cmf_menu.persistence.phpcr.menu_basepath`` setting to +determine where to add menus. The menu node admin additionally uses +``cmf_menu.persistence.phpcr.content_basepath`` to show the tree used to select +content for a menu node. + +There are some general settings for the menu admin: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + cmf_sonata_phpcr_admin_integration: + bundles: + menu: + recursive_breadcrumbs: true + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('cmf_sonata_phpcr_admin_integration', [ + 'bundles' => [ + 'menu' => [ + 'recursive_breadcrumbs' => true, + ], + ], + ]); + +recursive_breadcrumbs +~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``true``. + +If this is set to true, the breadcrumb in the menu item admin shows the +ancestor menu items in addition to the link for home and the menu containing +the current menu item. + +MenuNodeReferrersInterface Sonata Admin Extension +------------------------------------------------- + +The menu admin integration provides an extension to edit referring menu nodes +for content that implements the ``MenuNodeReferrersInterface``. + +To enable the extension in your admin classes, define the extension 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.menu.extension.menu_node_referrers: + implements: + - Symfony\Cmf\Bundle\MenuBundle\Model\MenuNodeReferrersInterface + + .. code-block:: xml + + + + + + + + + Symfony\Cmf\Bundle\MenuBundle\Model\MenuNodeReferrersInterface + + + + + .. code-block:: php + + // app/config/config.php + use Symfony\Cmf\Bundle\MenuBundle\Model\MenuNodeReferrersInterface; + + $container->loadFromExtension('sonata_admin', [ + 'extensions' => [ + 'cmf_sonata_phpcr_admin_integration.menu.extension.menu_node_referrers' => [ + 'implements' => [ + MenuNodeReferrersInterface::class, + ], + ], + ], + ]); + +See the `Sonata Admin extension documentation`_ for more information. + +MenuOptionInterface Sonata Admin Extension +------------------------------------------ + +This menu admin integration provides an extension that allows user to edit +different menu options using the Sonata admin interface. + +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.menu.extension.menu_options: + implements: + - Symfony\Cmf\Bundle\MenuBundle\Model\MenuOptionsInterface + + .. code-block:: xml + + + + + + + + + Symfony\Cmf\Bundle\MenuBundle\Model\MenuOptionsInterface + + + + + .. code-block:: php + + // app/config/config.php + use Symfony\Cmf\Bundle\MenuBundle\Model\MenuOptionsInterface; + + $container->loadFromExtension('sonata_admin', [ + 'extensions' => [ + 'cmf_sonata_phpcr_admin_integration.menu.extension.menu_options' => [ + 'implements' => [ + MenuOptionsInterface::class, + ], + ], + ], + ]); + +See the `Sonata Admin extension documentation`_ for more information. + +The extension makes these options editable (advanced options require additional +setup, see below): + + * Display; + * Display children; + * Menu attributes (advanced); + * Label attributes (advanced); + * Children attributes (advanced); + * Link attributes (advanced). + +See the `KnpMenuBundle documentation`_ for more information about the meaning +of those attributes. + +Advanced Menu Options +~~~~~~~~~~~~~~~~~~~~~ + +By default the only available options are **Display** and **Display Children**. +You can enable advanced options, but need to add the BurgovKeyValueFormBundle_ +to your project. Run ``composer require burgov/key-value-form-bundle``, +instantiate the bundle in the kernel and extend the template +``SonataAdminBundle:Form:form_admin_fields.html.twig`` to add: + +.. code-block:: jinja + + {% block burgov_key_value_widget %} + {{- block('sonata_type_native_collection_widget') -}} + {% endblock %} + +Once you enabled the bundle, you can enable the advanced menu options in your +configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + cmf_sonata_phpcr_admin_integration: + bundles: + menu: + extensions: + menu_options: + advanced: true + + .. code-block:: xml + + + + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('cmf_sonata_phpcr_admin_integration', [ + 'bundles' => [ + 'menu' => [ + 'extensions' => [ + 'menu_options' => [ + 'advanced' => true, + ], + ], + ], + ], + ]); + +.. _`Sonata Admin extension documentation`: https://sonata-project.org/bundles/admin/master/doc/reference/extensions.html +.. _SonataDoctrinePHPCRAdminBundle: https://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/index.html +.. _`the sonata admin documentation`: https://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/reference/configuration.html +.. _`KnpMenuBundle documentation`: https://github.com/KnpLabs/KnpMenu/blob/master/doc/01-Basic-Menus.markdown#menu-attributes +.. _BurgovKeyValueFormBundle: https://github.com/Burgov/KeyValueFormBundle