From 75c586fbf85fe0d56e019ecd2295c030bf4af1e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julien=20Fastr=C3=A9?= <julien.fastre@champs-libres.coop>
Date: Wed, 26 May 2021 17:58:58 +0200
Subject: [PATCH] fix documentation for timeline

---
 docs/source/development/timelines.rst | 37 ++++++++++++++++-----------
 1 file changed, 22 insertions(+), 15 deletions(-)

diff --git a/docs/source/development/timelines.rst b/docs/source/development/timelines.rst
index a8d0ff0be..afabdb398 100644
--- a/docs/source/development/timelines.rst
+++ b/docs/source/development/timelines.rst
@@ -97,7 +97,7 @@ The has the following signature :
          * 
          * @param string $context
          * @param mixed[] $args the argument to the context.
-         * @return string[]
+         * @return TimelineSingleQuery
          * @throw  \LogicException if the context is not supported
          */
         public function fetchQuery($context, array $args);
@@ -163,18 +163,16 @@ The has the following signature :
 The `fetchQuery` function
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The fetchQuery function help to build the UNION query to gather events. This function should return an associative array MUST have the following key :
+The fetchQuery function help to build the UNION query to gather events. This function should return an instance of :code:`TimelineSingleQuery`. For you convenience, this object may be build using an associative array with the following keys:
 
 * `id` : the name of the id column
 * `type`: a string to indicate the type
 * `date`: the name of the datetime column, used to order entities by date
-* `FROM` (in capital) : the FROM clause. May contains JOIN instructions
+* `FROM`: the FROM clause. May contains JOIN instructions
+* `WHERE`: the WHERE clause;
+* `parameters`: the parameters to pass to the query
 
-Those key are optional:
-
-* `WHERE` (in capital) : the WHERE clause. 
-
- Where relevant, the data must be quoted to avoid SQL injection.
+The parameters should be replaced into the query by :code:`?`. They will be replaced into the query using prepared statements.
 
 `$context` and `$args` are defined by the bundle which will call the timeline rendering. You may use them to build a different query depending on this context.
 
@@ -186,6 +184,15 @@ For instance, if the context is `'person'`, the args will be this array :
         'person' => $person //a \Chill\PersonBundle\Entity\Person entity
     );
 
+For the context :code:`center`, the args will be:
+
+.. code-block:: php
+
+    array(
+        'centers' => [ ]  // an array of \Chill\MainBundle\Entity\Center entities
+    );
+
+
 You should find in the bundle documentation which contexts are arguments the bundle defines.
 
 .. note::
@@ -199,13 +206,12 @@ Example of an implementation :
     namespace Chill\ReportBundle\Timeline;
 
     use Chill\MainBundle\Timeline\TimelineProviderInterface;
+    use Chill\MainBundle\Timeline\TimelineSingleQuery;
     use Doctrine\ORM\EntityManager;
 
     /**
      * Provide report for inclusion in timeline
      *
-     * @author Julien Fastré <julien.fastre@champs-libres.coop>
-     * @author Champs Libres <info@champs-libres.coop>
      */
     class TimelineReportProvider implements TimelineProviderInterface
     {
@@ -227,16 +233,17 @@ Example of an implementation :
                 
                 $metadata = $this->em->getClassMetadata('ChillReportBundle:Report');
                 
-                return array(
+                return TimelineSingleQuery::fromArray([
                    'id' => $metadata->getColumnName('id'),
                    'type' => 'report',
                    'date' => $metadata->getColumnName('date'),
                    'FROM' => $metadata->getTableName(),
-                   'WHERE' => sprintf('%s = %d',
+                   'WHERE' => sprintf('%s = ?',
                          $metadata
-                            ->getAssociationMapping('person')['joinColumns'][0]['name'],
-                         $args['person']->getId())
-                );
+                            ->getAssociationMapping('person')['joinColumns'][0]['name'])
+                         )
+                   'parameters' => [ $args['person']->getId() ]
+                ]);
             }
 
         //....