[TASK] Document carousel Content Block (#340) (#346)

sfroemkenjw · linawolf · web-flow · commit 7334554fd8b4 · 2025-01-28T16:50:53.000+01:00
* [TASK] Document carousel

Releases: main, 13.4

* [TASK] Document carousel

Releases: main, 13.4

* [TASK] Document carousel

Releases: main, 13.4

* Update Carousel.rst

* Update Documentation/ContentBlocks/Carousel.rst

* Update Index.rst

Co-authored-by: Lina Wolf &lt;48202465+linawolf@users.noreply.github.com&gt;
diff --git a/Documentation/CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/backend-preview.html b/Documentation/CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/backend-preview.html
@@ -1,12 +1,22 @@
-<f:asset.css identifier="content-block-t3docs-t3docs/carousel-be" href="{cb:assetPath()}/preview.css"/>
+<f:layout name="Preview"/>
 
-<div class="row">
-    <f:for each="{data.carousel_items}" as="item" iteration="iteration">
-        <div class="col">
-            <f:for each="{item.image}" as="image" iteration="iteration">
-                <f:image image="{image}" width="100"/><br/>
-            </f:for>
-            {item.header}
-        </div>
-    </f:for>
-</div>
+<f:section name="Header">
+    <f:variable name="itemCount"><f:count subject="{data.carousel_items}" /></f:variable>
+    <div>{f:translate(key: '{cb:languagePath()}:backend.itemCount', arguments: {0: '{itemCount}'})}</div>
+</f:section>
+
+<f:section name="Content">
+    <div class="row">
+        <f:for each="{data.carousel_items}" as="item" iteration="iteration">
+            <div class="col">
+                <f:image image="{item.image}" width="100"/><br/>
+                {item.header}
+            </div>
+        </f:for>
+    </div>
+</f:section>
+
+<f:section name="Footer">
+    <f:variable name="lastUpdated"><f:format.date>{data.rawRecord.crdate}</f:format.date></f:variable>
+    <div>{f:translate(key: '{cb:languagePath()}:backend.lastUpdated', arguments: {0: '{lastUpdated}'})}</div>
+</f:section>
diff --git a/Documentation/CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/frontend.html b/Documentation/CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/frontend.html
@@ -10,9 +10,7 @@
     <div class="carousel-inner">
         <f:for each="{data.carousel_items}" as="item" iteration="iteration">
             <div class="carousel-item{f:if(condition: '{iteration.isFirst}', then:' active')}">
-                <f:for each="{item.image}" as="image" iteration="iteration">
-                    <f:image image="{image}" class="d-block w-100"/>
-                </f:for>
+                <f:image image="{item.image}" class="d-block w-100"/>
                 <div class="carousel-caption d-none d-md-block">
                     <h5>{item.header}</h5>
                     <f:format.html>{item.description}</f:format.html>
diff --git a/Documentation/CodeSnippets/my_site_package/ContentBlocks/ContentElements/jumbotron/assets/icon.svg b/Documentation/CodeSnippets/my_site_package/ContentBlocks/ContentElements/jumbotron/assets/icon.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" viewBox="0 0 16 16"><path fill="#FFF" d="M1 1h14v14H1V1z"/><path fill="#999" d="M1 1v14h14V1H1zm1 1h12v12H2V2z"/><path fill="#666" d="M3 3h10v1H3V3z"/><path fill="#B9B9B9" d="M3 5h10v1H3V5z"/><path fill="#59F" d="M7 7h6v6H7V7z"/><path fill="#FFF" d="M11 12H8l.75-1 .75-1 .75 1 .75 1z"/><path fill="#FFF" d="M12 12H9.333l.667-.667.667-.666.666.666L12 12z"/><circle cx="11.5" cy="9.5" r=".5" fill="#FFF"/><path fill="#B9B9B9" d="M3 7h3v1H3V7zm0 2h3v1H3V9zm0 2h3v1H3v-1z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" viewBox="0 0 16 16"><path fill="#FFF" d="M1 1h14v14H1V1z"/><path fill="#999" d="M1 1v14h14V1H1zm1 1h12v12H2V2z"/><path fill="#666" d="M3 3h10v1H3V3z"/><path fill="#B9B9B9" d="M3 5h10v1H3V5z"/><path fill="#59F" d="M7 7h6v6H7V7z"/><path fill="#FFF" d="M11 12H8l.75-1 .75-1 .75 1 .75 1z"/><path fill="#FFF" d="M12 12H9.333l.667-.667.667-.666.666.666L12 12z"/><circle cx="11.5" cy="9.5" r=".5" fill="#FFF"/><path fill="#B9B9B9" d="M3 7h3v1H3V7zm0 2h3v1H3V9zm0 2h3v1H3v-1z"/></svg>
diff --git a/Documentation/CodeSnippets/my_site_package/Resources/Private/Language/locallang.xlf b/Documentation/CodeSnippets/my_site_package/Resources/Private/Language/locallang.xlf
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
 <xliff version="1.0">
-    <file source-language="en" datatype="plaintext" original="messages" date="2024-12-11UTC10:20:370">
+    <file source-language="en" datatype="plaintext" original="messages" date="2025-01-26UTC08:22:400">
         <header>
-            <authorName>J. Doe</authorName>
-            <authorEmail>j.doe@example.org</authorEmail>
+            <authorName>John Doe</authorName>
+            <authorEmail>j.doe@example.com</authorEmail>
         </header>
         <body>
         </body>
diff --git a/Documentation/CodeSnippets/my_site_package/Resources/Private/Language/locallang_be.xlf b/Documentation/CodeSnippets/my_site_package/Resources/Private/Language/locallang_be.xlf
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
 <xliff version="1.0">
-    <file source-language="en" datatype="plaintext" original="messages" date="2024-12-11UTC10:20:370">
+    <file source-language="en" datatype="plaintext" original="messages" date="2025-01-26UTC08:22:400">
         <header>
-            <authorName>J. Doe</authorName>
-            <authorEmail>j.doe@example.org</authorEmail>
+            <authorName>John Doe</authorName>
+            <authorEmail>j.doe@example.com</authorEmail>
         </header>
         <body>
             <trans-unit id="backend_layout.default">
@@ -21,6 +21,9 @@
             <trans-unit id="backend_layout.column.right">
                 <source>Right</source>
             </trans-unit>
+            <trans-unit id="content_element.group.my_site_package">
+                <source>My Site Package elements</source>
+            </trans-unit>
         </body>
     </file>
 </xliff>
diff --git a/Documentation/CodeSnippets/my_site_package/Resources/Private/Language/locallang_db.xlf b/Documentation/CodeSnippets/my_site_package/Resources/Private/Language/locallang_db.xlf
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
 <xliff version="1.0">
-    <file source-language="en" datatype="plaintext" original="messages" date="2024-12-11UTC10:20:370">
+    <file source-language="en" datatype="plaintext" original="messages" date="2025-01-26UTC08:22:400">
         <header>
-            <authorName>J. Doe</authorName>
-            <authorEmail>j.doe@example.org</authorEmail>
+            <authorName>John Doe</authorName>
+            <authorEmail>j.doe@example.com</authorEmail>
         </header>
         <body>
         </body>
diff --git a/Documentation/CodeSnippets/my_site_package/Resources/Public/Icons/Extension.svg b/Documentation/CodeSnippets/my_site_package/Resources/Public/Icons/Extension.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><path fill="#FF8700" d="M0 0h64v64H0z"/><path fill="#FFF" d="M42.8 32.8c-3.6 0-8.1-10.1-8.1-15.1 0-2.3.9-2.7 3.2-2.7 5.5 0 11 .9 11 4-.1 6.2-4 13.8-6.1 13.8zM28.5 18.5c0 5 6.4 20.2 10.7 20.2.5 0 .9-.1 1.4-.2-3.8 6.1-8.4 10.6-11.2 10.6-5.9 0-14.3-17.9-14.3-25.7 0-1.2.3-2.2.7-2.8 2-2.5 8.4-4.4 13.7-5-.6.4-1 1-1 2.9z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><path fill="#FF8700" d="M0 0h64v64H0z"/><path fill="#FFF" d="M42.8 32.8c-3.6 0-8.1-10.1-8.1-15.1 0-2.3.9-2.7 3.2-2.7 5.5 0 11 .9 11 4-.1 6.2-4 13.8-6.1 13.8zM28.5 18.5c0 5 6.4 20.2 10.7 20.2.5 0 .9-.1 1.4-.2-3.8 6.1-8.4 10.6-11.2 10.6-5.9 0-14.3-17.9-14.3-25.7 0-1.2.3-2.2.7-2.8 2-2.5 8.4-4.4 13.7-5-.6.4-1 1-1 2.9z"/></svg>
diff --git a/Documentation/CodeSnippets/my_site_package/Resources/Public/Images/logo.svg b/Documentation/CodeSnippets/my_site_package/Resources/Public/Images/logo.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><path fill="#FF8700" d="M0 0h64v64H0z"/><path fill="#FFF" d="M42.8 32.8c-3.6 0-8.1-10.1-8.1-15.1 0-2.3.9-2.7 3.2-2.7 5.5 0 11 .9 11 4-.1 6.2-4 13.8-6.1 13.8zM28.5 18.5c0 5 6.4 20.2 10.7 20.2.5 0 .9-.1 1.4-.2-3.8 6.1-8.4 10.6-11.2 10.6-5.9 0-14.3-17.9-14.3-25.7 0-1.2.3-2.2.7-2.8 2-2.5 8.4-4.4 13.7-5-.6.4-1 1-1 2.9z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><path fill="#FF8700" d="M0 0h64v64H0z"/><path fill="#FFF" d="M42.8 32.8c-3.6 0-8.1-10.1-8.1-15.1 0-2.3.9-2.7 3.2-2.7 5.5 0 11 .9 11 4-.1 6.2-4 13.8-6.1 13.8zM28.5 18.5c0 5 6.4 20.2 10.7 20.2.5 0 .9-.1 1.4-.2-3.8 6.1-8.4 10.6-11.2 10.6-5.9 0-14.3-17.9-14.3-25.7 0-1.2.3-2.2.7-2.8 2-2.5 8.4-4.4 13.7-5-.6.4-1 1-1 2.9z"/></svg>
diff --git a/Documentation/CodeSnippets/my_site_package/composer.json b/Documentation/CodeSnippets/my_site_package/composer.json
@@ -1,8 +1,8 @@
 {
     "name": "my-vendor/my-site-package",
     "type": "typo3-cms-extension",
-    "description": "Site package to follow the tutorial.",
-    "homepage": "https://docs.typo3.org/permalink/t3sitepackage:start",
+    "description": "",
+    "homepage": "https://example.com",
     "license": ["GPL-2.0-or-later"],
     "keywords": ["TYPO3 CMS"],
     "require": {
diff --git a/Documentation/CodeSnippets/my_site_package/ext_emconf.php b/Documentation/CodeSnippets/my_site_package/ext_emconf.php
@@ -2,7 +2,7 @@
 
 $EM_CONF[$_EXTKEY] = [
     'title' => 'My Site Package',
-    'description' => 'Site package to follow the tutorial.',
+    'description' => '',
     'category' => 'templates',
     'constraints' => [
         'depends' => [
@@ -22,8 +22,8 @@
     'uploadfolder' => 0,
     'createDirs' => '',
     'clearCacheOnLoad' => 1,
-    'author' => 'J. Doe',
-    'author_email' => 'j.doe@example.org',
+    'author' => 'John Doe',
+    'author_email' => 'j.doe@example.com',
     'author_company' => 'My Vendor',
     'version' => '1.0.0',
 ];
diff --git a/Documentation/ContentBlocks/Carousel.rst b/Documentation/ContentBlocks/Carousel.rst
@@ -0,0 +1,182 @@
+:navigation-title: Carousel
+..  include:: /Includes.rst.txt
+
+..  _carousel:
+
+==============================
+Carousel Content Block example
+==============================
+
+This content block demonstrates some additional features of
+:composer:`friendsoftypo3/content-blocks`. We assume that you are already
+familiar with the concepts described in chapter
+`Custom Content Blocks <https://docs.typo3.org/permalink/t3sitepackage:content-blocks>`_.
+
+..  contents:: Table of contents
+
+..  _carousel-directory:
+
+Directory structure of the carousel content element
+===================================================
+
+Additionally to the files that the jumbotron provides (compare
+:ref:`content-blocks-jumbotron-directory`), the carousel comes with special CSS
+and JavaScript needed for this element only.
+
+Additionally it supplies a template for its display in the backend.
+
+..  directory-tree::
+    :level: 2
+    :show-file-icons: true
+
+    *   packages/my_site_package/ContentBlocks/ContentElements/carousel
+
+        *   assets
+
+            *   frontend.css
+            *   frontend.js
+            *   icon.svg
+
+        *   language
+
+            *   labels.xlf
+
+        *   templates
+
+            *   backend-preview.html
+            *   frontend.html
+
+        *   config.yaml
+
+..  _carousel-configuration:
+
+The carousel: A Content Block containing a collection of elements
+=================================================================
+
+The carousel can contain one or several items, each of which has an image,
+header, and description:
+
+..  literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/config.yaml
+    :caption: packages/my_site_package/ContentBlocks/ContentElements/carousel/config.yaml
+    :linenos:
+
+Line 8: We use a field of type
+`Collection <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-collection>`_
+to contain the items to be displayed in the carousel. This field type expects
+an array of fields (line 10ff).
+
+Line 15: We use the type
+`File <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-file>`_
+to reference the image for the carousel item. We allow images only (line 16)
+and require exactly one image (lines 17 and 18).
+
+Line 20: The title should be one line of text. We use the type
+`Text <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-text>`_.
+
+Line 22: The description may contain rich text. Therefore, we use the type
+`Textarea <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-textarea>`_
+and enable the Rich-Text Editor (line 23).
+
+..  _carousel-fluid:
+
+Frontend template: Fluid template for a Content Block with a Collection
+=======================================================================
+
+..  literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/frontend.html
+    :caption: packages/my_site_package/ContentBlocks/ContentElements/carousel/templates/frontend.html
+    :linenos:
+
+Line 1: We use `Asset.css ViewHelper <f:asset.css> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-css>`_
+to load the provided CSS file only if a carousel is displayed on that page. The
+`Asset collector <https://docs.typo3.org/permalink/t3coreapi:asset-collector>`_
+takes care that the file is not loaded more then once per page. All Fluid
+ViewHelpers prefixed with `cb:` are provided by :composer:`friendsoftypo3/content-blocks`
+they are therefore not listed in the official View Helper reference. The inline
+ViewHelper `cb:assetPath()` resolves paths to the `asset` folder of the current
+content block.
+
+Line 2: We use the `Asset.script ViewHelper <f:asset.script> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-script>`_
+to load the JavaScript file the same way.
+
+Line 6: We use the `For ViewHelper <f:for> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-for>`_
+to loop through each item. We then render a button for each carousel item.
+
+Line 11: We loop the items a second time to now display all carousel slides.
+
+Line 13: The field `image` was defined with option `relationship: manyToOne` in
+the :ref:`config.yaml <carousel-configuration>` it can therefore only contain
+one image at maximum. As supplying an image is also mandatory `minitems: 1`
+we can be sure there is always exactly one image. And just use the
+`Image ViewHelper <f:image> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-image>`_
+to display the image.
+
+Line 16: As the field `{item.description}` is of type Textarea with rich-text
+enabled we have to use the `Format.html ViewHelper <f:format.html> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-format-html>`_
+to properly display it.
+
+Line 23, 27: The previous and next buttons use localized text for their labels.
+We use the `Translate ViewHelper <f:translate> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-translate>`_
+to translate these labels and a view helper provided by the Content Block
+extension to determine the path to the language file.
+
+..  _carousel-backend-fluid:
+
+Content Block with backend template
+===================================
+
+This Content Block contains a template to influence how the content elements
+should be displayed in the TYPO3 backend in the Page module:
+
+..  literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/backend-preview.html
+    :caption: packages/my_site_package/ContentBlocks/ContentElements/carousel/templates/backend-preview.html
+    :linenos:
+
+The same fields like for the frontend template are available and the same
+ViewHelpers can be used. However we display them in a simplified form.
+
+Line 1: We are using the layout `Preview`, which already gives some structure to
+the display of the backend element:
+
+..  figure:: /Images/ContentBlocks/BackendLayout.png
+    :alt: Screenshot of a Content Block in the TYPO3 Backend, demonstrating the sections of the layout
+
+    The sections of a content element backend layout: (1) Header, (2) Content, (3) Footer
+
+The line on the very top with the name of the content element, the icon and the
+edit buttons is generated by TYPO3 automatically and cannot be influenced by
+a backend template. It uses the label `title` defined in :file:`language/labels.xlf`
+and the icon :file:`assets/icon.svg`.
+
+As always we use the `Layout ViewHelper <f:layout> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-layout>`_
+to select the `Preview` layout.
+
+Each section is declared using the `Section ViewHelper <f:section> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-section>`_.
+
+Line 10: We once more use the
+`For ViewHelper <f:for> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-for>`_
+to loop through all items of the slider and display them one by one.
+
+Line 21: Labels can and should also be localized in the backend. To not lose
+context we prefixed all labels to be used in the backend with `backend.`.
+
+..  tip::
+    See also chapter `Backend Preview in the Content Blocks
+    manual <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:api-backend-preview>`_.
+
+
+..  _carousel-assets:
+
+Content Block specific assets
+=============================
+
+The assets in folder :directory:`assets` can be loaded in the
+:ref:`Frontend Template <carousel-fluid>`. They will only be loaded when the
+Content Block is loaded on the current page. If compression
+(:ref:`config.compressCss <t3tsref:confval-config-compresscss>`,
+:ref:`config.compressJs <t3tsref:confval-config-compressjs>`) and concatenation
+(:ref:`config.concatenateCss <t3tsref:confval-config-concatenatecss>`,
+:ref:`concatenateJs <t3tsref:confval-config-concatenatejs>`) are enabled
+all assets are compressed and concatenated into as few as possible small asset
+files.
+
+This also has the advantage that your JavaScript is only loaded if needed.
diff --git a/Documentation/ContentBlocks/Index.rst b/Documentation/ContentBlocks/Index.rst
@@ -14,11 +14,19 @@ HTMl layout.
 This is because the stage does not contain normal content, as provided by
 Fluid-Styled Content, but a Jumbotron element or a slider.
 
+..  contents:: Table of contents
+
 ..  note::
     The extension :composer:`friendsoftypo3/content-blocks` is not an official
     part of the TYPO3 Core yet. It is also possible to
     `Create a custom content element with TYPO3 Core only <https://docs.typo3.org/permalink/t3coreapi:adding-your-own-content-elements>`_.
 
+..  toctree::
+    :glob:
+    :hidden:
+
+    *
+
 ..  _content-blocks-installation:
 
 Install extension Content Blocks
@@ -147,12 +155,21 @@ to format and sanitize the output.
 Line 5: We use the `Link.typolink ViewHelper <f:link.typolink> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-link-typolink>`_
 to render a link to the target that was defined in our custom field `button_link`.
 
+..  _content-blocks-carousel:
+
+The carousel Content Block
+==========================
+
+The carousel Content block is provided in the generated site package as an
+example on how to create a content block that contains on repeated items, here a
+carousel with multiple slides.
+
+It is described in chapter `Carousel Content Block example <https://docs.typo3.org/permalink/t3sitepackage:carousel>`_.
+
 ..  _content-blocks-next:
 
 Next steps
 ==========
 
-*   The generated site package contains a second, more elaborate example in
-    directory :path:`packages/my_site_package/ContentBlocks/ContentElements/carousel`.
 *   Learn how to use the `Kickstart command <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:cb-skeleton>`_
     to create your own Content Blocks.
diff --git a/Documentation/Images/ContentBlocks/BackendLayout.png b/Documentation/Images/ContentBlocks/BackendLayout.png
