From 3ce4d85ae4b86896fffe8a27a7baea07e0606d61 Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 12 Jul 2022 17:21:57 +0200 Subject: [PATCH] [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 --- Documentation/ApiOverview/Fluid/Syntax.rst | 93 +++++++++++++++++++++- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/Documentation/ApiOverview/Fluid/Syntax.rst b/Documentation/ApiOverview/Fluid/Syntax.rst index 4bed404f76..c9abfa9204 100644 --- 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 ` 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 + + +
  • {result.title}
    • +     + +The "f" namespace is already defined, but can be explicitly specified to +improve IDE autocompletion. + +Fluid example with custom ViewHelper "custom" in namespace "my": + +.. code-block:: html + :caption: EXT:blog_example/Resources/Private/Templates/SomeTemplate.html + + + +Here, we are using a custom ViewHelper within the namespace my. 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 element with xmlns + + .. code-block:: html + :caption: EXT:blog_example/Resources/Private/Templates/SomeTemplate.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 for registering namespaces. This is already done for + `typo3/cms-fluid` and `typo3fluid/fluid` ViewHelpers. Therefore they are always + available via the `f` namespace. + + Custom ViewHelpers, e.g. 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: