[Backport 11.5] Migrate Fluid page "Using TypoScript for rendering: T…

…he cObject ViewHelper" from Extbase book (#1960) * Migrate towards reStructuredText format - initial commit git-svn-id: https://svn.typo3.org/TYPO3v4/Documentation/book_extbase_fluid/trunk@960 709f56b5-9817-0410-a4d7-c38de5d9e867 * Migrate towards reStructuredText format - markup clean up git-svn-id: https://svn.typo3.org/TYPO3v4/Documentation/book_extbase_fluid/trunk@961 709f56b5-9817-0410-a4d7-c38de5d9e867 * Fix some wrong indentation git-svn-id: https://svn.typo3.org/TYPO3v4/Documentation/book_extbase_fluid/trunk@982 709f56b5-9817-0410-a4d7-c38de5d9e867 * Update 5-using-typoscript-for-rendering-the-cobject-viewhelper.rst align code blocks properly * More reST coding stuff - Include Includes.txt at the beginning of each *.rst file - Shorten some punctuation lines of headlines. The rest needs to be done. - Add to the coding conventions in this manual * Update 5-using-typoscript-for-rendering-the-cobject-viewhelper.rst * Bulk replace tabs by spaces * fix typos * Improve grammar and readability (#378) * [TASK] Improve grammar and readability This is achieved by using grammarly.com on all texts * [TASK] Revert several changes and add missing newlines * change headings to sentence case, domain-driven design, See https://en.wikipedia.org/wiki/Domain-driven_design * Sentence case * Update 4-Property-mapping.rst * Sentence case * cases and sentence case * cases and sentence restructuring * case * Structural and case improvements improved the following: Headline order headlines to sentence case include missing imports Case issues * Remove all sphinx warnings * behavior (US English) * Update 1-Model-View-Controller-in-Extbase.rst * Update 8-Back-in-the-controller.rst * Update 6-adding-the-template.rst * Update 1-the-application-domain.rst * Update Index.rst * Update 2a-creating-the-repositories.rst * Update 1-Creating-Controllers-and-Actions.rst * Update 1-Creating-Controllers-and-Actions.rst * Update 8-developing-a-custom-viewhelper.rst * Update Index.rst * Write ViewHelper in CamelCase once again. Co-authored-by: Lina Wolf <[email protected]> * Rename includes.txt to includes.rst.txt (#381) * Introducing indexes (#384) * [WIP] indexing chapter 1-3 * [WIP] indexing chapter 4 * Indexing rest * remove sphinx warnings * Add captions to code-blocks (#94) (#525) * [TASK] Add captions to code-blocks (#94) to make it more clear where code should go Releases: main, 11.5 * Update 4-Property-mapping.rst * Update 6-adding-the-template.rst Co-authored-by: lina.wolf <[email protected]> Co-authored-by: Tom Warwick <[email protected]> * Add migrated Fluid file to index * Shorten title Long titles can be quite messy in the menu so we shorten the title. The first paragraph is chnaged accordingly. * Fix inline code Use correct text roles * Remove redundant text Remove last paragraph which contains a not about the following chapter which was left over from migration from the Extbase book but no longer applies. Co-authored-by: fab1en <fab1en@709f56b5-9817-0410-a4d7-c38de5d9e867> Co-authored-by: Simon Schaufelberger <[email protected]> Co-authored-by: Martin Bless <[email protected]> Co-authored-by: fischhase <[email protected]> Co-authored-by: Martin Bless <[email protected]> Co-authored-by: Ben Abbott <[email protected]> Co-authored-by: Alexander Schnitzler <[email protected]> Co-authored-by: Lina Wolf <[email protected]> Co-authored-by: lina.wolf <[email protected]> Co-authored-by: Tom Warwick <[email protected]> Co-authored-by: Sybille Peters <[email protected]>
TYPO3-Documentation · Jul 13, 2022 · 5f9ca5c · 5f9ca5c
1 parent e8f2bdc
commit 5f9ca5c
Show file tree

Hide file tree

Showing 2 changed files with 182 additions and 0 deletions.
diff --git a/Documentation/ApiOverview/Fluid/Index.rst b/Documentation/ApiOverview/Fluid/Index.rst
@@ -37,5 +37,6 @@ You can use Fluid in TYPO3 to do one of the following:
 
    Introduction
    Syntax
+   UsingTypoScriptCObjectViewHelper
    DevelopCustomViewhelper
    ViewHelper reference <https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/>
diff --git a/Documentation/ApiOverview/Fluid/UsingTypoScriptCObjectViewHelper.rst b/Documentation/ApiOverview/Fluid/UsingTypoScriptCObjectViewHelper.rst
@@ -0,0 +1,181 @@
+.. include:: /Includes.rst.txt
+.. index::
+   TypoScript ViewHelper
+   Fluid; f:cObject
+
+==================
+cObject ViewHelper
+==================
+
+The cObject ViewHelper combines Fluid with TypoScript.
+The following line in the HTML template will be replaced with the referenced
+TypoScript object.
+
+.. code-block:: html
+   :caption: EXT:my_extension/Resources/Private/Templates/SomeTemplate.html
+
+   <f:cObject typoscriptObjectPath="lib.title"/>
+
+Now we only have to define :typoscript:`lib.title` in the TypoScript
+Setup:
+
+.. code-block:: typoscript
+   :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript
+
+   lib.title = TEXT
+   lib.title.value = Extbase and Fluid
+
+»Extbase and Fluid« will be outputted in the template. Now we can output an
+image (e.g. headlines with unusual fonts) by changing the TypoScript to:
+
+.. code-block:: typoscript
+   :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript
+
+   lib.title = IMAGE
+   lib.title {
+      file = GIFBUILDER
+      file {
+         10 = TEXT
+         10.value = Extbase and Fluid
+      }
+   }
+
+.. sidebar:: TypoScript
+
+   TypoScript is a flexible configuration language, which can control
+   the rendering of a page in much detail. It consists of TypoScript objects
+   (also known as :typoscript:`Content` object or :typoscript:`cObject`) and
+   their configuration options.
+
+   The simplest :typoscript:`Content` object is :typoscript:`TEXT`
+   which outputs unmodified text. The TypoScript object :typoscript:`IMAGE`
+   can be used to generate images, and database entries can be outputted
+   with :typoscript:`CONTENT`.
+
+So far, it's not a "real world" example because no data is
+being passed from Fluid to the TypoScript. We'll demonstrate how to pass
+a parameter to the TypoScript with the example of a user counter. The value
+of our user counter should come from the Blog-Post. (Every Blog-Post should
+count how many times it's been viewed in this example).
+
+In the Fluid template we add:
+
+.. code-block:: html
+   :caption: EXT:my_extension/Resources/Private/Templates/SomeTemplate.html
+
+   <f:cObject typoscriptObjectPath="lib.myCounter">{post.viewCount}</f:cObject>
+
+Alternatively, we can use a self-closing tag. The data is being passed
+with the help of the :html:`data` attribute.
+
+.. code-block:: html
+   :caption: EXT:my_extension/Resources/Private/Templates/SomeTemplate.html
+
+   <f:cObject typoscriptObjectPath="lib.myCounter" data="{post.viewCount}" />
+
+Also advisable for this example is the inline notation, because you can
+easily read it from left to right:
+
+.. code-block:: html
+   :caption: EXT:my_extension/Resources/Private/Templates/SomeTemplate.html
+
+   {post.viewCount -> f:cObject(typoscriptObjectPath: 'lib.myCounter')}
+
+Now we still have to evaluate the passed value in our TypoScript
+template. We can use the :typoscript:`stdWrap` attribute :typoscript:`current`
+to achieve this. It works like a switch: If set to 1, the value, which we
+passed to the TypoScript object in the Fluid template will be used. In our
+example, it looks like this:
+
+.. code-block:: typoscript
+   :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript
+
+   lib.myCounter = TEXT
+   lib.myCounter {
+      current = 1
+      wrap = <strong>|</strong>
+   }
+
+This TypoScript snippet outputs the current number of visits written
+in bold.
+
+Now for example we can output the user counter as image instead of
+text without modifying the Fluid template. We simply have to use the
+following TypoScript:
+
+.. code-block:: typoscript
+   :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript
+
+   lib.myCounter = IMAGE
+   lib.myCounter {
+      file = GIFBUILDER
+      file {
+         10 = TEXT
+         10.text.current = 1
+      }
+   }
+
+At the moment, we're only passing a single value to the TypoScript.
+It's more versatile, though, to pass multiple values to the TypoScript object
+because then you can select which value to use in the TypoScript, and the
+values can be concatenated. You can also pass whole objects to the
+ViewHelper in the template:
+
+.. code-block:: html
+   :caption: EXT:my_extension/Resources/Private/Templates/SomeTemplate.html
+
+   {post -> f:cObject(typoscriptObjectPath: 'lib.myCounter')}
+
+Now, how do you access individual properties of the object in the
+TypoScript-Setup? You can use the property :typoscript:`field` of
+:typoscript:`stdWrap`:
+
+.. code-block:: typoscript
+   :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript
+
+   lib.myCounter = COA
+   lib.myCounter {
+      10 = TEXT
+      10.field = title
+      20 = TEXT
+      20.field = viewCount
+      wrap = (<strong>|</strong>)
+   }
+
+Now we always output the title of the blog, followed by the amount of
+page visits in parenthesis in the example above.
+
+You can also combine the :typoscript:`field` based approach with
+:typoscript:`current`: If you set the property :html:`currentValueKey`
+in the cObject ViewHelper, this value will be available in
+the TypoScript template with :typoscript:`current`. That is especially useful
+when you want to emphasize that the value is very
+*important* for the TypoScript template. For example, the
+*amount of visits* is significant in our view
+counter:
+
+.. code-block:: html
+   :caption: EXT:my_extension/Resources/Private/Templates/SomeTemplate.html
+
+   {post -> f:cObject(typoscriptObjectPath: 'lib.myCounter', currentValueKey: 'viewCount')}
+
+In the TypoScript template you can now use both, :typoscript:`current`
+and :typoscript:`field`, and have therefor the maximum flexibility with the
+greatest readability. The following TypoScript snippet outputs the same
+information as the previous example:
+
+.. code-block:: typoscript
+   :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript
+
+   lib.myCounter = COA
+   lib.myCounter {
+      10 = TEXT
+      10.field = title
+      20 = TEXT
+      20.current = 1
+      wrap = (<strong>|</strong>)
+   }
+
+The cObject ViewHelper is a powerful option to use the
+best advantages of both worlds by making it possible to embed TypoScript
+expressions in Fluid templates.