TYPO3 v15 dev-main snapshot ()
This commit is contained in:
@@ -0,0 +1,372 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _usage:
|
||||
|
||||
=====
|
||||
Usage
|
||||
=====
|
||||
|
||||
.. _usage-redirects-module:
|
||||
|
||||
Redirects module
|
||||
================
|
||||
|
||||
Access the redirects module in the TYPO3 backend under :guilabel:`Sites > Redirects`.
|
||||
|
||||
.. figure:: ../Images/RedirectsMenu.png
|
||||
:class: with-shadow
|
||||
|
||||
Open Redirects module
|
||||
|
||||
.. _usage-redirects-module-list:
|
||||
|
||||
List
|
||||
----
|
||||
|
||||
.. figure:: ../Images/RedirectList.png
|
||||
:class: with-shadow
|
||||
|
||||
Redirect list
|
||||
|
||||
You will see a list of the existing redirects with the following columns labels.
|
||||
|
||||
#. **Source Domain**
|
||||
#. **Source Path**
|
||||
#. **Target**
|
||||
#. **Count**: Number of "hits" (only if hit counter is on)
|
||||
#. **Last Hit on**: When was the most recent redirect "hit" (only if hit
|
||||
counter is on)
|
||||
#. *Action buttons*: View page, edit, disable and delete |action_buttons_image|
|
||||
|
||||
.. tip::
|
||||
|
||||
Hover over the text to see the link markup (underline) and a tooltip.
|
||||
|
||||
It is also possible to **sort** by clicking on the :guilabel:`Source Host` or
|
||||
:guilabel:`Source Path` column headers and changing the sort order by clicking
|
||||
again, as also done elsewhere in the backend.
|
||||
|
||||
By clicking on the *Source Path* of one of the columns or on the pencil edit
|
||||
icon |edit_action_image|, you can **edit** the record. Clicking on a link in the
|
||||
*Destination* column, should open the link target.
|
||||
|
||||
The :guilabel:`+` sign on the top will open an edit form to create a **new
|
||||
redirect**.
|
||||
|
||||
It is also possible to **filter**, e.g. by the *Source Path*, *Status Code*,
|
||||
*Creation type*, *Protected* or only show redirect records which were "*Never hit*"
|
||||
(see Information on :ref:`Hit counter <hit-counter>` which must be explicitly
|
||||
enabled via Feature Toggle).
|
||||
|
||||
.. _usage-redirects-module-edit-form:
|
||||
|
||||
Edit form
|
||||
---------
|
||||
|
||||
When creating a new redirect or editing an existing one, the edit form will open.
|
||||
|
||||
A redirect generally consists of these 2 parts which are separated in the
|
||||
edit form:
|
||||
|
||||
#. A **source** part (host, path, query parameters) which is matched against
|
||||
the URL. If it matches, the redirect is applied
|
||||
#. A **target** part which defines where the redirect should redirect to and
|
||||
some additional parameters like the HTTP status code, whether to force HTTPS
|
||||
and keep query parameters
|
||||
|
||||
Also, the redirect has some additional parameters that are specific for the
|
||||
redirect record but not relevant when generating the redirect, such as the
|
||||
:guilabel:`Protected` field.
|
||||
|
||||
Admin users will see the respective database fields from the table
|
||||
:sql:`sys_redirect` in square brackets (e.g.
|
||||
:guilabel:`Source Domain [source_host]`) next to the label if in debug mode.
|
||||
|
||||
Non-admin users may not see all the fields. By default *Source Domain*, *Source Path*
|
||||
and *Target* are enabled, the rest are exclude fields and must be enabled in the
|
||||
backend group permissions, see
|
||||
:ref:`backend user configuration <editor-permission>`.
|
||||
|
||||
.. _usage-redirects-module-edit-form-general-tab:
|
||||
|
||||
General tab
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. figure:: ../Images/RedirectEdit.png
|
||||
:class: with-shadow
|
||||
|
||||
Edit redirect
|
||||
|
||||
----
|
||||
|
||||
**Source:**
|
||||
|
||||
.. confval:: Source Domain
|
||||
|
||||
:Field: source_host
|
||||
|
||||
It is possible to select one of the domains from the site configuration or
|
||||
use the wildcard (`*`). In this case the redirect applies to all sites!
|
||||
|
||||
.. confval:: Source Path
|
||||
|
||||
:Field: source_path
|
||||
|
||||
Can be an actual path, e.g. `/path`. For URLs with different entry points
|
||||
for languages, you should use the full path, e.g. `/en/path`.
|
||||
:ref:`Regular expressions <regex-examples>` are possible, but then
|
||||
`is_regexp` must be enabled. Regular expressions must be enclosed in
|
||||
delimiters, e.g. `#^/path/([a-zA-Z]{1}[a-zA-Z0-9_/-]+)#` or
|
||||
`/^\/path\/([a-zA-Z]{1}[a-zA-Z0-9_/-]+)/`.
|
||||
|
||||
.. confval:: Respect GET Parameters
|
||||
|
||||
:Field: respect_query_parameters
|
||||
|
||||
If on, matching is also performed on query parameters. If off, matching is
|
||||
only performed on the path.
|
||||
|
||||
.. confval:: Is regular expression?
|
||||
|
||||
:Field: is_regexp
|
||||
|
||||
Evaluate the Source Path as regular expression.
|
||||
|
||||
----
|
||||
|
||||
**Target:**
|
||||
|
||||
.. confval:: Target
|
||||
|
||||
:Field: target
|
||||
|
||||
The redirect target, can be a
|
||||
|
||||
- path, e.g. `/features`
|
||||
- URL, e.g. `https://example.org/features`
|
||||
- page ID or page URI, e.g. `t3://page?uid=1`
|
||||
- file URI, e.g. `t3://file?uid=1`
|
||||
- path with reference to
|
||||
:ref:`regular expression capturing group <regex-examples>` if the regular
|
||||
expression feature is used with e.g. capturing groups in Source Path, e.g.
|
||||
`/newpath/$1`
|
||||
|
||||
.. confval:: Status Code HTTP Header
|
||||
|
||||
:Field: target_statuscode
|
||||
|
||||
The :ref:`HTTP status code <http-status-codes>` that will be sent to the
|
||||
client. This is 307 (Temporary Redirect) by default.
|
||||
|
||||
.. confval:: Force SSL Redirect
|
||||
|
||||
:Field: force_https
|
||||
|
||||
When redirecting, use HTTPS when constructing the target URL. This will even
|
||||
be the case, if a full URL is given as target (e.g.
|
||||
`http://example.com/features`) or if the entry point of a site uses HTTP, so
|
||||
make sure your site supports HTTPS (which is recommended anyway).
|
||||
|
||||
.. confval:: Keep GET Parameters
|
||||
|
||||
:Field: keep_query_parameters
|
||||
|
||||
When redirecting, add query parameters of original URL (with possible
|
||||
changes) to the target. By default, the query parameters are omitted, so
|
||||
source URL `https://example.com/features?abc=1` would be redirected to
|
||||
`https://example.com/all-features`. If there are already query
|
||||
parameters in the target field, these are used instead.
|
||||
|
||||
.. confval:: Protected
|
||||
|
||||
:Field: protected
|
||||
|
||||
This does not affect the redirect itself. It protects the record from
|
||||
automatic deletion (e.g. with redirects:cleanup).
|
||||
|
||||
.. confval:: Creation Type
|
||||
|
||||
:Field: creation_type
|
||||
|
||||
This field allows to differentiate between redirects that are created
|
||||
automatically when the slug of a page is changed and those that are created
|
||||
in the backend module by editors.
|
||||
|
||||
.. confval:: Integrity Status
|
||||
|
||||
:Field: integrity_status
|
||||
|
||||
This field hints about a broken redirect, for example, if the page references
|
||||
to itself.
|
||||
|
||||
.. _usage-redirects-module-edit-form-statistic-tab:
|
||||
|
||||
Statistics tab
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. figure:: ../Images/RedirectsEditStatistics.png
|
||||
:class: shadow
|
||||
|
||||
Statistics tab with hit counter
|
||||
|
||||
This tab is only available, if the hit counter is enabled. Here you can disable
|
||||
the hit counter for a specific redirect and also see read-only statistics.
|
||||
|
||||
.. confval:: Hit Counter
|
||||
|
||||
:Field: disable_hitcount
|
||||
|
||||
Disable the hit counter only for this redirect.
|
||||
|
||||
.. confval:: Count
|
||||
|
||||
:Field: hitcount
|
||||
:Editable: read only
|
||||
|
||||
Number of hits for this particular redirect. (How often was the page
|
||||
accessed which triggered this redirect?)
|
||||
|
||||
.. confval:: Last Hit on
|
||||
|
||||
:Field: lasthiton
|
||||
:Editable: read only
|
||||
|
||||
When was the last hit on this redirect?
|
||||
|
||||
.. confval:: Created At
|
||||
|
||||
:Field: createdon
|
||||
:Editable: read only
|
||||
|
||||
When was this redirect created?
|
||||
|
||||
.. _usage-redirects-module-edit-form-access-tab:
|
||||
|
||||
Access tab
|
||||
~~~~~~~~~~
|
||||
|
||||
.. confval:: Enabled
|
||||
|
||||
:Field: disabled
|
||||
|
||||
If disabled, the redirect has no effect.
|
||||
|
||||
.. confval:: Start
|
||||
|
||||
:Field: starttime
|
||||
|
||||
If this is not empty, "now" (current time) must be after Start time for the
|
||||
redirect to have effect.
|
||||
|
||||
.. confval:: Stop
|
||||
|
||||
:Field: endtime
|
||||
|
||||
If this is not empty, "now" (current time) must be before Stop time for the
|
||||
redirect to have effect.
|
||||
|
||||
.. _usage-redirects-module-edit-form-notes-tab:
|
||||
|
||||
Notes
|
||||
~~~~~
|
||||
|
||||
.. confval:: Description
|
||||
|
||||
:Field: description
|
||||
|
||||
Add context to the corresponding redirect. The added information is also
|
||||
displayed in the "Record information" info box above the edit form.
|
||||
|
||||
|
||||
.. _regex-examples:
|
||||
|
||||
Regex examples
|
||||
--------------
|
||||
|
||||
.. _regex-examples-regex:
|
||||
|
||||
|
||||
Example 1: Source path with regular expression and capturing group
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
redirect
|
||||
|
||||
+-------------------------------------------------+-----------------------+----------------------------------------+
|
||||
| Source Path | Is Regular Expression | target |
|
||||
+-------------------------------------------------+-----------------------+----------------------------------------+
|
||||
| `#^/path/([a-zA-Z]{1}[a-zA-Z0-9_/-]+)#` | true | :samp:`https://example.org/newpath/$1` |
|
||||
+-------------------------------------------------+-----------------------+----------------------------------------+
|
||||
|
||||
with the following result:
|
||||
|
||||
+--------------------------------------------+-----------------------------------------------+
|
||||
| URL | result URL |
|
||||
+--------------------------------------------+-----------------------------------------------+
|
||||
| :samp:`https://example.org/path/something` | :samp:`https://example.org/newpath/something` |
|
||||
+--------------------------------------------+-----------------------------------------------+
|
||||
|
||||
.. _regex-examples-regex-relative:
|
||||
|
||||
Example 2: Source path with regular expression, capturing group and relative target
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
redirect
|
||||
|
||||
+-------------------------------------------------+-----------------------+---------------+
|
||||
| Source Path | Is Regular Expression | target |
|
||||
+-------------------------------------------------+-----------------------+---------------+
|
||||
| `#^/another/path/([a-zA-Z]{1}[a-zA-Z0-9_/-]+)#` | true | `/newpath/$1` |
|
||||
+-------------------------------------------------+-----------------------+---------------+
|
||||
|
||||
with the following result:
|
||||
|
||||
+----------------------------------------------------+--------------------------------------------------------+
|
||||
| URL | result URL |
|
||||
+----------------------------------------------------+--------------------------------------------------------+
|
||||
| :samp:`https://example.org/another/path/something` | :samp:`https://example.org/relative/newpath/something` |
|
||||
+----------------------------------------------------+--------------------------------------------------------+
|
||||
|
||||
Using a relative target is necessary if a redirect must work on multiple domains or multiple environments.
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
TYPO3 will not syntax check the redirect. Make sure you enter working
|
||||
redirects enclosed in delimiters. Use tools like https://regex101.com/,
|
||||
if necessary.
|
||||
|
||||
.. _automatic-redirect-creation:
|
||||
|
||||
Automatic redirects creation
|
||||
============================
|
||||
|
||||
Redirects are created automatically on slug changes, if EXT:redirects is
|
||||
installed and automatic creation is enabled in
|
||||
:ref:`site configuration <site-configuration>`.
|
||||
|
||||
A redirect from the old URL to the new URL will be created. All sub pages are
|
||||
checked too and the slugs will be updated and redirects will be created for
|
||||
these as well.
|
||||
|
||||
After the creation of the redirects a notification will be shown to the user.
|
||||
|
||||
.. figure:: ../Images/RedirectRevert.png
|
||||
:class: with-shadow
|
||||
|
||||
Revert redirect
|
||||
|
||||
The notification contains two possible actions:
|
||||
|
||||
- revert the complete slug update and remove the redirects
|
||||
- or only remove the redirects
|
||||
|
||||
.. note::
|
||||
|
||||
No redirects are generated for workspace versions in the TYPO3 backend.
|
||||
The setting `redirect.autoCreateRedirects` is internally disabled in this
|
||||
case.
|
||||
|
||||
|
||||
.. |edit_action_image| image:: ../Images/EditAction.png
|
||||
|
||||
.. |action_buttons_image| image:: ../Images/RedirectActionButtons.png
|
||||
Reference in New Issue
Block a user