Add documentation for CreateMenuItemFromNodeEvent.

Author: Ben

bundles/menu/menu_factory.rst

@@ -65,3 +65,99 @@ visible by use of the :doc:`publish workflow checker
 
 The ``MenuContentVoter`` decides that a menu node is not published if the
 content it is pointing to is not published.
+
+Customizing Menus using Events
+------------------------------
+
+The CMF menu factory dispatches a ``cmf_menu.create_menu_item_from_node`` event 
+during the process of creating a ``MenuItem`` from a class implementing 
+``NodeInterface``. You can use this event to control the ``MenuItem`` that is 
+created. The ``CreateMenuItemFromNodeEvent`` provides access to the 
+``NodeInterface`` and ``ContentAwareFactory``, which can be used to create a
+custom ``MenuItem``, or to tell the factory to ignore the current node or its 
+children. For example, this event is used by the 
+:doc:`publish workflow checker <../core/publish_workflow>` to skip 
+``MenuItem`` generation for unpublished nodes.
+
+The ``CreateMenuItemFromNodeEvent`` which is dispatched includes the following
+methods which can be used to customize the creation of the ``MenuItem`` for a 
+``NodeInterface``.
+
+* ``CreateMenuItemFromNodeEvent::setSkipNode(true|false)``: Setting skipNode to 
+  true will prevent creation of item from the node and skip any child nodes.
+  **Note:** If setSkipNode(true) is called for ``Menu`` the ``ContentAwareFactory``
+  will still create an empty item for the menu. This is to prevent the KnpMenuBundle
+  code from throwing an Exception due to null being passed to a function to render a
+  menu.
+* ``CreateMenuItemFromNodeEvent::setItem(ItemInterface $item|null)``: A listener
+  can call setItem to provide a custom item to use for the given node. If an
+  item is set, the ``ContentAwareFactory`` will use it instead of creating one for 
+  the node.  The children of the node will still be processed by the 
+  ``ContentAwareFactory`` and listeners will have an opportunity then to override 
+  their items using this method.
+* ``CreateMenuItemFromNodeEvent::setSkipChildren(true|false)``: Listeners can
+  set this to true and the ``ContentAwareFactory`` will skip processing of the
+  children of the current node.
+
+Example Listener
+~~~~~~~~~~~~~~~~
+
+Example PHP code for a listener that would replace nodes that implement
+an interface ``MenuReferrerInterface`` with a menu generated by
+a menu provider service.
+
+.. code-block:: php
+
+    namespace Example\Menu;
+
+    interface MenuReferrerInterface
+    {
+        public function getMenuName();
+        public function getMenuOptions();
+    }
+
+    namespace Example\Event;
+
+    use Symfony\Cmf\Bundle\MenuBundle\Event\CreateMenuItemFromNodeEvent;
+    use Example\Menu\MenuReferrerInterface;
+    use Knp\Menu\Provider\MenuProviderInterface;
+
+    class CreateMenuItemFromNodeListener
+    {
+        protected $provider;
+
+        public function __construct(MenuProviderInterface $provider)
+        {
+            $this->provider = $provider;
+        }
+
+        public function onCreateMenuItemFromNode(CreateMenuItemFromNodeEvent $event)
+        {
+            $node = $event->getNode();
+            
+            if ($node implements MenuReferrerInterface) {
+                $menuName = $node->getMenuName();
+                $menuOptions = $node->getMenuOptions();
+
+                if ( ! $this->provider->has($menuName)) {
+                    return;
+                }
+
+                $menu = $this->provider->get($menuName, $menuOptions);
+                $event->setItem($menu);
+            }
+        }
+
+    }
+
+Service definition
+
+.. code-block:: xml
+
+    <service id="cmf_menu.listener.menu_referrer_listener" class="Example\Event\CreateMenuItemFromNodeListener">
+        <argument type="service" id="knp_menu.menu_provider" />
+        <tag name="kernel.event_listener" event="cmf_menu.create_menu_item_from_node" method="onCreateMenuItemFromNode" />
+    </service>
+
+**Note** In this case since the listener did not call ``$event->setSkipChildren(true)`` any nodes 
+that are children of the node being processed will still be added to the menu that is created.