update menu bundle documentation for cmf 2.0

Author: dbu

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`

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:
                     <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"
+                        node-document-class="Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode"
                     />
                 </persistence>
             </config>
@@ -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
-
-        <!-- app/config/config.xml -->
-        <?xml version="1.0" charset="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services">
-            <config xmlns="http://cmf.symfony.com/schema/dic/menu">
-                <admin_extensions>
-                    <menu_options
-                        enabled="auto"
-                        advanced="false"
-                    />
-                </admin_extensions>
-            </config>
-        </container>
-
-    .. 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
 -----
 

bundles/menu/index.rst

@@ -9,5 +9,4 @@ MenuBundle
     menu_factory
     menu_provider
     voters
-    sonata_admin
     configuration

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 <phpcr-odm-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

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 <bundles_menu_menu_factory_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');

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
-<bundles-routing-dynamic-generator>`, this needs to be a class implementing the
+<bundles-routing-dynamic-generator>`, 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::