[TASK] Add ViewHelpers to Fluid syntax (#1947)

* [TASK] Add ViewHelpers to Fluid syntax Part of the text has been reused from the Extbase book. In subsequent patches, more content will be migrated from the Extbase book to TYPO3 Explained. Related: TYPO3-Documentation/TYPO3CMS-Book-ExtbaseFluid#536 * Use namespace consistently Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> * Use namespace consistently Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> * Improve phrase Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> * Reduce use of abbreviations Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> * Improve formatting Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com>
TYPO3-Documentation · Jul 12, 2022 · cde49d9 · cde49d9
1 parent c216a8a
commit cde49d9
Showing 1 changed file with 90 additions and 3 deletions.
diff --git a/Documentation/ApiOverview/Fluid/Syntax.rst b/Documentation/ApiOverview/Fluid/Syntax.rst
@@ -71,14 +71,101 @@ It is possible to access array or object values by a dynamic index:
 
    myArray.{myIndex}
 
-ViewHelper attributes
-=====================
+.. _fluid-syntax-viewhelpers:
+
+ViewHelpers
+===========
+
+ViewHelpers are special tags in the template which provide more complex
+functionality such as loops or generating links.
+
+The functionality of the ViewHelper is implemented in PHP, every ViewHelper has
+its own PHP class.
 
 See the :doc:`Fluid Viewhelper Reference <t3viewhelper:Index>` for a complete
 list of all available ViewHelpers.
 
+Within Fluid, the ViewHelper is used as a special HTML element with a namespace
+prefix, for example the namespace prefix "f" is used for ViewHelpers from the
+Fluid namespace:
+
+.. code-block:: html
+   :caption: Fluid example with for ViewHelper
+
+   <f:for each="{results}" as="result">
+      <li>{result.title}</li>
+   </f:for>
+
+The "f" namespace is already defined, but can be explicitly specified to
+improve IDE autocompletion.
+
+Fluid example with custom ViewHelper "custom" in namespace "blog":
+
+.. code-block:: html
+   :caption: EXT:blog_example/Resources/Private/Templates/SomeTemplate.html
+
+   <blog:custom argument1="something"/>
+
+Here, we are using a custom ViewHelper within the namespace "blog". The namespace
+must be registered explicitly, see the next section.
+
+.. _fluid-syntax-viewhelpers-import-namespaces:
+
+Import ViewHelper namespaces
+----------------------------
+
+There are 3 ways to import ViewHelper namespaces in TYPO3. In all three examples
+`blog` is the namespace available within the Fluid template and
+`MyVendor\BlogExample\ViewHelpers` is the PHP namespace to import into Fluid.
+
+1. Use an :html:`<html>` tag with xmlns
+
+   .. code-block:: html
+      :caption: EXT:blog_example/Resources/Private/Templates/SomeTemplate.html
+
+      <html
+       xmlns:blog="http://typo3.org/ns/Myvendr/MyExtension/ViewHelpers"
+       data-namespace-typo3-fluid="true">
+
+      </html>
+
+   If the attribute :html:`data-namespace-typo3-fluid="true"` is specified on the
+   :html:`html` element, the HTML element itself won’t be rendered. This is useful
+   for various IDEs and HTML auto-completion.
+
+2. Local namespace import via curly braces {}-syntax
+
+   .. code-block:: html
+      :caption: EXT:blog_example/Resources/Private/Templates/SomeTemplate.html
+
+      {namespace blog=MyVendor\BlogExample\ViewHelpers}
+
+   Each of the rows will result in a blank line. Multiple import statements can go
+   into a single or multiple lines.
+
+3. Global namespace import
+
+   Fluid allows to register global namespaces. This is already done for
+   `typo3/cms-fluid` and `typo3fluid/fluid` ViewHelpers. Therefore they are always
+   available via the `f` namespace.
+
+   Custom ViewHelpers, for example for a site package, can be registered the same way.
+   Namespaces are registered within
+   :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']`, for example:
+
+   .. code-block:: php
+      :caption: EXT:blog_example/ext_localconf.php
+
+       $GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['blog'] = [
+           'MyVendor\BlogExample\ViewHelpers',
+       ];
+
+
+Viewhelper attributes
+---------------------
+
 Simple
-------
+~~~~~~
 
 Variables can be inserted into ViewHelper attributes by putting them in
 curly braces: