Commit eaaa9984 authored by Chris Müller's avatar Chris Müller Committed by Nikita Hovratov
Browse files

[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's avatarcore-ci <typo3@b13.com>
Tested-by: Andreas Fernandez's avatarAndreas Fernandez <a.fernandez@scripting-base.de>
Tested-by: Nikita Hovratov's avatarNikita Hovratov <nikita.h@live.de>
Reviewed-by: Simon Schaufelberger's avatarSimon Schaufelberger <simonschaufi+typo3@gmail.com>
Reviewed-by: Andreas Fernandez's avatarAndreas Fernandez <a.fernandez@scripting-base.de>
Reviewed-by: Nikita Hovratov's avatarNikita Hovratov <nikita.h@live.de>
parent 08ca9785
Pipeline #27506 passed with stages
in 19 minutes and 2 seconds
.. 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.
.. 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
......
.. 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
......
.. 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
......
.. include:: /Includes.rst.txt
.. _display:
==================
What is displayed?
^^^^^^^^^^^^^^^^^^
==================
If there is no frontend user logged in, the login form will be
shown.
......
.. 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
......
.. 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.
.. 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.
.. 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
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment