prepare for merging doc into mono-repository

docs/source/development/user-interface/widgets/ChillMainConfiguration.php

@@ -0,0 +1,64 @@
+<?php
+   # Chill\MainBundle\DependencyInjection\Configuration.php
+  
+   namespace Chill\MainBundle\DependencyInjection;
+
+   use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+   use Symfony\Component\Config\Definition\ConfigurationInterface;
+   use Chill\MainBundle\DependencyInjection\Widget\AddWidgetConfigurationTrait;
+   use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+   /**
+    * Configure the main bundle
+    */
+   class Configuration implements ConfigurationInterface
+   {
+       
+       use AddWidgetConfigurationTrait;
+       
+       /**
+	*
+	* @var ContainerBuilder
+	*/
+       private $containerBuilder;
+
+       
+       public function __construct(array $widgetFactories = array(), 
+	       ContainerBuilder $containerBuilder)
+       {
+           // we register here widget factories (see below)
+	   $this->setWidgetFactories($widgetFactories);
+           // we will need the container builder later...
+	   $this->containerBuilder = $containerBuilder;
+       }
+       
+       /**
+	* {@inheritDoc}
+	*/
+       public function getConfigTreeBuilder()
+       {
+	   $treeBuilder = new TreeBuilder();
+	   $rootNode = $treeBuilder->root('chill_main');
+
+	   $rootNode
+	       ->children()
+
+                   // ...
+
+		   ->arrayNode('widgets')
+		       ->canBeDisabled()
+		       ->children()
+                            // we declare here all configuration for homepage place
+			    ->append($this->addWidgetsConfiguration('homepage', $this->containerBuilder))
+		       ->end() // end of widgets/children
+		   ->end() // end of widgets
+		  ->end() // end of root/children
+	       ->end() // end of root
+	   ;
+
+	   
+	   return $treeBuilder;
+       }
+   }
+
+

docs/source/development/user-interface/widgets/ChillMainExtension.php

@@ -0,0 +1,59 @@
+<?php
+
+#Chill\MainBundle\DependencyInjection\ChillMainExtension.php
+
+namespace Chill\MainBundle\DependencyInjection;
+
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\Config\FileLocator;
+use Symfony\Component\HttpKernel\DependencyInjection\Extension;
+use Symfony\Component\DependencyInjection\Loader;
+use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
+use Chill\MainBundle\DependencyInjection\Widget\Factory\WidgetFactoryInterface;
+use Chill\MainBundle\DependencyInjection\Configuration;
+
+/**
+ * This class load config for chillMainExtension.
+ */
+class ChillMainExtension extends Extension implements Widget\HasWidgetFactoriesExtensionInterface
+{
+    /**
+     * widget factory
+     * 
+     * @var WidgetFactoryInterface[]
+     */
+    protected $widgetFactories = array();
+    
+    public function addWidgetFactory(WidgetFactoryInterface $factory)
+    {
+        $this->widgetFactories[] = $factory;
+    }
+    
+    /**
+     * 
+     * @return WidgetFactoryInterface[]
+     */
+    public function getWidgetFactories()
+    {
+        return $this->widgetFactories;
+    }
+    
+    public function load(array $configs, ContainerBuilder $container)
+    {
+        // configuration for main bundle
+        $configuration = $this->getConfiguration($configs, $container);
+        $config = $this->processConfiguration($configuration, $configs);
+        
+        // add the key 'widget' without the key 'enable'
+        $container->setParameter('chill_main.widgets', 
+            array('homepage' => $config['widgets']['homepage']));
+
+        // ... 
+    }
+    
+    public function getConfiguration(array $config, ContainerBuilder $container)
+    {
+        return new Configuration($this->widgetFactories, $container);
+    }
+    
+}

docs/source/development/user-interface/widgets/ChillPersonAddAPersonListWidgetFactory.php

@@ -0,0 +1,69 @@
+<?php
+
+# Chill/PersonBundle/Widget/PersonListWidgetFactory
+
+namespace Chill\PersonBundle\Widget;
+
+use Chill\MainBundle\DependencyInjection\Widget\Factory\AbstractWidgetFactory;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
+
+/**
+ * add configuration for the person_list widget.
+ */
+class PersonListWidgetFactory extends AbstractWidgetFactory
+{
+   /*
+    * append the option to the configuration
+    * see http://symfony.com/doc/current/components/config/definition.html
+    *
+    */
+    public function configureOptions($place, NodeBuilder $node)
+    {
+        $node->booleanNode('only_active')
+                ->defaultTrue()
+                ->end();
+        $node->integerNode('number_of_items')
+            ->defaultValue(50)
+            ->end();
+        $node->scalarNode('filtering_class')
+                ->defaultNull()
+                ->end();
+            
+    }
+     
+   /*
+    * return an array with the allowed places where the widget can be rendered
+    *
+    * @return string[]
+    */   
+    public function getAllowedPlaces()
+    {
+        return array('homepage');
+    }
+    
+   /* 
+    * return the widget alias
+    *
+    * @return string
+    */
+    public function getWidgetAlias()
+    {
+        return 'person_list';
+    }
+    
+    /*
+     * return the service id for the service which will render the widget.
+     *
+     * this service must implements `Chill\MainBundle\Templating\Widget\WidgetInterface`
+     * 
+     * the service must exists in the container, and it is not required that the service 
+     * has the `chill_main` tag.
+     */
+    public function getServiceId(ContainerBuilder $containerBuilder, $place, $order, array $config)
+    {
+        return 'chill_person.widget.person_list';
+    }
+    
+}
+

docs/source/development/user-interface/widgets/ChillPersonAddAPersonWidget.php

@@ -0,0 +1,129 @@
+<?php
+# Chill/PersonBundle/Widget/PersonListWidget.php
+
+namespace Chill\PersonBundle\Widget;
+
+use Chill\MainBundle\Templating\Widget\WidgetInterface;
+use Doctrine\ORM\EntityRepository;
+use Doctrine\ORM\Query\Expr;
+use Doctrine\DBAL\Types\Type;
+use Chill\MainBundle\Security\Authorization\AuthorizationHelper;
+use Symfony\Component\Security\Core\User\UserInterface;
+use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorage;
+use Chill\PersonBundle\Security\Authorization\PersonVoter;
+use Symfony\Component\Security\Core\Role\Role;
+use Doctrine\ORM\EntityManager;
+
+/**
+ * add a widget with person list. 
+ * 
+ * The configuration is defined by `PersonListWidgetFactory`
+ */
+class PersonListWidget implements WidgetInterface
+{
+    
+    /**
+     * Repository for persons
+     * 
+     * @var EntityRepository
+     */
+    protected $personRepository;
+    
+    /**
+     * The entity manager
+     *
+     * @var EntityManager
+     */
+    protected $entityManager;
+    
+    /**
+     * the authorization helper
+     * 
+     * @var AuthorizationHelper;
+     */
+    protected $authorizationHelper;
+    
+    /**
+     *
+     * @var TokenStorage
+     */
+    protected $tokenStorage;
+    
+    /**
+     *
+     * @var UserInterface
+     */
+    protected $user;
+    
+    public function __construct(
+            EntityRepository $personRepostory,
+            EntityManager $em,
+            AuthorizationHelper $authorizationHelper,
+            TokenStorage $tokenStorage
+            ) {
+        $this->personRepository = $personRepostory;
+        $this->authorizationHelper = $authorizationHelper;
+        $this->tokenStorage = $tokenStorage;
+        $this->entityManager = $em;
+    }
+
+    /**
+     * 
+     * @param type $place
+     * @param array $context
+     * @param array $config
+     * @return string
+     */
+    public function render(\Twig_Environment $env, $place, array $context, array $config)
+    { 
+        $qb = $this->personRepository
+                ->createQueryBuilder('person');
+        
+        // show only the person from the authorized centers
+        $and = $qb->expr()->andX();
+        $centers = $this->authorizationHelper
+                ->getReachableCenters($this->getUser(), new Role(PersonVoter::SEE));
+        $and->add($qb->expr()->in('person.center', ':centers'));
+        $qb->setParameter('centers', $centers);
+        
+
+        // add the "only active" where clause
+        if ($config['only_active'] === true) {
+            $qb->join('person.accompanyingPeriods', 'ap');
+            $or = new Expr\Orx();
+            // add the case where closingDate IS NULL
+            $andWhenClosingDateIsNull = new Expr\Andx();
+            $andWhenClosingDateIsNull->add((new Expr())->isNull('ap.closingDate'));
+            $andWhenClosingDateIsNull->add((new Expr())->gte(':now', 'ap.openingDate'));
+            $or->add($andWhenClosingDateIsNull);
+            // add the case when now is between opening date and closing date
+            $or->add(
+                    (new Expr())->between(':now', 'ap.openingDate', 'ap.closingDate')
+                );
+            $and->add($or);
+            $qb->setParameter('now', new \DateTime(), Type::DATE);
+        }
+        
+        // adding the where clause to the query
+        $qb->where($and);
+        
+        $qb->setFirstResult(0)->setMaxResults($config['number_of_items']);
+        
+        $persons = $qb->getQuery()->getResult();
+        
+        return $env->render(
+            'ChillPersonBundle:Widget:homepage_person_list.html.twig',
+            array('persons' => $persons)
+            );
+    }
+    
+    /**
+     * 
+     * @return UserInterface
+     */
+    private function getUser()
+    {
+        // return a user
+    }
+
+}

docs/source/development/user-interface/widgets/ChillPersonExtension.php

@@ -0,0 +1,51 @@
+<?php
+
+# Chill/PersonBundle/DependencyInjection/ChillPersonExtension.php
+
+namespace Chill\PersonBundle\DependencyInjection;
+
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\Config\FileLocator;
+use Symfony\Component\HttpKernel\DependencyInjection\Extension;
+use Symfony\Component\DependencyInjection\Loader;
+use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
+use Chill\MainBundle\DependencyInjection\MissingBundleException;
+use Chill\PersonBundle\Security\Authorization\PersonVoter;
+
+/**
+ * This is the class that loads and manages your bundle configuration
+ *
+ * To learn more see {@link http://symfony.com/doc/current/cookbook/bundles/extension.html}
+ */
+class ChillPersonExtension extends Extension implements PrependExtensionInterface
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function load(array $configs, ContainerBuilder $container)
+    {
+      // ...
+    }
+    
+    
+    /**
+     * 
+     * Add a widget "add a person" on the homepage, automatically
+     * 
+     * @param \Chill\PersonBundle\DependencyInjection\containerBuilder $container
+     */
+    public function prepend(ContainerBuilder $container) 
+    {
+        $container->prependExtensionConfig('chill_main', array(
+            'widgets' => array(
+                'homepage' => array(
+                    array(
+                        'widget_alias' => 'add_person',
+                        'order' => 2
+                    )
+                )
+            )
+        ));
+    }
+}
+