diff --git a/source/development/index.rst b/source/development/index.rst index 1f9e45c96..4b6afaab0 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -36,6 +36,7 @@ Layout and UI Layout / Template usage Classes and mixins + Delegated blocks Help, I am lost ! diff --git a/source/development/user-interface/delegated-blocks.rst b/source/development/user-interface/delegated-blocks.rst new file mode 100644 index 000000000..e3f4e49ee --- /dev/null +++ b/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 `_. + +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 `_. + +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.