add documentation for render and embeddable comments

docs/source/development/embeddable-comments.rst

@@ -0,0 +1,121 @@
+
+.. 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".
+
+
+Embeddable comments
+###################
+
+Those embeddable comments is a comment with some metadata:
+
+* the one who updated the comment (the comment itself, and not the whole entity);
+* the date and time for the last update (again, the comment itself, and not the whole entity).
+
+We make usage of `embeddables <https://www.doctrine-project.org/projects/doctrine-orm/en/2.8/tutorials/embeddables.html>`_.
+
+Embed the comment
+=================
+
+The comment may be embedded into the entity:
+
+.. code-block:: php
+
+   namespace Chill\ActivityBundle\Entity;
+
+   use Chill\MainBundle\Entity\Embeddable\CommentEmbeddable;
+   use Doctrine\ORM\Mapping as ORM;
+
+   /**
+    * Class Activity
+    *
+    * @ORM\Entity()
+    */
+   class Activity
+   {
+       /**
+        * @var integer
+        *
+        * @ORM\Id
+        * @ORM\Column(name="id", type="integer")
+        * @ORM\GeneratedValue(strategy="AUTO")
+        */
+       private $id;
+
+       /**
+        * @ORM\Embedded(class="Chill\MainBundle\Entity\Embeddable\CommentEmbeddable", columnPrefix="comment_")
+        */
+       private $comment;
+
+
+       /**
+        * @return \Chill\MainBundle\Entity\Embeddalbe\CommentEmbeddable
+        */
+       public function getComment()
+       {
+           return $this->comment;
+       }
+
+       /**
+        * @param \Chill\MainBundle\Entity\Embeddalbe\CommentEmbeddable $comment
+        */
+       public function setComment($comment)
+       {
+           $this->comment = $comment;
+       }
+   }
+
+Note on relation to :class:`User`
+=================================
+
+The embeddable proposed by Doctrine does not support relationship to other entities. The entity Comment is able to render a user's id, but not an User object.
+
+
+.. code-block:: php
+
+   $activity->getComment()->getUserId(); // return user id of the last author
+
+   $activity->getComment()->getUser(); // does not work !
+
+
+Usage into form
+===============
+
+Use the :class:`Chill\MainBundle\Form\Type\CommentType` to load the form widget:
+
+.. code-block:: php
+
+   namespace Chill\ActivityBundle\Form;
+
+   use Chill\MainBundle\Form\Type\CommentType;
+   use Symfony\Component\Form\AbstractType;
+   use Symfony\Component\Form\FormBuilderInterface;
+
+   class ActivityType extends AbstractType
+   {
+       /**
+        * @param FormBuilderInterface $builder
+        * @param array $options
+        */
+       public function buildForm(FormBuilderInterface $builder, array $options)
+       {
+           $builder
+               ->add('comment', CommentType::class, [
+                   'required' => false,
+               ])
+           ;
+       }
+   }
+
+Render the comment
+==================
+
+.. code-block:: twig
+
+   {{ activity.comment|chill_entity_render_box }}
+
+

docs/source/development/index.rst

@@ -29,6 +29,7 @@ As Chill rely on the `symfony <http://symfony.com>`_ framework, reading the fram
     Searching <searching.rst>
     Timelines <timelines.rst>
     Exports <exports.rst>
+    Embeddable comments <embeddable-comments.rst>
     Testing <make-test-working.rst>
     Useful snippets <useful-snippets.rst>
     manual/index.rst
@@ -40,6 +41,7 @@ Layout and UI
 .. toctree::
    :maxdepth: 2
 
+   Render entities automatically <render-entity.rst>
    Layout / Template usage <user-interface/layout-template-usage.rst>
    Classes and mixins <user-interface/css-classes.rst>
    Widgets <user-interface/widgets.rst>

docs/source/development/render-entity.rst

@@ -0,0 +1,154 @@
+
+Rendering entity automatically
+##############################
+
+Some entity need to be rendered automatically for a couple of times: a person, a user, ...
+
+One can use some twig filter to render those entities:
+
+.. code-block:: twig
+
+   {{ person|chill_entity_render_box }}
+
+Define a renderer
+=================
+
+By default, the object passed through the renderer will be rendered using the :code:`__toString()` method. To customize this behaviour, you have to define a service and tag it using :code:`chill.render_entity`.
+
+The rendered is implemented using :class:`Chill\MainBundle\Templating\Entity\ChillEntityRenderInterface`. This interface has 3 methods:
+
+* :code:`public function supports($entity, array $options): bool`: return true if the :code:`$entity` given in parameter, with custom options, is supported by this renderer;
+* :code:`public function renderString($entity, array $options): string`: render the entity as a single string, for instance in a select list;
+* :code:`public function renderBox($entity, array $options): string`: render the entity in an html box.
+
+.. warning::
+
+   The HTML returned by :code:`renderBox` **MUST BE SAFE** of any XSS injection.
+
+:class:`Chill\MainBundle\Templating\Entity\AbstractChillEntityRender` provides some useful methods to get the opening and closing boxes that should be used.
+
+Usage about rendering comment:
+
+.. code-block:: php
+
+   namespace Chill\MainBundle\Templating\Entity;
+
+   use Chill\MainBundle\Entity\Embeddable\CommentEmbeddable;
+   use Chill\MainBundle\Repository\UserRepository;
+   use Chill\MainBundle\Templating\Entity\AbstractChillEntityRender;
+   use Symfony\Component\Templating\EngineInterface;
+
+   class CommentRender extends AbstractChillEntityRender
+   {
+       /**
+        * @var \Chill\MainBundle\Repository\UserRepository
+        */
+       private $userRepository;
+
+       /**
+        *
+        * @var EngineInterface
+        */
+       private $engine;
+
+       public function __construct(
+           UserRepository $userRepository,
+           EngineInterface $engine
+       ) {
+           $this->userRepository = $userRepository;
+           $this->engine = $engine;
+       }
+
+       /**
+        * @param CommentEmbeddable $entity
+        * @param array $options
+        *
+        * @return string
+        */
+       public function renderBox($entity, array $options): string
+       {
+           // default options
+           $options = \array_merge([
+                   'user' => [],
+                   'disable_markdown' => false,
+                   'limit_lines' => null,
+                   'metadata' => true
+               ], $options);
+
+           if ($entity->getUserId()) {
+               $user = $this->userRepository->find($entity->getUserId());
+           }
+
+           return $this->engine
+               ->render(
+                   '@ChillMain/Entity/CommentEmbeddable.html.twig',
+                   [
+                       'opening_box' => $this->getDefaultOpeningBox('comment-embeddable'),
+                       'closing_box' => $this->getDefaultClosingBox(),
+                       'user' => $user ?? NULL,
+                       'comment' => $entity,
+                       'options' => $options
+                   ]
+               );
+       }
+
+       /**
+        * @param CommentEmbeddable $entity
+        * @param array $options
+        *
+        * @return string
+        */
+       public function renderString($entity, array $options): string
+       {
+           return $entity->getComment();
+       }
+
+       public function supports($entity, array $options): bool
+       {
+           return $entity instanceof CommentEmbeddable;
+       }
+   }
+
+Logic inside the template:
+
+.. code-block:: twig
+
+   {{ opening_box|raw }}
+   <div>
+      {# logic for rendering #}
+   </div> 
+   {{ closing_box|raw }}
+
+Usage in templates
+==================
+
+For rendering entity as a box:
+
+.. code-block:: twig
+
+   {{ entity|chill_entity_render_box }}
+
+For rendering entity as a string:
+
+.. code-block:: twig
+
+   {{ entity|chill_entity_render_string }}
+
+Available renderer and options
+==============================
+
+:code:`Person` (Person Bundle)
+------------------------------
+
+* no options
+
+:code:`CommentEmbeddable` (Main Bundle)
+---------------------------------------
+
+Options:
+
+* :code:`user`: options which will be passed to "user" renderer
+* :code:`disable_markdown`: disable markdown renderer, default to :code:`FALSE`
+* :code:`limit_lines` (integer) limit the number of lines. Default to :code:`NULL`. May be an integer.
+* :code:`metadata` (boolean): show the last updating user and last updating date. Default to :code:`TRUE`.
+

src/Bundle/ChillMainBundle/Templating/Entity/CommentRender.php

@@ -21,7 +21,6 @@
 namespace Chill\MainBundle\Templating\Entity;
 
 use Chill\MainBundle\Entity\Embeddable\CommentEmbeddable;
-use Chill\MainBundle\Entity\User;
 use Chill\MainBundle\Repository\UserRepository;
 use Chill\MainBundle\Templating\Entity\AbstractChillEntityRender;
 use Symfony\Component\Templating\EngineInterface;