Merge branch 'hotfix/v1.5.1'

conf.py

@@ -105,9 +105,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.5.3'
+version = '1.5.4'
 # The full version, including alpha/beta/rc tags.
-release = '1.5.3'
+release = '1.5.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

developer/forms/contact_forms.rst

@@ -23,7 +23,7 @@ Here is an example to create your contact form in your controller action.
     use Symfony\Component\Form\Extension\Core\Type\FileType;
     use Symfony\Component\Form\Extension\Core\Type\SubmitType;
 
-    …
+    // …
     // Create contact-form manager and add 3 default fields.
     $contactFormManager = $this->createContactFormManager()
                                ->withDefaultFields();
@@ -174,15 +174,22 @@ Do not forget to add recaptcha form-template and to embed google’s javascript.
 
 .. code-block:: html
 
+    {# Recaptcha v2 #}
     <script src='https://www.google.com/recaptcha/api.js'></script>
 
 .. code-block:: html+jinja
 
     {# In your theme’ forms.html.twig file #}
     {% block recaptcha_widget -%}
+        {# Recaptcha v2 #}
         <div class="g-recaptcha" data-sitekey="{{ configs.publicKey }}"></div>
     {%- endblock recaptcha_widget %}
 
+.. note::
+
+   Backend logic with Google Recaptcha is compatible with v2 **and** v3. You’ll need to adapt your
+   frontend logic.
+
 Sending contact form and accept application/json
 ------------------------------------------------
 

developer/themes/custom_assignations.rst

@@ -112,7 +112,7 @@ parts. At first we used to create long node-types with a lot of fields, and when
 editors needed to move content to an other position, they had to cut and paste text
 to another field. It was long and not very sexy.
 
-So we thought about a modulable way to build pages. We decided to use one master node-type and
+So we thought about a modular way to build pages. We decided to use one master node-type and
 several slave node-types instead of a single big type. Here is what we call **Page/Block pattern**.
 
 This pattern takes advantage of Roadiz node hierarchy. We create a very light *Page* node-type, with
@@ -139,10 +139,16 @@ Make sure the global ``bags`` service is available and reachable.
 
 .. code-block:: html+jinja
 
+    {# Fetch only BasicBlock nodes inside #}
     {% set blocks = nodeSource|children({
         node.nodeType : bags.nodeTypes.get('BasicBlock'),
     }) %}
 
+    {# Fetch ALL non-reachable nodes inside #}
+    {% set blocks = nodeSource|children({
+        node.nodeType.reachable : false,
+    }) %}
+
 .. note::
     You can use different *block* types in the same *page*. Just create as many
     node-types as you need and add their name to your *Page* ``children_node`` default values.
@@ -157,7 +163,7 @@ Now we can update your ``types/page.html.twig`` template to use your assignated
     {% if blocks %}
     <section class="page-blocks">
     {% for pageBlock in blocks %}
-        {% include '@MyTheme/blocks/' ~ pageBlock.node.nodeType.name|lower ~ '.html.twig' with {
+        {% include '@MyTheme/blocks/' ~ pageBlock.nodeTypeName|u.snake ~ '.html.twig' with {
             'nodeSource': pageBlock,
             'parentNodeSource': nodeSource,
             'themeServices': themeServices,
@@ -206,6 +212,52 @@ This is the simplest example to demonstrate you the power of *Page / Block*
 pattern. If you managed to reproduce this example you can now try it using
 multiple *block* node-types, combining multiple sub-templates.
 
+Use a TreeWalker to control your node hierarchy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Page/Block* pattern is really powerful and is the foundation for almost every Rezo Zero websites. But this
+approach can lead to performance issues if developers do not specify each available node-types for each child.
+Thus, we wanted to remove this ORM logic from your Twig templates, in order to comply with MVC pattern, but more important,
+in order to expose node hierarchy into a REST JSON API.
+
+Rezo Zero developed a `third-party library <https://github.com/rezozero/tree-walker>`_: ``rezozero/tree-walker`` which aims to abstract node hierarchy from the context and the CMS where it is used.
+
+.. code-block:: shell
+
+    composer require rezozero/tree-walker
+
+A ``TreeWalker`` is a traversable object you will be able to loop on in your Twig template, but also to serialize into
+a JSON object. This TreeWalker object can be configured with *definitions* in order to fetch next-level objects
+from your *database*, your CMS, or even an external API. That way you instantiate a new TreeWalker with a *root* object
+and by simply traversing it, it will trigger a fetch operation (``getChildren``) which will look for
+the right definition for the *root* object ``class``. Then "tree walking" operation goes on for each of your *root*
+object children until your definitions list is empty or when you reached the max-level limit.
+
+Here is an example of what the *Page/Block* pattern looks like using a *block tree-walker*:
+
+.. code-block:: html+jinja
+
+    {% if blockWalker %}
+        <div class="page-blocks">
+            {% for subWalker in blockWalker %}
+                {% include '@MyTheme/blocks/' ~ subWalker.item.nodeTypeName|u.snake ~ '.html.twig' ignore missing with {
+                    'nodeSource': subWalker.item,
+                    'parentNodeSource': nodeSource,
+                    'themeServices': themeServices,
+                    'head': head,
+                    'node': subWalker.item.node,
+                    'nodeType': subWalker.item.node.nodeType,
+                    'loop': loop,
+                    'blockWalker': subWalker,
+                    'blocksLength': blockWalker|length
+                } only %}
+            {% endfor %}
+        </div>
+    {% endif %}
+
+Frontend developers do not need to know how to fetch children blocks anymore, they just need to loop over the *tree-walker*
+at each template level.
+
 Use block rendering
 -------------------
 

developer/themes/display_documents.rst

@@ -23,7 +23,6 @@ Now, you can use the ``DocumentViewer`` service to generate HTML view for your
     {% if image %}
     {{ image|display({
         'width':200,
-        'height':200,
         'crop':"1:1",
         'quality':75,
         'embed':true
@@ -51,7 +50,7 @@ Images resampling options
 
 * **width**
 * **height**
-* **crop** (ratio: ``{w}:{h}``, for example : ``16:9``)
+* **crop** (ratio: ``{w}:{h}``, for example : ``16:9``), defines a ratio for cropping images. **You must combine ``crop`` option with ``width`` or ``height`` option**, otherwise you’ll end with a cyclic dependency to compute output image size. We recommend you to use ``fit`` option with *final image size* to better control output: ``crop`` may lose precision on width or height especially on small sizes.
 * **fit** (fixed dimensions: ``{w}x{h}``, for example : ``100x200``), if you are using *fit* option, Roadiz will be able to add ``width`` and ``height`` attributes to your ``<img>`` tag.
 * **align**, to use along with ``fit`` parameter to choose which part of the picture to fit. Allowed options:
     * top-left
@@ -171,6 +170,8 @@ This will output an ``img`` tag like the following one:
     <img src="/assets/f600x600-q75/image.jpg"
          srcset="/assets/f600x600-q75/image.jpg 1200w, /assets/f200x200-q90/image.jpg 780w"
          sizes="(max-width: 780px) 200px, (max-width: 1200px) 600px"
+         data-ratio="1"
+         width="600" height="600"
          alt="A responsive image">
 
 Generate <picture> elements
@@ -255,6 +256,7 @@ This will output a ``picture`` element supporting :
 
         <img alt="file.jpg"
              src="/assets/f640x400-q75/folder/file.jpg"
+             data-ratio="1.6"
              width="640" height="400" />
     </picture>