chill-bundles/docs/source/development/render-entity.md

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:

   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:

   {# @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.