cleanup the menu creation event and improve doc

Author: dbu

CHANGELOG.md

@@ -1,6 +1,10 @@
 Changelog
 =========
 
+* **2014-04-04**: The menu factory now raises an event when a menu item is
+  built from a menu node. The event can be used to change the behaviour or
+  skip building the menu item altogether.
+
 * **2014-03-24**: setParent() and getParent() are now deprecated.
   Use setParentDocument() and getParentDocument() instead.
   Moreover, you should now enable the ChildExtension from the CoreBundle.
@@ -16,8 +20,8 @@ Changelog
        $ php app/console doctrine:phpcr:nodes:update \
            --query="SELECT * FROM [nt:base] WHERE [phpcr:class] = 'Symfony\\Cmf\\Bundle\\MenuBundle\\Doctrine\\Phpcr\\Menu' OR [phpcr:class] = 'Symfony\\Cmf\\Bundle\\MenuBundle\\Doctrine\\Phpcr\\MenuNode'" \
            --apply-closure="$node->addMixin('mix:referenceable');"
- 
-* **2013-11-25**: [PublishWorkflow] added a `MenuContentVoter`, this voter 
+
+* **2013-11-25**: [PublishWorkflow] added a `MenuContentVoter`, this voter
   decides that a menu node is not published if the content it is pointing to is
   not published.
 

ContentAwareFactory.php

@@ -18,6 +18,8 @@
 
 use Psr\Log\LoggerInterface;
 
+use Symfony\Cmf\Bundle\MenuBundle\Event\Events;
+use Symfony\Cmf\Bundle\MenuBundle\Model\Menu;
 use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 use Symfony\Component\Routing\Exception\RouteNotFoundException;
 
@@ -68,23 +70,24 @@ class ContentAwareFactory extends RouterAwareFactory
     private $allowEmptyItems;
 
     /**
-     * @param UrlGeneratorInterface $generator     for the parent class
-     * @param UrlGeneratorInterface $contentRouter to generate routes when
+     * @param UrlGeneratorInterface    $generator     for the parent class
+     * @param UrlGeneratorInterface    $contentRouter to generate routes when
      *      content is set
-     * @param LoggerInterface $logger
+     * @param EventDispatcherInterface $dispatcher    to dispatch the CREATE_ITEM_FROM_NODE event.
+     * @param LoggerInterface          $logger
      */
     public function __construct(
         UrlGeneratorInterface $generator,
         UrlGeneratorInterface $contentRouter,
-        LoggerInterface $logger,
-        EventDispatcherInterface $dispatcher
+        EventDispatcherInterface $dispatcher,
+        LoggerInterface $logger
     )
     {
         parent::__construct($generator);
         $this->contentRouter = $contentRouter;
-        $this->logger = $logger;
         $this->linkTypes = array('route', 'uri', 'content');
         $this->dispatcher = $dispatcher;
+        $this->logger = $logger;
     }
 
     /**
@@ -144,9 +147,14 @@ private function getVoters()
     public function createFromNode(NodeInterface $node)
     {
         $event = new CreateMenuItemFromNodeEvent($node, $this);
-        $this->dispatcher->dispatch('cmf_menu.create_menu_item_from_node', $event);
+        $this->dispatcher->dispatch(Events::CREATE_ITEM_FROM_NODE, $event);
+
+        if ($event->isSkipNode()) {
+            if ($node instanceof Menu) {
+                // create an empty menu root to avoid the knp menu from failing.
+                return $this->createItem('');
+            }
 
-        if ($event->getSkipNode()) {
             return null;
         }
 
@@ -156,23 +164,24 @@ public function createFromNode(NodeInterface $node)
             return null;
         }
 
-        if ($event->getSkipChildren()) {
+        if ($event->isSkipChildren()) {
             return $item;
         }
 
-        return $this->addChildrenFromNode($node, $item);
+        return $this->addChildrenFromNode($node->getChildren(), $item);
     }
 
     /**
-     * Add children to a menu item from a node
+     * Create menu items from a list of menu nodes and add them to $item.
+     *
+     * @param NodeInterface[] $node The menu nodes to create.
+     * @param ItemInterface   $item The menu item to add the children to.
      *
-     * @param NodeInterface $node
-     * @param ItemInterface $item
      * @return ItemInterface
      */
-    public function addChildrenFromNode(NodeInterface $node, ItemInterface $item)
+    public function addChildrenFromNode($nodes, ItemInterface $item)
     {
-        foreach ($node->getChildren() as $childNode) {
+        foreach ($nodes as $childNode) {
             if ($childNode instanceof NodeInterface) {
                 $child = $this->createFromNode($childNode);
                 if (!empty($child)) {

Event/CreateMenuItemFromNodeEvent.php

@@ -3,52 +3,65 @@
 /*
  * This file is part of the Symfony CMF package.
  *
- * (c) 2011-2013 Symfony CMF
+ * (c) 2011-2014 Symfony CMF
  *
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
 
 namespace Symfony\Cmf\Bundle\MenuBundle\Event;
 
-use Knp\Menu\MenuItem;
+use Knp\Menu\ItemInterface;
 use Knp\Menu\NodeInterface;
 
 use Symfony\Component\EventDispatcher\Event;
 
 use Symfony\Cmf\Bundle\MenuBundle\ContentAwareFactory;
 
+/**
+ * This event is raised when a menu node is to be transformed into a menu item.
+ *
+ * The event allows to control whether the menu node should be handled or to
+ * completely replace the default behaviour of converting a menu node to a menu
+ * item.
+ *
+ * @author Ben Glassman <[email protected]>
+ */
 class CreateMenuItemFromNodeEvent extends Event
 {
     /**
      * @var NodeInterface
      */
-    protected $node;
+    private $node;
 
     /**
-     * @var ContentAwareFactory
+     * @var ItemInterface
      */
-    protected $factory;
+    private $item;
 
     /**
-     * @var MenuItem
+     * @var ContentAwareFactory
      */
-    protected $item;
+    private $factory;
 
     /**
      * Whether or not to skip processing of this node
-     * 
+     *
      * @var boolean
      */
-    protected $skipNode = false;
+    private $skipNode = false;
 
     /**
      * Whether or not to skip processing of child nodes
-     * 
+     *
      * @var boolean
      */
-    protected $skipChildren = false;
+    private $skipChildren = false;
 
+    /**
+     * @param NodeInterface       $node
+     * @param ContentAwareFactory $factory
+     */
     public function __construct(
         NodeInterface $node,
         ContentAwareFactory $factory
@@ -57,44 +70,100 @@ public function __construct(
         $this->factory = $factory;
     }
 
-    public function getItem()
-    {
-        return $this->item;
-    }
-
-    public function setItem(MenuItem $item = null)
+    /**
+     * Get the menu node that is about to be built.
+     *
+     * @return NodeInterface
+     */
+    public function getNode()
     {
-        $this->item = $item;
+        return $this->node;
     }
 
-    public function getFactory()
+    /**
+     * Get the menu item attached to this event.
+     *
+     * If this is non-null, it will be used instead of automatically converting
+     * the NodeInterface into a MenuItem.
+     *
+     * @return ItemInterface
+     */
+    public function getItem()
     {
-        return $this->factory;
+        return $this->item;
     }
 
-    public function getNode()
+    /**
+     * Set the menu item that represents the menu node of this event.
+     *
+     * Unless you set the skip children option, the children from the menu node
+     * will still be built and added after eventual children this menu item
+     * has.
+     *
+     * @param ItemInterface $item Menu item to use.
+     */
+    public function setItem(ItemInterface $item = null)
     {
-        return $this->node;
+        $this->item = $item;
     }
 
+    /**
+     * Set whether the node associated with this event is to be skipped
+     * entirely. This has precedence over an eventual menu item attached to the
+     * event.
+     *
+     * This automatically skips the whole subtree, as the children have no
+     * place where they could be attached to.
+     *
+     * @param bool $skipNode
+     */
     public function setSkipNode($skipNode)
     {
         $this->skipNode = (bool) $skipNode;
     }
 
-    public function getSkipNode()
+    /**
+     * @return bool Whether the node associated to this event is to be skipped.
+     */
+    public function isSkipNode()
     {
         return $this->skipNode;
     }
 
+    /**
+     * Set whether the children of the *node* associated with this event should
+     * be ignored.
+     *
+     * Use this for example when your event handler implements its own logic to
+     * build children items for the node associated with this event.
+     *
+     * If this event has a menu *item*, those children won't be skipped.
+     *
+     * @param bool $skipChildren
+     */
     public function setSkipChildren($skipChildren)
     {
         $this->skipChildren = (bool) $skipChildren;
     }
 
-    public function getSkipChildren()
+    /**
+     * @return bool Whether the children of the node associated to this event
+     *              should be handled or ignored.
+     */
+    public function isSkipChildren()
     {
         return $this->skipChildren;
     }
 
+    /**
+     * Get the menu factory that raised this event.
+     *
+     * You can use the factory to build a custom menu item.
+     *
+     * @return ContentAwareFactory
+     */
+    public function getFactory()
+    {
+        return $this->factory;
+    }
 }

Event/Events.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the Symfony CMF package.
+ *
+ * (c) 2011-2014 Symfony CMF
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Cmf\Bundle\MenuBundle\Event;
+
+final class Events
+{
+    /**
+     * Fired when a menu item is to be created from a node in ContentAwareFactory
+     *
+     * The event object is a CreateMenuItemFromNodeEvent.
+     */
+    const CREATE_ITEM_FROM_NODE = 'cmf_menu.create_menu_item_from_node';
+}

Provider/PhpcrMenuProvider.php

@@ -9,7 +9,6 @@
  * file that was distributed with this source code.
  */
 
-
 namespace Symfony\Cmf\Bundle\MenuBundle\Provider;
 
 use Doctrine\Common\Persistence\ManagerRegistry;