Merge branch 'master' into ticket-app-master

# Conflicts:
#	src/Bundle/ChillMainBundle/Export/Formatter/CSVFormatter.php
#	src/Bundle/ChillMainBundle/Export/Formatter/CSVListFormatter.php
#	src/Bundle/ChillMainBundle/Export/Formatter/SpreadsheetListFormatter.php
#	src/Bundle/ChillMainBundle/Resources/public/vuejs/PickEntity/PickEntity.vue
#	src/Bundle/ChillPersonBundle/Export/Aggregator/AccompanyingCourseAggregators/GeographicalUnitStatAggregator.php
#	src/Bundle/ChillPersonBundle/Resources/public/types.ts
#	src/Bundle/ChillPersonBundle/Resources/public/vuejs/_components/AddPersons.vue

docs/source/_static/code/exports/BirthdateFilter.php

@@ -12,6 +12,7 @@ declare(strict_types=1);
 namespace Chill\PersonBundle\Export\Filter;
 
 use Chill\MainBundle\Export\ExportElementValidatedInterface;
+use Chill\MainBundle\Export\ExportGenerationContext;
 use Chill\MainBundle\Export\FilterInterface;
 use DateTime;
 use Doctrine\ORM\Query\Expr;
@@ -20,6 +21,7 @@ use Symfony\Component\Validator\Context\ExecutionContextInterface;
 
 class BirthdateFilter implements ExportElementValidatedInterface, FilterInterface
 {
+    use \Chill\MainBundle\Export\ExportDataNormalizerTrait;
     // add specific role for this filter
     public function addRole(): ?string
     {
@@ -28,7 +30,7 @@ class BirthdateFilter implements ExportElementValidatedInterface, FilterInterfac
     }
 
     // here, we alter the query created by Export
-    public function alterQuery(\Doctrine\ORM\QueryBuilder $qb, $data)
+    public function alterQuery(\Doctrine\ORM\QueryBuilder $qb, $data, \Chill\MainBundle\Export\ExportGenerationContext $exportGenerationContext): void
     {
         $where = $qb->getDQLPart('where');
         // we create the clause here
@@ -52,13 +54,13 @@ class BirthdateFilter implements ExportElementValidatedInterface, FilterInterfac
     }
 
     // we give information on which type of export this filter applies
-    public function applyOn()
+    public function applyOn(): string
     {
         return 'person';
     }
 
     // we build a form to collect some parameters from the users
-    public function buildForm(\Symfony\Component\Form\FormBuilderInterface $builder)
+    public function buildForm(\Symfony\Component\Form\FormBuilderInterface $builder): void
     {
         $builder->add('date_from', DateType::class, [
             'label' => 'Born after this date',
@@ -74,6 +76,18 @@ class BirthdateFilter implements ExportElementValidatedInterface, FilterInterfac
             'format' => 'dd-MM-yyyy',
         ]);
     }
+    public function getNormalizationVersion(): int
+    {
+        return 1;
+    }
+    public function normalizeFormData(array $formData): array
+    {
+        return ['date_from' => $this->normalizeDate($formData['date_from']), 'date_to' => $this->normalizeDate($formData['date_to'])];
+    }
+    public function denormalizeFormData(array $formData, int $fromVersion): array
+    {
+        return ['date_from' => $this->denormalizeDate($formData['date_from']), 'date_to' => $this->denormalizeDate($formData['date_to'])];
+    }
     public function getFormDefaultData(): array
     {
         return ['date_from' => new DateTime(), 'date_to' => new DateTime()];
@@ -81,7 +95,7 @@ class BirthdateFilter implements ExportElementValidatedInterface, FilterInterfac
 
     // here, we create a simple string which will describe the action of
     // the filter in the Response
-    public function describeAction($data, $format = 'string')
+    public function describeAction($data, ExportGenerationContext $context): string|\Symfony\Contracts\Translation\TranslatableInterface|array
     {
         return ['Filtered by person\'s birtdate: '
             . 'between %date_from% and %date_to%', [
@@ -90,7 +104,7 @@ class BirthdateFilter implements ExportElementValidatedInterface, FilterInterfac
             ], ];
     }
 
-    public function getTitle()
+    public function getTitle(): string|\Symfony\Contracts\Translation\TranslatableInterface
     {
         return 'Filter by person\'s birthdate';
     }
@@ -99,7 +113,7 @@ class BirthdateFilter implements ExportElementValidatedInterface, FilterInterfac
     // is executed here. This function is added by the interface
     // `ExportElementValidatedInterface`, and can be ignore if there is
     // no need for a validation
-    public function validateForm($data, ExecutionContextInterface $context)
+    public function validateForm($data, ExecutionContextInterface $context): void
     {
         $date_from = $data['date_from'];
         $date_to = $data['date_to'];

docs/source/_static/code/exports/CountPerson.php

@@ -36,6 +36,18 @@ class CountPerson implements ExportInterface
     {
         // this export does not add any form
     }
+    public function getNormalizationVersion(): int
+    {
+        return 1;
+    }
+    public function normalizeFormData(array $formData): array
+    {
+        return [];
+    }
+    public function denormalizeFormData(array $formData, int $fromVersion): array
+    {
+        return [];
+    }
     public function getFormDefaultData(): array
     {
         return [];
@@ -60,29 +72,29 @@ class CountPerson implements ExportInterface
         };
     }
 
-    public function getQueryKeys($data)
+    public function getQueryKeys($data): array
     {
         // this array match the result keys in the query. We have only
         // one column.
         return ['export_result'];
     }
 
-    public function getResult($query, $data)
+    public function getResult($query, $data, \Chill\MainBundle\Export\ExportGenerationContext $context): array
     {
         return $query->getQuery()->getResult(Query::HYDRATE_SCALAR);
     }
 
-    public function getTitle()
+    public function getTitle(): string|\Symfony\Contracts\Translation\TranslatableInterface
     {
         return 'Count peoples';
     }
 
-    public function getType()
+    public function getType(): string
     {
         return Declarations::PERSON_TYPE;
     }
 
-    public function initiateQuery(array $requiredModifiers, array $acl, array $data = [])
+    public function initiateQuery(array $requiredModifiers, array $acl, array $data, \Chill\MainBundle\Export\ExportGenerationContext $context): \Doctrine\ORM\QueryBuilder
     {
         // we gather all center the user choose.
         $centers = array_map(static fn ($el) => $el['center'], $acl);

docs/source/development/export-sequence.puml

@@ -0,0 +1,84 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+autonumber
+
+User -> ExportController: configure export using form
+activate ExportController
+ExportController -> ExportForm: build form
+activate ExportForm
+
+loop for every ExportElement (Filter, Aggregator)
+    ExportForm -> ExportElement: `buildForm`
+    activate ExportElement
+    ExportElement -> ExportForm: add form to builders
+    deactivate ExportElement
+end
+
+ExportForm -> ExportController
+deactivate ExportForm
+
+ExportController -> User: show form
+deactivate ExportController
+
+note left of User: Configure the export:\ncheck filters, aggregators, …
+
+User -> ExportController: post configuration of the export
+activate ExportController
+
+ExportController -> ExportForm: `getData`
+activate ExportForm
+ExportForm -> ExportController: return data: list of entities, etc.
+deactivate ExportForm
+
+loop for every ExportElement (Filter, Aggregator)
+    ExportController -> ExportElement: serializeData (data)
+    activate ExportElement
+    ExportElement -> ExportController: return serializedData (simple array with string, int, …)
+    deactivate ExportElement
+end
+
+ExportController -> Database: `INSERT INTO RequestGeneration_table` (insert new entity)
+ExportController -> MessageQueue: warn about a new request
+activate MessageQueue
+ExportController -> User: "ok, generation is in process"
+deactivate ExportController
+
+note left of User: The user see a waiting screen
+
+MessageQueue -> MessengerConsumer: forward the message to the MessengerConsumer
+deactivate MessageQueue
+activate MessengerConsumer
+MessengerConsumer -> Database: `SELECT * FROM RequestGeneration_table WHERE id = %s`
+activate Database
+Database -> MessengerConsumer: return RequestGeneration with serializedData
+deactivate Database
+
+loop for every ExportElement (Filter, Aggregator)
+    MessengerConsumer -> ExportElement: deserializeData
+    activate ExportElement
+    ExportElement -> MessengerConsumer: return data (list of entities, etc.) from the serialized array
+    deactivate ExportElement
+    MessengerConsumer -> ExportElement: alter the sql query (`ExportElement::alterQuery`)
+    activate ExportElement
+    ExportElement -> MessengerConsumer: return the query with WHERE and GROUP BY clauses
+    deactivate ExportElement
+end
+
+MessengerConsumer -> MessengerConsumer: prepare the export
+MessengerConsumer -> MessengerConsumer: save the export as a stored object
+MessengerConsumer -> Database: `UPDATE RequestGeneration_table SET ready = true`
+deactivate MessengerConsumer
+
+User -> ExportController: pull every 5s to know if the export is generated
+activate ExportController
+ExportController -> User: warn the export is generated
+deactivate ExportController
+
+User -> ExportController: download the export from object storage
+
+
+
+
+
+@enduml

docs/source/development/messages-to-users.rst

@@ -15,24 +15,31 @@ Messages to users, flashbags and buttons
 Flashbags
 ==========
 
-The four following levels are defined : 
+The four following levels are defined :
 
 +-----------+----------------------------------------------------------------------------------------------+
 |Key        |Intent                                                                                        |
 +===========+==============================================================================================+
-|alert      |A message not linked with the user action, but which should require an action or a            |
-|           |correction.                                                                                   |
-+-----------+----------------------------------------------------------------------------------------------+
 |success    |The user action succeeds.                                                                     |
 +-----------+----------------------------------------------------------------------------------------------+
 |notice     |A simple message to give information to the user. The message may be linked or not linked with|
 |           |the user action.                                                                              |
 +-----------+----------------------------------------------------------------------------------------------+
-|warning    |A message linked with an action, the user should correct.                                     |
-+-----------+----------------------------------------------------------------------------------------------+
 |error      |The user's action failed: he must correct something to process the action.                    |
 +-----------+----------------------------------------------------------------------------------------------+
 
+We can use :code:`TranslatableMessage` (and other :code:`TranslatableMessageInterface` instances) into the controller:
+
+.. code-block:: php
+
+   // in a controller action:
+   if (($session = $request->getSession()) instanceof Session) {
+       $session->getFlashBag()->add(
+           'success',
+           new TranslatableMessage('saved_export.Saved export is saved!')
+       );
+   }
+
 .. seealso::
 
    `Flash Messages on Symfony documentation <http://symfony.com/doc/current/book/controller.html#flash-messages>`_
@@ -66,7 +73,7 @@ To add the action on button, use them as class along with ``sc-button`` :
 |           |                | - Submitting this form will remove the entity                                |
 +-----------+----------------+------------------------------------------------------------------------------+
 | Edit      | ``bt-edit`` or | Link to a form to edit an entity                                             |
-|           | ``bt-update``  |                                                                              | 
+|           | ``bt-update``  |                                                                              |
 +-----------+----------------+------------------------------------------------------------------------------+
 | Save      | ``bt-save``    | Submitting this form will save change on the entity                          |
 +-----------+----------------+------------------------------------------------------------------------------+