[DOC] Document xmlns-carrying node behavior in Fluid 45/50245/5
authorClaus Due <claus@namelesscoder.net>
Mon, 17 Oct 2016 13:31:16 +0000 (15:31 +0200)
committerSusanne Moog <susanne.moog@typo3.org>
Mon, 17 Oct 2016 15:58:54 +0000 (17:58 +0200)
This change documents the fact that xmlns-based
namespace importing works slightly different since Fluid
standalone became the base. Migration docs included.

Change-Id: I58f7a7e09eb0b640514cc3bf885d6ed05ea988e4
Resolves: #76155
Releases: master
Reviewed-on: https://review.typo3.org/50245
Tested-by: TYPO3com <no-reply@typo3.com>
Reviewed-by: Benni Mack <benni@typo3.org>
Tested-by: Benni Mack <benni@typo3.org>
Reviewed-by: Susanne Moog <susanne.moog@typo3.org>
Tested-by: Susanne Moog <susanne.moog@typo3.org>
typo3/sysext/core/Documentation/Changelog/8.0/Breaking-76155-ViewHelperNamespaceImportsWithXmlnsAreNowSingular.rst [new file with mode: 0644]

diff --git a/typo3/sysext/core/Documentation/Changelog/8.0/Breaking-76155-ViewHelperNamespaceImportsWithXmlnsAreNowSingular.rst b/typo3/sysext/core/Documentation/Changelog/8.0/Breaking-76155-ViewHelperNamespaceImportsWithXmlnsAreNowSingular.rst
new file mode 100644 (file)
index 0000000..efa9d00
--- /dev/null
@@ -0,0 +1,62 @@
+
+.. include:: ../../Includes.txt
+
+=============================================================================
+Breaking: #76155 - ViewHelper Namespace imports with `xmlns` are now singular
+=============================================================================
+
+See :issue:`76155`
+
+Description
+===========
+
+Fluid templates which use **multiple** ยด<div xmlns:xyz="...">` in one template file are affected. Only the first
+such node is now detected and respected. The reasons for this new limitation are the reworked internals of Fluid since
+the standalone version.
+
+Before, namespace nodes were handled internally by the TemplateParser. They worked in a way that the namespace
+dictated by the node would **only apply inside that node**.
+
+After, namespace nodes are handled by template pre-processing and handed off to the ViewHelperResolver without going
+through the TemplateParser first. Since it happens in pre-processing, namespaces dictated by such nodes now **apply
+across the entire template file**.
+
+This has two effects on template parsing:
+
+1. Extraction of `xmlns:xyz` style imports happens **once** and detects only a single node.
+2. Nesting no longer matters; a namespace imported with this method will apply to the entire template file since it
+   is extracted during pre-processing and is not recursive.
+
+Most templates will not be affected by this since the norm is already to include a single such namespace import and
+put it as the outermost surrounding tag, then add all imported namespaces on that single node. This usage is still
+fully supported.
+
+
+Impact
+======
+
+The change affects template files which fulfill one or both of the following conditions:
+
+1. Any template file which contains multiple nodes with `xmlns:xyz` imports will see only the first node detected.
+2. Any template file which assumes an imported namespace is removed when the enclosing tag is closed and uses a
+   previously imported namespace after the closing node will likely see errors with `ViewHelper could not be resolved`
+   since Fluid will attempt to translate matching XHTML nodes with namespace prefixes to ViewHelper classes.
+
+
+Affected Installations
+======================
+
+TYPO3 8.0 and above, any site matching conditions stated in `Impact`.
+
+
+Migration
+=========
+
+There is one migration for each of the conditions above:
+
+1. Templates with multiple `xmlns:xyz` nodes can be migrated by combining all those nodes into one.
+2. Templates which assume a closing container tag removes the namespace will have to migrate by extracting the XHTML
+   that collides with the Fluid namespace and placing it in a separate template file (e.g. Partial template).
+
+
+.. index:: Fluid