From e57284f72ee97df7db4638d1437f52c68e7d4464 Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 12 Jul 2022 17:21:57 +0200 Subject: [PATCH 1/6] [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 836952f318..a159e483ec 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: From 7349c2a9e2b9367cfb1d9d8cc5dc29fc0bbd8924 Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 12 Jul 2022 20:06:31 +0200 Subject: [PATCH 2/6] Use namespace consistently Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> --- Documentation/ApiOverview/Fluid/Syntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ApiOverview/Fluid/Syntax.rst b/Documentation/ApiOverview/Fluid/Syntax.rst index a159e483ec..ba1b900c8a 100644 --- a/Documentation/ApiOverview/Fluid/Syntax.rst +++ b/Documentation/ApiOverview/Fluid/Syntax.rst @@ -99,7 +99,7 @@ Fluid namespace: The "f" namespace is already defined, but can be explicitly specified to improve IDE autocompletion. -Fluid example with custom ViewHelper "custom" in namespace "my": +Fluid example with custom ViewHelper "custom" in namespace "blog": .. code-block:: html :caption: EXT:blog_example/Resources/Private/Templates/SomeTemplate.html From cee2b5808a961b0907d636b00e03515b6b3f9326 Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 12 Jul 2022 20:06:40 +0200 Subject: [PATCH 3/6] Use namespace consistently Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> --- Documentation/ApiOverview/Fluid/Syntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ApiOverview/Fluid/Syntax.rst b/Documentation/ApiOverview/Fluid/Syntax.rst index ba1b900c8a..75142dcbce 100644 --- a/Documentation/ApiOverview/Fluid/Syntax.rst +++ b/Documentation/ApiOverview/Fluid/Syntax.rst @@ -106,7 +106,7 @@ Fluid example with custom ViewHelper "custom" in namespace "blog": -Here, we are using a custom ViewHelper within the namespace my. The namespace +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: From 29c83ccbe0dbb938e27a2d4ff5c69e70ff66973e Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 12 Jul 2022 20:07:22 +0200 Subject: [PATCH 4/6] Improve phrase Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> --- Documentation/ApiOverview/Fluid/Syntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ApiOverview/Fluid/Syntax.rst b/Documentation/ApiOverview/Fluid/Syntax.rst index 75142dcbce..7c3e3b5bdb 100644 --- a/Documentation/ApiOverview/Fluid/Syntax.rst +++ b/Documentation/ApiOverview/Fluid/Syntax.rst @@ -145,7 +145,7 @@ There are 3 ways to import ViewHelper namespaces in TYPO3. In all three examples 3. Global namespace import - Fluid allows for registering namespaces. This is already done for + 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. From 4280eec874bd08de48910ab3591147c7004b4ce3 Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 12 Jul 2022 20:07:46 +0200 Subject: [PATCH 5/6] Reduce use of abbreviations Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> --- Documentation/ApiOverview/Fluid/Syntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ApiOverview/Fluid/Syntax.rst b/Documentation/ApiOverview/Fluid/Syntax.rst index 7c3e3b5bdb..fa78a01885 100644 --- a/Documentation/ApiOverview/Fluid/Syntax.rst +++ b/Documentation/ApiOverview/Fluid/Syntax.rst @@ -149,7 +149,7 @@ There are 3 ways to import ViewHelper namespaces in TYPO3. In all three examples `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. + 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: From 8a2ce924f276de2173dab1bafef119dd9e727981 Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 12 Jul 2022 20:28:33 +0200 Subject: [PATCH 6/6] Improve formatting Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> --- Documentation/ApiOverview/Fluid/Syntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ApiOverview/Fluid/Syntax.rst b/Documentation/ApiOverview/Fluid/Syntax.rst index fa78a01885..447a468b5f 100644 --- a/Documentation/ApiOverview/Fluid/Syntax.rst +++ b/Documentation/ApiOverview/Fluid/Syntax.rst @@ -118,7 +118,7 @@ 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 +1. Use an :html:`` tag with xmlns .. code-block:: html :caption: EXT:blog_example/Resources/Private/Templates/SomeTemplate.html