Change all content from rst format to markdown and correct spelling/grammar

docs/source/development/render-entity.md

@@ -0,0 +1,140 @@
+# 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:
+
+   {{ person|chill_entity_render_box }}
+
+## Define a renderer
+
+By default, the object passed through the renderer will be rendered using the `__toString()` method. To customize this behaviour, you have to define a service and tag it using `chill.render_entity`.
+
+The rendered is implemented using :class:`Chill\MainBundle\Templating\Entity\ChillEntityRenderInterface`. This interface has 3 methods:
+
+* `public function supports($entity, array $options): bool`: return true if the `$entity` given in parameter, with custom options, is supported by this renderer;
+* `public function renderString($entity, array $options): string`: render the entity as a single string, for instance in a select list;
+* `public function renderBox($entity, array $options): string`: render the entity in a HTML box.
+
+   The HTML returned by `renderBox` **MUST BE SAFE** of any XSS injection.
+
+`Chill\MainBundle\Templating\Entity\AbstractChillEntityRender` provides some useful methods to get the opening and closing boxes that should be used.
+
+Usage about rendering comment:
+
+```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:
+
+```twig
+   {# @var opening_box: string #}
+   {# @var closing_box: string #}
+   {{ opening_box|raw }}
+   <div>
+      {# logic for rendering #}
+   </div>
+   {{ closing_box|raw }}
+```
+
+## Usage in templates
+
+For rendering an entity as a box:
+
+   `{{ entity|chill_entity_render_box }}`
+
+For rendering an entity as a string:
+
+   `{{ entity|chill_entity_render_string }}`
+
+## Available renderer and options
+
+### `Person` (Person Bundle)
+
+* no options
+
+### `CommentEmbeddable` (Main Bundle)
+
+Options :
+
+* `user`: options, which will be passed to "user" renderer
+* `disable_markdown`: disable markdown renderer, default to `FALSE`
+* `limit_lines` (integer) limit the number of lines. Default to `NULL`. Can be an integer.
+* `metadata` (boolean): show the last updating user and last updating date. Default to `TRUE`.