Merge pull request #374 from symfony-cmf/menu-prefetch

document the menu prefetch option

Author: wouterj

reference/configuration/menu.rst

@@ -27,6 +27,7 @@ persistence configuration has the following configuration:
                     enabled:              false
                     menu_basepath:        /cms/menu
                     content_basepath:     ~
+                    prefetch:             10
                     manager_name:         ~
                     menu_document_class:  Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu
                     node_document_class:  Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode
@@ -46,6 +47,7 @@ persistence configuration has the following configuration:
                         enabled="false"
                         menu-basepath="/cms/menu"
                         content-basepath="null"
+                        prefetch="10"
                         manager-name="null"
                         menu-document-class="null"
                         node-document-class="null"
@@ -66,6 +68,7 @@ persistence configuration has the following configuration:
                     'enabled' => false,
                     'menu_basepath' => '/cms/menu',
                     'content_basepath' => null,
+                    'prefetch' => 10,
                     'manager_name' => null,
                     'menu_document_class' => null,
                     'node_document_class' => null,
@@ -82,11 +85,6 @@ enabled
 
 .. include:: partials/persistence_phpcr_enabled.rst.inc
 
-manager_name
-""""""""""""
-
-.. include:: partials/persistence_phpcr_manager_name.rst.inc
-
 menu_basepath
 """""""""""""
 
@@ -95,7 +93,7 @@ menu_basepath
 Specifies the path in the PHPCR-ODM document hierarchy under which the menu
 documents can be found.
 
-* This is the default location used by the 
+* This is the default location used by the
   :doc:`MenuProvider <../../bundles/menu/menu_factory>` to locate menus.
 * This is the default location for newly created menus in the Sonata admin
   class.
@@ -115,8 +113,31 @@ the content branch of the document hierarchy in forms.
 If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to
 the value of ``%cmf_core.persistence.phpcr.basepath%/content``
 
-menu_document
-"""""""""""""
+.. versionadded:: 1.1
+
+    The prefetch functionality was added in MenuBundle 1.1.
+
+prefetch
+""""""""
+
+**type**: ``integer`` **default**: ``10``
+
+When rendering a menu, the whole menu tree needs to be loaded. To reduce the
+number of database requests that PHPCR needs to make, this setting makes the
+tree loader prefetch all menu nodes in one call.
+
+``10`` should be enough for most cases, if you have deeper menu structures you
+might want to increase this.
+
+To disable menu prefetch completely, set this option to ``0``.
+
+manager_name
+""""""""""""
+
+.. include:: partials/persistence_phpcr_manager_name.rst.inc
+
+menu_document_class
+"""""""""""""""""""
 
 **type**: ``string`` **default**:
 ``Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu``
@@ -125,8 +146,8 @@ Specifies the document class which should represent an entire menu.
 
 This setting is used by the admin class.
 
-node_document
-"""""""""""""
+node_document_class
+"""""""""""""""""""
 
 **type**: ``string`` **default**:
 ``Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode``
@@ -175,7 +196,7 @@ The ``voters`` section enables you to enable and configure *pre-defined* :doc:`v
     .. code-block:: yaml
 
         cmf_menu:
-            # ... 
+            # ...
             voters:
                 content_identity:
                     content_key:          ~