From ae81e7be31a9ff36a6368139ad35389858d4c0ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 25 Mar 2021 22:44:48 +0100 Subject: [PATCH] add documentation for render and embeddable comments --- .../development/embeddable-comments.rst | 121 ++++++++++++++ docs/source/development/index.rst | 2 + docs/source/development/render-entity.rst | 154 ++++++++++++++++++ .../Templating/Entity/CommentRender.php | 1 - 4 files changed, 277 insertions(+), 1 deletion(-) create mode 100644 docs/source/development/embeddable-comments.rst create mode 100644 docs/source/development/render-entity.rst diff --git a/docs/source/development/embeddable-comments.rst b/docs/source/development/embeddable-comments.rst new file mode 100644 index 000000000..e14e8e84b --- /dev/null +++ b/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 `_. + +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 }} + + diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index b5d39e166..04f91ede1 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -29,6 +29,7 @@ As Chill rely on the `symfony `_ framework, reading the fram Searching Timelines Exports + Embeddable comments Testing Useful snippets manual/index.rst @@ -40,6 +41,7 @@ Layout and UI .. toctree:: :maxdepth: 2 + Render entities automatically Layout / Template usage Classes and mixins Widgets diff --git a/docs/source/development/render-entity.rst b/docs/source/development/render-entity.rst new file mode 100644 index 000000000..bfc579682 --- /dev/null +++ b/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 }} +
+ {# logic for rendering #} +
+ {{ 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`. + diff --git a/src/Bundle/ChillMainBundle/Templating/Entity/CommentRender.php b/src/Bundle/ChillMainBundle/Templating/Entity/CommentRender.php index 50fb2d35a..9ff0ca90c 100644 --- a/src/Bundle/ChillMainBundle/Templating/Entity/CommentRender.php +++ b/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;