Merge branch 'release/v1.5.0'

conf.py

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

developer/first-steps/docker.rst

@@ -8,15 +8,11 @@ to use for development. *Docker* on Linux will provide awesome performances and
 without bloating your development machine. Performances won't be as good on *macOS* or *Windows* hosts,
 but it will prevent installing singled versioned PHP and MySQL directly on your computer.
 
-First, copy ``.env.dist`` file to  ``.env`` and configure it according to your host machine.
+First, edit ``.env`` file and configure it according to your host machine (you can copy it from ``.env.dist``
+if it does not exist).
 
 .. code-block:: bash
 
-    # Copy sample environment variables
-    # and adjust them against your needs.
-    # Especially APP_PORT when you're working on several projects
-    cp .env.dist .env;
-
     # Build PHP image
     docker-compose build;
 

developer/first-steps/manual_config.rst

@@ -35,6 +35,35 @@ Roadiz uses *Doctrine ORM* to store your data. It will directly pass this YAML c
 you can use every available drivers and options from its documentation at
 http://doctrine-dbal.readthedocs.org/en/latest/reference/configuration.html
 
+Choose your inheritance model
+-----------------------------
+
+*Roadiz’* main feature is all about its polymorphic document model which is mapped on a relational database. This requires a
+challenging structure which can be lead to some performance bottlenecks when dealing with more than 20-30 node-types.
+So we made the data inheritance model configurable to allow switching to `single_table <https://www.doctrine-project.org/projects/doctrine-orm/en/2.7/reference/inheritance-mapping.html#single-table-inheritance>`_ scheme which will be more performant
+if you need lots of node-types. However *Single class* model will drop support for indexable fields and you won’t be able
+to create fields with the *same name but not the same type* because all node-type fields will be created in the **same SQL table**.
+
+If you really need to create indexable fields and to mix field types, we advise you to keep the original `joined table <https://www.doctrine-project.org/projects/doctrine-orm/en/2.7/reference/inheritance-mapping.html#class-table-inheritance>`_
+inheritance type which creates a dedicated SQL table for each node-type. *Joined table* inheritance can be very useful
+with a small number of node-type (max. 20) and very different fields. But its main drawback is that Roadiz needs to *LEFT JOIN*
+every node-type table for each node-source query, **unless you specify one node-type criteria**.
+
+You can configure *Doctrine* strategy for NodesSources inheritance classes in ``app/conf/config.yml``:
+
+.. code-block:: yaml
+
+    inheritance:
+        # type: joined
+        type: single_table
+
+- Joined class inheritance: ``joined``
+- Single table inheritance: ``single_table``
+
+.. warning::
+
+    If you change this setting after creating content in your website, all node-sources data will be lost.
+
 Themes
 ------
 
@@ -331,3 +360,4 @@ Make sure that every additional commands extend ``Symfony\Component\Console\Comm
 
     additionalCommands:
         - \Themes\DefaultTheme\Commands\DefaultThemeCommand
+

developer/first-steps/requirements.rst

@@ -29,7 +29,7 @@ Here is a short summary of mandatory elements before installing Roadiz:
     - ``register_globals = Off``
     - ``session.auto_start = Off``
 
-* MariaDB/MySQL/PostgreSQL or SQLite database (do not forget to install ``php-xxxsql`` extension according to your database driver flavor)
+* MariaDB 10.2.4+ or MySQL 5.7+ database with `JSON_*` functions support
 * Zip/Unzip
 * cUrl
 * Composer
@@ -77,6 +77,7 @@ CMS Structure
 -------------
 
 * ``bin/``: Contains the Roadiz CLI executable
+* ``docker/``: Tools for creating development and production *Docker* image for your project
 * ``app/``: Contains every runtime resources from configuration to app cache and nodes-sources entities
 
     * ``cache/``: Every cache file for *Twig* templates and `Intervention Request <https://github.com/roadiz/roadiz/releases>`_ images (this folder must be writable for PHP)
@@ -91,5 +92,5 @@ CMS Structure
     * ``files/``: Public documents (this folder must be writable for PHP)
     * ``themes/``: public assets mirror for each theme, this folder contains symlinks to your ``themes/YourTheme/static`` folder
 
-* ``themes/``: Contains your themes and system themes such as *Rozier* and *Install*
+* ``themes/``: Contains your own themes and all your website logic
 * ``vendor/``: Dependencies folder managed by *Composer*

developer/forms/contact_forms.rst

@@ -123,7 +123,7 @@ with it as an argument.
 
     $form = $contactFormManager->getForm();
 
-    // Assignate your form view to display it in Twig.
+    // Assign your form view to display it in Twig.
     $this->assignation['contactForm'] = $form->createView();
 
     return $this->render('blocks/contactformblock.html.twig', $this->assignation);
@@ -132,6 +132,25 @@ Then, in your *master* controller (i.e. ``PageController``), ``render`` method w
 catch your *ForceResponseException* exception in order to extract the forced response object. Then
 it will return your response instead of your page twig rendered output.
 
+Alter email configuration after form submit
+-------------------------------------------
+
+If you want to customize emails sent with form data, you can use Symfony form events to change the contact form manager
+options:
+The following example alters the email subject to add the user email and makes the subject unique for the receiver.
+
+.. code-block:: php
+
+   $formBuilder->addEventListener(FormEvents::SUBMIT, function (FormEvent $event) use ($contactFormManager) {
+      $contactFormManager->setSubject($contactFormManager->getSubject() . ': ' . $event->getForm()->get('email')->getData());
+   });
+
+You can also use this behaviour to change dynamically the contact form receiver after the user chose it in a select box input.
+
+.. note::
+
+   You can read more about form events at https://symfony.com/doc/current/form/events.html
+
 Securing your form with *Google reCAPTCHA*
 ------------------------------------------
 

developer/forms/custom_forms.rst

@@ -34,6 +34,7 @@ if you used ``{{ nodeSource|render(@AwesomeTheme) }}`` Twig filter.
     use RZ\Roadiz\Core\Entities\CustomForm;
     use RZ\Roadiz\Core\Exceptions\EntityAlreadyExistsException;
     use RZ\Roadiz\Core\Exceptions\ForceResponseException;
+    use Symfony\Cmf\Component\Routing\RouteObjectInterface;
     use RZ\Roadiz\Utils\CustomForm\CustomFormHelper;
     use Symfony\Component\Form\FormError;
     use Symfony\Component\HttpFoundation\JsonResponse;
@@ -80,7 +81,10 @@ if you used ``{{ nodeSource|render(@AwesomeTheme) }}`` Twig filter.
                             $request,
                             $this->getTranslator()->trans('form_has_been_successfully_sent')
                         );
-                        $response = $this->redirect($this->generateUrl($this->nodeSource->getParent()));
+                        $response = $this->redirect($this->generateUrl(
+                            RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+                            [RouteObjectInterface::ROUTE_OBJECT => $this->nodeSource->getParent()]
+                        ));
                     }
                     /*
                      * If you are in a BlockController use ForceResponseException

developer/nodes-system/node_type_fields.rst

@@ -39,15 +39,14 @@ This following fields stores simple data in your custom node-source database tab
 
 .. note ::
     *Single geographic coordinates* field stores its data in JSON format. Make sure you
-    don’t have manually writen data in its input field.
+    don’t have manually written data in its input field.
 
 .. warning ::
     To use *Single geographic coordinates* you must create a *Google API Console* account with *Maps API v3* activated.
     Then, create a *Browser key* and paste it in “Google Client ID” parameter in Roadiz settings
-    to enable *geographic* node-type fields. If you didn’t do it, a simple text input will
+    to enable *geographic* node-type fields. If you didn't do it, a simple text input will
     be display instead of *Roadiz Map Widget*.
 
-
 .. image:: ./img/field-types.*
    :align: center
    :width: 300

developer/nodes-system/nodes.rst

@@ -70,7 +70,7 @@ origin node-source.
         'node.visible': true
     }) %}
 
-If you need to trasverse node-source graph from your controllers you can use
+If you need to traverse node-source graph from your controllers you can use
 the *Entity API*. Moreover, Nodes-sources API allows you to filter using custom criteria if you choose a specific ``NodeType``.
 
 .. code-block:: php
@@ -191,6 +191,8 @@ You can use ``generateUrl()`` in your controllers to get a node-source’ path o
 
 .. code-block:: php
 
+    use Symfony\Cmf\Component\Routing\RouteObjectInterface;
+
     class BlogPostController extends MyAwesomeTheme
     {
         public function indexAction(
@@ -201,12 +203,15 @@ You can use ``generateUrl()`` in your controllers to get a node-source’ path o
             $this->prepareThemeAssignation($node, $translation);
 
             // Generate a path for current node-source
-            $path = $this->generateUrl($this-nodeSource);
+            $path = $this->generateUrl(
+                RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+                [RouteObjectInterface::ROUTE_OBJECT => $this->nodeSource]
+            );
 
             // Generate an absolute URL for current node-source
             $absoluteUrl =  $this->generateUrl(
-                $this->nodeSource,
-                [],
+                RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+                [RouteObjectInterface::ROUTE_OBJECT => $this->nodeSource],
                 UrlGeneratorInterface::ABSOLUTE_URL
             );
         }

developer/services/glossary.rst

@@ -470,6 +470,12 @@ Security
     accessDeniedHandler
         ``RZ\Roadiz\Core\Authorization\AccessDeniedHandler``
 
+    nodeChrootResolvers
+        ``array<RZ\Roadiz\Core\Authorization\Chroot\NodeChrootResolver>``
+
+    RZ\Roadiz\Core\Authorization\Chroot\NodeChrootResolver
+        ``RZ\Roadiz\Core\Authorization\Chroot\NodeChrootChainResolver``
+
 Serialization
 ^^^^^^^^^^^^^
 
@@ -616,3 +622,30 @@ Utils
 
     utils.universalDataDuplicator
         ``RZ\Roadiz\Utils\Node\UniversalDataDuplicator``
+
+
+OpenId
+^^^^^^
+
+.. glossary::
+
+    RZ\Roadiz\OpenId\OAuth2LinkGenerator:
+        ``RZ\Roadiz\OpenId\OAuth2LinkGenerator``
+
+    jwtRoleStrategies
+        ``array<RZ\Roadiz\OpenId\Authentication\Provider\JwtRoleStrategy>``
+
+    RZ\Roadiz\OpenId\Authentication\Provider\JwtRoleStrategy
+        ``RZ\Roadiz\OpenId\Authentication\Provider\ChainJwtRoleStrategy``
+
+    RZ\Roadiz\OpenId\Authentication\Provider\OAuth2AuthenticationProvider
+        ``RZ\Roadiz\OpenId\Authentication\Provider\OAuth2AuthenticationProvider``
+
+    RZ\Roadiz\OpenId\Authentication\Provider\OpenIdAccountProvider
+        ``RZ\Roadiz\OpenId\Authentication\Provider\OpenIdAccountProvider``
+
+    RZ\Roadiz\OpenId\Discovery
+        ``RZ\Roadiz\OpenId\Discovery`` or ``null``
+
+    oauth2AuthenticationProvider.validators:
+        ``array<RZ\Roadiz\OpenId\Authentication\Validator\JwtValidator>``

developer/themes/display_documents.rst

@@ -33,18 +33,18 @@ Now, you can use the ``DocumentViewer`` service to generate HTML view for your
 HTML output options
 -------------------
 
-* **absolute** (true|false), generates an *absolute* URL with protocol, domain-name and base-url. This must be used for social network images.
-* **embed** (true|false), display an embed as iframe instead of its thumbnail
+* **absolute** (true|false, default: ``false``), generates an *absolute* URL with protocol, domain-name and base-url. This must be used for social network images.
+* **embed** (true|false, default: ``false``), display an embed as iframe instead of its thumbnail
 * **identifier**
 * **class**
 * **alt**: If not filled, it will get the document name, then the document filename
-* **lazyload** (true|false), fill image src in a ``data-src`` attribute instead of ``src`` to prevent it from loading. It will add automatically ``lazyload_class`` class to your HTML image.
+* **lazyload** (true|false, default: ``false``), fill image src in a ``data-src`` attribute instead of ``src`` to prevent it from loading. It will add automatically ``lazyload_class`` class to your HTML image.
 * **lazyload_class** (default: ``lazyload``) Class name to be added when enabling lazyloading.
 * **fallback** (URL|data-uri) Defines a custom fallback image URL or *data-uri* when using ``lazyload`` option in order to fill ``src`` attribute and validate against W3C
 * **blurredFallback** (false|true, default: ``false``) Generated a very low quality image version for lazyload fallback to better control image size and better experience.
-* **picture** (false|true), use ``<picture>`` element instead of image and allow serving WebP image to compatibles browsers. **Only use if your server support WebP**.
-* **inline** (true|false), **for SVG**, display SVG inline code in html instead of using an ``<object>`` tag. Default ``true``.
-* **loading** (auto|lazy|eager), for next-gen browser only that will support native lazy-loading. This will be applied only on `img`, `picture` and `iframe` elements. *This can fail W3C validation*.
+* **picture** (false|true, default: ``false``), use ``<picture>`` element instead of image and allow serving WebP image to compatibles browsers. **Only use if your server support WebP**.
+* **inline** (true|false, default: ``true``), **for SVG**, display SVG inline code in html instead of using an ``<object>`` tag. Default ``true``.
+* **loading** (auto|lazy|eager|null, default: ``null``), for next-gen browser only that will support native lazy-loading. This will be applied only on `img`, `picture` and `iframe` elements. *This can fail W3C validation*.
 
 Images resampling options
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -63,59 +63,60 @@ Images resampling options
     * bottom-left
     * bottom
     * bottom-right
-* **grayscale** (boolean)
-* **quality** (1-100)
+* **grayscale** (boolean, default: ``false``)
+* **quality** (1-100, default: ``90``)
 * **flip** (``h`` or ``v``), mirror your image vertical or horizontal
-* **blur** (1-100) *(can be really slow to process)*
-* **sharpen** (1-100)
-* **contrast** (1-100)
+* **blur** (1-100, default: ``0``) *(can be really slow to process)*
+* **sharpen** (1-100, default: ``0``)
+* **contrast** (1-100, default: ``0``)
 * **background** (hexadecimal color without #)
-* **progressive** (boolean), it will interlace the image if it’s a *PNG* file.
-* **noProcess** (boolean): Disable image processing
+* **progressive** (boolean, default: ``false``), it will interlace the image if it’s a *PNG* file.
+* **noProcess** (boolean, default: ``false``): Disable image processing, useful if you want to keep animated GIF
 
 Audio / Video options
 ^^^^^^^^^^^^^^^^^^^^^
 
-* **autoplay** (boolean)
-* **controls** (boolean)
-* **loop** (boolean)
-* **muted** (boolean)
+* **autoplay** (boolean, default: ``false``)
+* **controls** (boolean, default: ``true``)
+* **loop** (boolean, default: ``false``)
+* **muted** (boolean, default: ``false``)
 * **custom_poster** (string): URL to a image to be used as video poster
 
 For *Soundcloud* embeds
 
-* **hide_related** (boolean)
-* **show_comments** (boolean)
-* **show_user** (boolean)
-* **show_reposts** (boolean)
-* **visual** (boolean)
+* **hide_related** (boolean, default: ``false``)
+* **show_comments** (boolean, default: ``false``)
+* **show_user** (boolean, default: ``false``)
+* **show_reposts** (boolean, default: ``false``)
+* **visual** (boolean, default: ``false``)
 
 For *Mixcloud* embeds
 
-* **mini** (boolean) defaults to ``false``
-* **light** (boolean) defaults to ``true``
-* **hide_cover** (boolean) defaults to ``true``
-* **hide_artwork** (boolean) defaults to ``false``
+* **mini** (boolean, default: ``false``)
+* **light** (boolean, default: ``true``)
+* **hide_cover** (boolean, default: ``true``)
+* **hide_artwork** (boolean, default: ``false``)
 
 For *Vimeo* embeds
 
-* **displayTitle** (boolean)
-* **byline** (boolean)
-* **portrait** (boolean)
+* **displayTitle** (boolean, default: ``false``)
+* **byline** (boolean, default: ``false``)
+* **portrait** (boolean, default: ``false``)
 * **color** (boolean)
-* **api** (boolean)
-* **automute** (boolean)
-* **autopause** (boolean)
+* **api** (boolean, default: ``true``)
+* **automute** (boolean, default: ``false``)
+* **autopause** (boolean, default: ``false``)
 
 For *Youtube* `embeds <https://developers.google.com/youtube/player_parameters>`_
 
-* **modestbranding** (boolean)
-* **rel** (boolean)
-* **showinfo** (boolean)
-* **start** (integer)
-* **end** (integer)
-* **enablejsapi** (boolean)
-* **playlist** (boolean)
+* **modestbranding** (boolean, default: ``true``)
+* **rel** (boolean, default: ``false``)
+* **showinfo** (boolean, default: ``false``)
+* **start** (integer, default: ``false``)
+* **end** (integer, default: ``false``)
+* **enablejsapi** (boolean, default: ``true``)
+* **playlist** (boolean, default: ``false``)
+* **playsinline** (boolean, default: ``false``): Allow iframe to play inline on iOS
 
 You can use **multiple source files** for one video document or audio document.
 Just upload a file using tge same filename name but with a different extension. Use this method to
@@ -265,7 +266,7 @@ You can find more details in `our API documentation <http://api.roadiz.io/RZ/Roa
 * If document is an **image**: ``getDocumentByArray`` method will generate an ``<img />`` tag with a ``src`` and ``alt`` attributes.
 * If it’s a **video**, it will generate a ``<video />`` tag with as many sources as available in your document database. Roadiz will look for same filename with each HTML5 video extensions (filename.mp4, filename.ogv, filename.webm).
 * Then if document is an external media **and** if you set the ``embed`` flag to ``true``, it will generate an iframe according to its platform implementation (*Youtube*, *Vimeo*, *Soundcloud*).
-* Get the external document URI (the one used for creating iframe for example) with ``(document|embedFinder).source`` twig command.
+* Get the external document URI (the one used for creating iframe for example) with ``(document|embedFinder).source(options…)`` twig command.
 
 Manage global documents
 -----------------------
@@ -275,7 +276,7 @@ Simply create a new *setting* in Roadiz back-office choosing *Document* type, th
 
 To use this document setting in your theme, you can assign it globally in your ``MyThemeApp::extendAssignation`` method.
 Use ``getDocument`` method instead of ``get`` to fetch a ``Document`` object  that you’ll be able to display in
-your Twig templates: 
+your Twig templates:
 
 .. code-block:: php
 

developer/themes/using_twig.rst

@@ -52,7 +52,7 @@ in order to make page content available from your Twig template.
     * **keywords** — [string]
 
 All these data will be available in your Twig template using ``{{ }}`` syntax.
-For example use ``{{ pageMeta.title }}`` inside your head’s ``<title>`` tag.
+For example use ``{{ pageMeta.title }}`` inside your head’s ``<title>`` tag.
 You can of course call objects members within Twig using the *dot* separator.
 
 .. code-block:: html+jinja