[TASK] Add missing documentation for typolink.language 42/58142/4
authorBenni Mack <benni@typo3.org>
Mon, 3 Sep 2018 15:19:41 +0000 (17:19 +0200)
committerAnja Leichsenring <aleichsenring@ab-softlab.de>
Mon, 3 Sep 2018 16:04:48 +0000 (18:04 +0200)
The newly added functionality for typolink.language
within TypoScript receives a documentation file.

Resolves: #86057
Releases: master
Change-Id: I87031125f879950f926e118bf4b4bcc5a068f39f
Reviewed-on: https://review.typo3.org/58142
Reviewed-by: Christian Kuhn <lolli@schwarzbu.ch>
Tested-by: Christian Kuhn <lolli@schwarzbu.ch>
Tested-by: TYPO3com <no-reply@typo3.com>
Reviewed-by: Anja Leichsenring <aleichsenring@ab-softlab.de>
Tested-by: Anja Leichsenring <aleichsenring@ab-softlab.de>
typo3/sysext/core/Documentation/Changelog/master/Feature-86057-ImprovedTypolinkURLLinkGeneration.rst [new file with mode: 0644]

diff --git a/typo3/sysext/core/Documentation/Changelog/master/Feature-86057-ImprovedTypolinkURLLinkGeneration.rst b/typo3/sysext/core/Documentation/Changelog/master/Feature-86057-ImprovedTypolinkURLLinkGeneration.rst
new file mode 100644 (file)
index 0000000..9d71f1e
--- /dev/null
@@ -0,0 +1,61 @@
+.. include:: ../../Includes.txt
+
+=========================================================
+Feature: #86057 - Improved typolink / URL link generation
+=========================================================
+
+See :issue:`86057`
+
+Description
+===========
+
+With new site-based handling, the de-facto standard GET parameter "L" (for language) became
+superfluous.
+
+However, in order to create a link to a specific language via TypoScript's `typolink` functionality,
+a new parameter `typolink.language` is introduced.
+
+.. code-block:: typoscript
+
+       page.10 = TEXT
+       page.10.value = Link to the page with the ID in the current language
+       page.10.typolink.parameter = 23
+       page.20 = TEXT
+       page.20.value = Link to the page with the ID in the language 3
+       page.20.typolink.parameter = 23
+       page.20.typolink.language = 3
+
+Omitting the parameter `language` will use the current. If a page is not available in the requested
+language, the link will not be generated, however a fallback to the default language can be built,
+as the HMENU TypoScript functionality does.
+
+Due to the new page-linking functionality, the following TypoScript settings are not necessary anymore
+and should be removed for TypoScript configurations on pagetrees with a site configuration:
+
+* Including the "L" parameter in :typoscript:`config.linkVars`, as the L parameter is not evaluated for
+  page requests with a site configuration.
+* :typoscript:`config.absRefPrefix` is only necessary for links to files or images, but not for
+  page links, as they are always built against the absolute path, or - if `typolink.forceAbsoluteUrl`
+  is explicitly set.
+  The option is set to `auto` by default for site configuration TypoScripts, so this is not necessary
+  anymore in regular installations.
+* One of the major strengths allows to link across sites / domains with specifically knowing
+  all available languages of a different pagetree. Using the `config.typolinkEnableLinksAcrossDomains`
+  is not necessary anymore for TypoScript within a site configuration.
+
+
+Impact
+======
+
+When using :typoscript:`typolink.additionalParams = &L=1`, this is automatically mapped to
+the :typoscript:`typolink.language` parameter, but if both are set, the `typolink.language` option
+takes precedence.
+
+When generating links with `&L=` query parameters, this parameter is stripped, and the correct base
+URL for the site is fetched, but the query parameter is not added anymore.
+
+Setting the target page ID via :typoscript:`typolink.parameter` it is also possible to set the
+page ID to a localized page ID, automatically resolving to the correct language if neither
+:typoscript:`typolink.parameter` nor :typoscript:`typolink.additionalParams = L=` is set.
+
+.. index:: TypoScript, ext:frontend
\ No newline at end of file