EZP-30869: Extending login form view (#748)

docs/guide/user_management.md

@@ -12,7 +12,7 @@ When the user requests a reset of a forgotten password, an email is sent to them
 It allows them to create a new password.
 
 The template for this email is located in `templates/Security/mail/forgot_user_password.html.twig` in `ezsystems/ezplatform-user`.
-You can customize it according to your needs.
+You can [customize it according to your needs](#customize-login-form).
 
 The validity of the password recovery token can be set using the `ezplatform.system.<siteaccess>.security.token_interval_spec` parameter.
 By default it is set to `PT1H` (one hour).
@@ -124,6 +124,100 @@ Here are default templates that you can reuse and/or modify:
 {% endblock %}
 ```
 
+### Customize login form
+
+You can use a custom template for example to display information about password expiration
+or to customize [other user management templates](#other-user-management-templates).
+
+If you need only to change a template, you can use the following configuration:
+
+```yaml
+ezpublish:
+    system:
+        my_siteaccess:
+            user:
+                login_template: '@ezdesign/Security/login.html.twig'
+```
+
+In case of more advanced template customization, you can use a subscriber,
+for example in `src/EventSubscriber/LoginFormViewSubscriber.php`:
+
+``` php hl_lines="23 35 40 42"
+<?php
+
+declare(strict_types=1);
+
+namespace App\EventSubscriber;
+
+use eZ\Publish\Core\MVC\Symfony\Event\PreContentViewEvent;
+use eZ\Publish\Core\MVC\Symfony\MVCEvents;
+use eZ\Publish\Core\MVC\Symfony\View\LoginFormView;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\Security\Core\Exception\CredentialsExpiredException;
+
+final class LoginFormViewSubscriber implements EventSubscriberInterface
+{
+    /**
+     * Returns an array of events this subscriber wants to listen to.
+     *
+     * @return string[]
+     */
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            MVCEvents::PRE_CONTENT_VIEW => 'onPreContentView',
+        ];
+    }
+    
+    public function onPreContentView(PreContentViewEvent $event): void
+    {
+        $view = $event->getContentView();
+        
+        if (!($view instanceof LoginFormView)) {
+            return ;
+        }
+        
+        $view->addParameters([
+            'foo' => 'foo',
+            'bar' => 'bar'
+        ]);
+        
+        if ($view->getLastAuthenticationException() instanceof CredentialsExpiredException) {
+            // View with instruction to unlock account
+            $view->setTemplateIdentifier('login/expired_credentials.html.twig');
+        }
+    }
+}
+```
+
+In the provided example, in line 23, the `PRE_CONTENT_VIEW` event is used
+(for details, see [eZ Publish Core events](content_rendering.md#ez-publish-core)).
+You can also pass additional parameters to the view (line 35).
+In this case, at the instance of exception (line 40), the subscriber displays the `expired_credentials.html.twig` template (line 42).
+
+Remember to provide a template and point to it in the subscriber
+(in this case, in `templates/login/expired_credentials.html.twig`):
+
+```html+twig
+{% extends '@ezdesign/Security/base.html.twig' %}
+
+{%- block content -%}
+    <h2 class="ez-login__header">
+        {{ 'authentication.credentials_expired'|trans|desc('Your password has expired') }}
+    </h2>
+    <p>
+        {{ 'authentication.credentials_expired.message'|trans|desc(
+            'For security reasons, your password has expired and needs to be changed. An email has been sent to you with instructions.'
+        ) }}
+    </p>
+    <p>
+        <a href="{{ path('ezplatform.user.forgot_password') }}" class="btn btn-primary ez-btn ez-btn--login">
+            {{ 'authentication.credentials_expired.reset_password'|trans|desc('Reset password') }}
+        </a>
+    </p>
+{%- endblock -%}
+```
+
 ### Other user management templates
 
 You can also modify the following form templates: