Skip to content

Commit 1c6eaa1

Browse files
linawolflinawolf
committed
[TASK] Document carousel
Releases: main, 13.4
1 parent a53699c commit 1c6eaa1

File tree

2 files changed

+136
-2
lines changed

2 files changed

+136
-2
lines changed

‎Documentation/ContentBlocks/Carousel.rst‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
:navigation-title: Carousel
2+
.. include:: /Includes.rst.txt
3+
4+
.. _carousel:
5+
6+
==============================
7+
Carousel Content Block example
8+
==============================
9+
10+
This content block demonstrates some additional features of
11+
:composer:`friendsoftypo3/content-blocks`. We assume that you are already
12+
familiar with the concepts described in chapter
13+
`Custom Content Blocks <https://docs.typo3.org/permalink/t3sitepackage:content-blocks>`_.
14+
15+
.. _carousel-directory:
16+
17+
Directory structure of the carousel content element
18+
===================================================
19+
20+
Additionally to the files that the jumbotron (compare
21+
:ref:`content-blocks-jumbotron-directory`) the carousel comes with special CSS
22+
and JavaScript needed for this element only.
23+
24+
Additionally it supplies a template for its display in the backend.
25+
26+
.. directory-tree::
27+
:level: 2
28+
:show-file-icons: true
29+
30+
* packages/my_site_package/ContentBlocks/ContentElements/jumbotron
31+
32+
* assets
33+
34+
* frontend.css
35+
* frontend.js
36+
* icon.svg
37+
38+
* language
39+
40+
* labels.xlf
41+
42+
* templates
43+
44+
* backend-preview.html
45+
* frontend.html
46+
47+
* config.yaml
48+
49+
.. _carousel-configuration:
50+
51+
The carousel: A Content Block containing a collection of elements
52+
=================================================================
53+
54+
The carousel can contain one or several items, each of which has an image,
55+
header, and description:
56+
57+
.. literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/config.yaml
58+
:caption: packages/my_site_package/ContentBlocks/ContentElements/carousel/config.yaml
59+
:linenos:
60+
61+
Line 8: We use a field of type
62+
`Collection <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-collection>`_
63+
to contain the items to be displayed in the carousel. This field type expects
64+
an array of fields (line 10ff).
65+
66+
Line 12: We use the type
67+
`File <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-file>`_
68+
to reference the image for the carousel item.
69+
70+
Line 14: The title should be one line of text. We use the type
71+
`Text <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-text>`_.
72+
73+
Line 16: The description may contain rich text. Therefore, we use the type
74+
`Textarea <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-textarea>`_
75+
and enable the Rich-Text Editor (line 17).
76+
77+
.. _carousel-fluid:
78+
79+
Frontend template: Fluid template for a Content Block with a Collection
80+
=======================================================================
81+
82+
.. literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/frontend.html
83+
:caption: packages/my_site_package/ContentBlocks/ContentElements/carousel/templates/frontend.html
84+
:linenos:
85+
86+
Line 1: We use `Asset.css ViewHelper <f:asset.css> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-css>`_
87+
to load the provided CSS file only if a carousel is displayed on that page. The
88+
`Asset collector <https://docs.typo3.org/permalink/t3coreapi:asset-collector>`_
89+
takes care that the file is not loaded more then once per page.
90+
91+
Line 2: We use the `Asset.script ViewHelper <f:asset.script> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-script>`_
92+
to load the JavaScript file the same way.
93+
94+
Line 6: We use the `For ViewHelper <f:for> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-for>`_
95+
to loop through each item. We then render a button for each carousel item.
96+
97+
Line 11: We loop the items a second time to now display all carousel slides.
98+
99+
Line 13: As the field of type "Files" may contain more then one file, the
100+
variable {data.carousel_items} contains an array. We loop through the array
101+
and display all images found.
102+
103+
Line 14: We use the `Image ViewHelper <f:image> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-image>`_
104+
to display the image.
105+
106+
Line 18: As the field `{item.description}` is of type Textarea with rich-text
107+
enabled we have to use the `Format.html ViewHelper <f:format.html> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-format-html>`_
108+
to properly display it.
109+
110+
Line 25, 29: The previous and next buttons use localized text for their labels.
111+
We use the `Translate ViewHelper <f:translate> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-translate>`_
112+
to translate these labels and a view helper provided by the Content Block
113+
extension to determine the path to the language file.
114+
115+
.. _carousel-backend-fluid:
116+
117+
Content Block with backend template
118+
===================================
119+
120+
This Content Block contains a template to influence how the content elements
121+
should be displayed in the TYPO3 backend in the Page module:
122+
123+
.. literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/carousel/templates/backend-preview.html
124+
:caption: packages/my_site_package/ContentBlocks/ContentElements/carousel/templates/backend-preview.html
125+
:linenos:
126+
127+
The same fields like for the frontend template are available and the same
128+
ViewHelpers can be used.

‎Documentation/ContentBlocks/Index.rst‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ Fluid-Styled Content, but a Jumbotron element or a slider.
1919
part of the TYPO3 Core yet. It is also possible to
2020
`Create a custom content element with TYPO3 Core only <https://docs.typo3.org/permalink/t3coreapi:adding-your-own-content-elements>`_.
2121

22+
.. toctree::
23+
:glob:
24+
:hidden:
25+
26+
*
27+
2228
.. _content-blocks-installation:
2329

2430
Install extension Content Blocks
@@ -152,7 +158,7 @@ to render a link to the target that was defined in our custom field `button_link
152158
Next steps
153159
==========
154160

155-
* The generated site package contains a second, more elaborate example in
156-
directory :path:`packages/my_site_package/ContentBlocks/ContentElements/carousel`.
161+
* The generated site package contains a second, more elaborate example, the
162+
:ref:`Carousel <carousel>`.
157163
* Learn how to use the `Kickstart command <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:cb-skeleton>`_
158164
to create your own Content Blocks.

0 commit comments

Comments
 (0)