From eaaa9984e51ac3ebc67c4e16f96b7520a8a64ed2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Chris=20M=C3=BCller?= <typo3@krue.ml>
Date: Thu, 26 May 2022 12:43:00 +0200
Subject: [PATCH] [DOCS] Streamline felogin documentation
The patch provides the following changes:
- Use consistent header levels
- Format code examples with the correct language
- Use example.org as domain for example link
- Apply takeaways from https://forge.typo3.org/issues/85035#note-8
(chapter "login process")
Resolves: #97692
Related: #85035
Releases: main, 11.5
Change-Id: If6c7851c25210cf4e03fb07efeaf14973e667cb9
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/74746
Tested-by: core-ci <typo3@b13.com>
Tested-by: Andreas Fernandez <a.fernandez@scripting-base.de>
Tested-by: Nikita Hovratov <nikita.h@live.de>
Reviewed-by: Simon Schaufelberger <simonschaufi+typo3@gmail.com>
Reviewed-by: Andreas Fernandez <a.fernandez@scripting-base.de>
Reviewed-by: Nikita Hovratov <nikita.h@live.de>
---
.../felogin/Documentation/Events/Index.rst | 26 +++++++-----
.../felogin/Documentation/Examples/Index.rst | 33 ++++++++-------
.../Documentation/Introduction/Index.rst | 17 ++++----
.../Documentation/KnownProblems/Index.rst | 5 +--
.../LoginMechanism/Display/Index.rst | 5 +--
.../Documentation/LoginMechanism/Index.rst | 5 +--
.../LoginMechanism/LoginProcess/Index.rst | 11 +++--
.../LoginMechanism/RedirectModes/Index.rst | 40 ++++++++++---------
.../Documentation/UsersManual/Index.rst | 17 ++++----
9 files changed, 82 insertions(+), 77 deletions(-)
diff --git a/typo3/sysext/felogin/Documentation/Events/Index.rst b/typo3/sysext/felogin/Documentation/Events/Index.rst
index ef8a11e2358c..0a5618926e17 100644
--- a/typo3/sysext/felogin/Documentation/Events/Index.rst
+++ b/typo3/sysext/felogin/Documentation/Events/Index.rst
@@ -1,45 +1,51 @@
.. include:: /Includes.rst.txt
-
-
.. _psr14events:
+=============
PSR-14 Events
--------------
+=============
The following PSR-14 Events are available to extend the extension:
BeforeRedirectEvent
-^^^^^^^^^^^^^^^^^^^
+===================
+
Notification before a redirect is made.
LoginConfirmedEvent
-^^^^^^^^^^^^^^^^^^^
+===================
+
A notification when a log in has successfully arrived at the plugin, via the
view and the controller, multiple information can be overridden in Event
Listeners.
LoginErrorOccurredEvent
-^^^^^^^^^^^^^^^^^^^^^^^
+=======================
+
A notification if something went wrong while trying to log in a user.
LogoutConfirmedEvent
-^^^^^^^^^^^^^^^^^^^^
+====================
+
A notification when a log out has successfully arrived at the plugin, via
the view and the controller, multiple information can be overridden in
Event Listeners.
ModifyLoginFormViewEvent
-^^^^^^^^^^^^^^^^^^^^^^^^
+========================
+
Allows to inject custom variables into the login form.
PasswordChangeEvent
-^^^^^^^^^^^^^^^^^^^
+===================
+
Event that contains information about the password which was set,
and is about to be stored in the database. Allows to mark the password
as invalid.
SendRecoveryEmailEvent
-^^^^^^^^^^^^^^^^^^^^^^
+======================
+
Event that contains the email to be sent to the user when they request a
new password.
diff --git a/typo3/sysext/felogin/Documentation/Examples/Index.rst b/typo3/sysext/felogin/Documentation/Examples/Index.rst
index 0fd6c9d44d07..c5787e1c629e 100644
--- a/typo3/sysext/felogin/Documentation/Examples/Index.rst
+++ b/typo3/sysext/felogin/Documentation/Examples/Index.rst
@@ -1,11 +1,10 @@
.. include:: /Includes.rst.txt
-
-
.. _examples:
+========
Examples
---------
+========
In this section some common situations are described.
@@ -13,28 +12,28 @@ In this section some common situations are described.
.. _login-and-back-to-original-page:
Send visitors to login page and redirect to original page
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+=========================================================
A common situation is that visitors who go to a page with access
restrictions should go to a login page first and after logging in
should be send back to the page they originally requested.
-Assume we have a login page with id 2.
+Assume we have a login page with id `2`.
Using TypoScript we can still display links to access restricted pages
and send visitors to the login page:
-::
+.. code-block:: typoscript
config {
- typolinkLinkAccessRestrictedPages = 2
- typolinkLinkAccessRestrictedPages_addParams = &return_url=###RETURN_URL###
+ typolinkLinkAccessRestrictedPages = 2
+ typolinkLinkAccessRestrictedPages_addParams = &return_url=###RETURN_URL###
}
On the login page the login form must be configured to redirect to the
original page:
-::
+.. code-block:: typoscript
plugin.tx_felogin_login.settings.redirectMode = referer
@@ -50,30 +49,30 @@ the felogin plugin, but requires a custom page-not-found handler.
.. _login-link-visibility:
Login link visible when not logged in and logout link visible when logged in
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+============================================================================
Again TypoScript will help you out. The page with the login form has
id=2:
-::
+.. code-block:: typoscript
10 = TEXT
10 {
- value = Login
- typolink.parameter = 2
+ value = Login
+ typolink.parameter = 2
}
[loginUser = *]
- 10.value = Logout
- 10.typolink.additionalParams = &logintype=logout
+ 10.value = Logout
+ 10.typolink.additionalParams = &logintype=logout
[end]
-Of course there can be solutions with HMENU items, etc.
+Of course there can be solutions with :typoscript:`HMENU` items, etc.
.. _access-restrictions:
Access restrictions on the felogin plugin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+=========================================
A very common issue is that the felogin plugin is set to Access: Hide
at login. After the core has processed the login request the page will
diff --git a/typo3/sysext/felogin/Documentation/Introduction/Index.rst b/typo3/sysext/felogin/Documentation/Introduction/Index.rst
index d91e8ee4a4b2..7708346422c3 100644
--- a/typo3/sysext/felogin/Documentation/Introduction/Index.rst
+++ b/typo3/sysext/felogin/Documentation/Introduction/Index.rst
@@ -1,17 +1,15 @@
.. include:: /Includes.rst.txt
-
-
.. _introduction:
+============
Introduction
-------------
-
+============
.. _what-does-it-do:
What does it do?
-^^^^^^^^^^^^^^^^
+================
The Frontend Login for Website Users (felogin) extension is a general
purpose extension for frontend logins. In addition to the actual login
@@ -21,13 +19,12 @@ and includes forgot password functionality.
.. _screenshots:
Screenshots
-^^^^^^^^^^^
-
+===========
.. _general-settings:
General Settings
-""""""""""""""""
+----------------
.. figure:: ../Images/GeneralSettings.png
:alt: General Settings
@@ -38,7 +35,7 @@ General Settings
.. _redirect-configuration:
Redirect Configuration
-""""""""""""""""""""""
+----------------------
.. figure:: ../Images/RedirectConfiguration.png
:alt: Redirect Configuration
@@ -49,7 +46,7 @@ Redirect Configuration
.. _messages-tab:
Messages Tab
-""""""""""""
+------------
.. figure:: ../Images/MessagesConfiguration.png
:alt: Messages Configuration
diff --git a/typo3/sysext/felogin/Documentation/KnownProblems/Index.rst b/typo3/sysext/felogin/Documentation/KnownProblems/Index.rst
index ce0da51967b1..9c73bc97e51b 100644
--- a/typo3/sysext/felogin/Documentation/KnownProblems/Index.rst
+++ b/typo3/sysext/felogin/Documentation/KnownProblems/Index.rst
@@ -1,11 +1,10 @@
.. include:: /Includes.rst.txt
-
-
.. _known-problems:
+==============
Known Problems
---------------
+==============
- If there is more than one felogin plugin on a page the password
recovery option can cause problems. This is a general problem with
diff --git a/typo3/sysext/felogin/Documentation/LoginMechanism/Display/Index.rst b/typo3/sysext/felogin/Documentation/LoginMechanism/Display/Index.rst
index 5dbbf945440a..b68440cf863e 100644
--- a/typo3/sysext/felogin/Documentation/LoginMechanism/Display/Index.rst
+++ b/typo3/sysext/felogin/Documentation/LoginMechanism/Display/Index.rst
@@ -1,11 +1,10 @@
.. include:: /Includes.rst.txt
-
-
.. _display:
+==================
What is displayed?
-^^^^^^^^^^^^^^^^^^
+==================
If there is no frontend user logged in, the login form will be
shown.
diff --git a/typo3/sysext/felogin/Documentation/LoginMechanism/Index.rst b/typo3/sysext/felogin/Documentation/LoginMechanism/Index.rst
index ea57c9549ae4..9fc5b13be657 100644
--- a/typo3/sysext/felogin/Documentation/LoginMechanism/Index.rst
+++ b/typo3/sysext/felogin/Documentation/LoginMechanism/Index.rst
@@ -1,11 +1,10 @@
.. include:: /Includes.rst.txt
-
-
.. _login-mechanism:
+===============
Login mechanism
----------------
+===============
In order to properly use the felogin plugin and its advanced
capabilities (such as redirect options) it is important to understand
diff --git a/typo3/sysext/felogin/Documentation/LoginMechanism/LoginProcess/Index.rst b/typo3/sysext/felogin/Documentation/LoginMechanism/LoginProcess/Index.rst
index e284b230ed97..355b9d027bb9 100644
--- a/typo3/sysext/felogin/Documentation/LoginMechanism/LoginProcess/Index.rst
+++ b/typo3/sysext/felogin/Documentation/LoginMechanism/LoginProcess/Index.rst
@@ -1,11 +1,10 @@
.. include:: /Includes.rst.txt
-
-
.. _login-process:
+=================
The login process
-^^^^^^^^^^^^^^^^^
+=================
After the form is submitted the TYPO3 CMS authentication services will
validate the login credentials. After this process felogin will handle
@@ -15,3 +14,9 @@ user who has logged in.
Felogin will then check any redirect options and generate the
appropriate content.
+.. caution::
+
+ - Do not use the login status of a frontend user as authorization,
+ but **always** rely on user groups.
+ - Only use different storage folders for frontend users if this is really
+ necessary due to organizational reasons.
diff --git a/typo3/sysext/felogin/Documentation/LoginMechanism/RedirectModes/Index.rst b/typo3/sysext/felogin/Documentation/LoginMechanism/RedirectModes/Index.rst
index eddeac3faab9..7aab4b48c52b 100644
--- a/typo3/sysext/felogin/Documentation/LoginMechanism/RedirectModes/Index.rst
+++ b/typo3/sysext/felogin/Documentation/LoginMechanism/RedirectModes/Index.rst
@@ -1,10 +1,10 @@
.. include:: /Includes.rst.txt
-
.. _redirect-modes:
+==============
Redirect Modes
-^^^^^^^^^^^^^^
+==============
The following redirect options are supported.
@@ -12,7 +12,7 @@ The following redirect options are supported.
.. _defined-by-usergroup-record:
Defined by Usergroup Record
-"""""""""""""""""""""""""""
+===========================
Within a Website usergroup record, you can specify a page where
usergroup members will be redirected after login.
@@ -21,7 +21,7 @@ usergroup members will be redirected after login.
.. _defined-by-user-record:
Defined by User Record
-""""""""""""""""""""""
+======================
This is identical to the redirection option for "defined by Usergroup
Record" but applies to a single website user instead of an entire user
@@ -31,17 +31,17 @@ group.
.. _after-login-ts-or-flexform:
After Login (TS or Flexform)
-""""""""""""""""""""""""""""
+============================
This redirect page is set either in TypoScript
-(:code:`plugin.tx_felogin_login.settings.redirectPageLogin`) or in the
+(:typoscript:`plugin.tx_felogin_login.settings.redirectPageLogin`) or in the
FlexForm of the felogin plugin.
.. _after-logout-ts-or-flexform:
After Logout (TS or Flexform)
-"""""""""""""""""""""""""""""
+=============================
Defines the redirect page after a user has logged out. Again, it can
be set in TypoScript or in the felogin plugin's FlexForm.
@@ -50,7 +50,7 @@ be set in TypoScript or in the felogin plugin's FlexForm.
.. _after-login-error-ts-of-flexform:
After Login Error (TS of Flexform)
-""""""""""""""""""""""""""""""""""
+==================================
Defines the redirect page after a login error occurs. Can be set in
TypoScript or in the felogin plugin's FlexForm.
@@ -58,23 +58,25 @@ TypoScript or in the felogin plugin's FlexForm.
.. _defined-by-get-post-vars:
-defined by GET/POST Parameters
-""""""""""""""""""""""""""""""
+Defined by GET/POST Parameters
+==============================
Redirect the visitor based on the GET/POST parameters :code:`redirect_url`.
If the TypoScript configuration
-:code:`config.typolinkLinkAccessRestrictedPages` is set, the GET/POST
+:typoscript:`config.typolinkLinkAccessRestrictedPages` is set, the GET/POST
parameter :code:`redirect_url` is used.
-Example url::
+Example url:
+
+.. code-block:: text
- http://www.domain.ext/index.php?id=12&redirect\_url=http%3A%2F%2Fwww%2Edomain%2Eext%2Fdestiny%2F
+ https://example.org/index.php?id=12&redirect_url=https%3A%2F%2Fexample%2Eorg%2Fdestiny%2F
.. _defined-by-referrer:
Defined by Referrer
-"""""""""""""""""""
+===================
The referrer page is used for the redirect. This basically means that
the user is sent back to the page he originally came from.
@@ -83,13 +85,13 @@ the user is sent back to the page he originally came from.
.. _defined-by-domain-entries:
Defined by Domain entries
-"""""""""""""""""""""""""
+=========================
-Same as 'defined by Referrer', except that only the domains listed in
-:code:`plugin.tx_felogin_login.domains` are allowed. If someone is sent to the
+Same as :guilabel:`Defined by Referrer`, except that only the domains listed in
+:typoscript:`plugin.tx_felogin_login.domains` are allowed. If someone is sent to the
login page coming from a domain which is not listed, the redirect will
not happen.
-By using the option "Use the first method found" you can define
-several fallback methods.
+By using the option :guilabel:`Use First Supported Mode from Selection` you can
+define several fallback methods.
diff --git a/typo3/sysext/felogin/Documentation/UsersManual/Index.rst b/typo3/sysext/felogin/Documentation/UsersManual/Index.rst
index 06a7c4c8e605..ae19fd2ed68e 100644
--- a/typo3/sysext/felogin/Documentation/UsersManual/Index.rst
+++ b/typo3/sysext/felogin/Documentation/UsersManual/Index.rst
@@ -1,11 +1,10 @@
.. include:: /Includes.rst.txt
-
-
.. _users-manual:
+============
Users manual
-------------
+============
The felogin extension requires no special configuration. All options
are available in the plugin's FlexForm as shown in the :ref:`screenshots`.
@@ -14,9 +13,9 @@ are available in the plugin's FlexForm as shown in the :ref:`screenshots`.
.. _using-plugin:
Using the plugin
-^^^^^^^^^^^^^^^^
+================
-The felogin plugin is available through the Content Wizard as "Login Form":
+The felogin plugin is available through the Content Wizard as :guilabel:`Login Form`:
.. figure:: ../Images/ContentElementWizard.png
@@ -28,19 +27,19 @@ The felogin plugin is available through the Content Wizard as "Login Form":
.. _storage-folder:
Choosing a User Storage Page for Website Users
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+==============================================
In order for Website Users to be able to log in, the felogin plugin
must know where the records are stored. There are two possibilities
for setting this storage folder:
-- Edit the felogin plugin, setting the field for the "User Storage
- Page" to your storage page.
+- Edit the felogin plugin, setting the field for the :guilabel:`User Storage
+ Page` to your storage page.
- Or set the UID of you storage folder through TypoScript in the setup
field of your TypoScript Template:
-::
+.. code-block:: typoscript
plugin.tx_felogin_login.settings.pages = xxx
--
GitLab