adding doc for delegated blocks

ref Chill-project/Chill-Main#12

source/development/index.rst

@@ -36,6 +36,7 @@ Layout and UI
    
    Layout / Template usage <user-interface/layout-template-usage.rst>
    Classes and mixins <user-interface/css-classes.rst>
+   Delegated blocks <user-interface/delegated-blocks.rst>
 
 
 Help, I am lost !

source/development/user-interface/delegated-blocks.rst

@@ -0,0 +1,92 @@
+.. Copyright (C)  2016 Champs Libres Cooperative SCRLFS
+   Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+Delegating rendering of block to other bundles
+##############################################
+
+Sometimes, you may want to delegate part of your layout to another bundle(s), which might, or might not, installed.
+
+Examples : 
+
+- you may want to show task in the top bar, only if the bundle "task" is installed (**Note**: this bundle does not exists... yet !)
+- you may want to show the group belonging (see :ref:`group-bundle`) below of the vertical menu, only if the bundle is installed.
+
+This is possible using `the symfony dispatcher event <http://symfony.com/doc/current/components/event_dispatcher/index.html>`_.
+
+Inserting a delegated block inside of a template
+================================================
+
+Use the twig function :code:`chill_delegated_block`.
+
+Example :
+
+.. code-block:: html+jinja
+
+   {{ chill_delegated_block('my_block', { 'person': person }) }}
+
+In this example, the block name is :code:`my_block`, and the context is an array : :code:`{ 'person': person }`.
+
+Subscribing to a delegated block
+=================================
+
+Create a :code:`Subscriber` or a :code:`Listener` as `described in the Symfony documentation <http://symfony.com/doc/current/cookbook/event_dispatcher/event_listener.html>`_.
+
+You should listen to the event :code:`chill_block.block_name`, where `block_name` is the name of the delegated block. For instance, in the example above, the event will be :code:`chill_block.my_block`.
+
+The event passed as argument will be an instance of :class:`Chill\MainBundle\Templating\Events\DelegatedBlockRenderingEvent`. The context will be available as an array, as described in subscriber example. You may add content to the page using the :method:`Chill\MainBundle\Templating\Events\DelegatedBlockRenderingEvent::addContent` method.
+
+Example :
+
+.. code-block:: php
+
+   namespace Chill\GroupBundle\Events;
+
+   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+   use Chill\MainBundle\Templating\Events\DelegatedBlockRenderingEvent;
+
+
+   class TemplatingPostVerticalMenuEventSubscriber implements EventSubscriberInterface
+   {
+       // constructor logic will take place here in a real world
+       
+       public static function getSubscribedEvents()
+       {
+           return array('chill_block.person_post_vertical_menu' => array(
+               array('processRendering', 0) // you may change the priority if you want your content to be inserted upper or below of the other content.
+           ));
+       }
+       
+       // here is where we add content to the event.
+       public function processRendering(DelegatedBlockRenderingEvent $event) 
+       {
+           // we access the person using $event['person']
+           $memberships = $memberships = $this->membershipRepository
+                   ->findBy(array('person' => $event['person']));
+           
+           // we add content to the templating using the templating engine
+           $event->addContent(
+                   $this->templating
+                       ->render('ChillGroupBundle:Membership:short_listing.html.twig', array(
+                           'memberships' => $memberships,
+                       ))
+               );
+       }
+
+   }
+
+This tag is registered as a service :
+
+.. code-block:: yaml
+
+   services:
+       chill_group.membership_rendering_event:
+           class: Chill\GroupBundle\Events\TemplatingPostVerticalMenuEventSubscriber
+           tags:
+               - { name: kernel.event_subscriber }
+
+You should have a look at the documentation of the bundle to know which delegated block are available and what is their context.