Skip to content

Commit 20c1208

Browse files
github-actions[bot]linawolfnhovratov
authored
[Backport 13.4] [FEATURE] Document Content Block Examples (#326)
* [FEATURE] Document Content Block Examples Releases: main, 13.4 * [FEATURE] Document Content Block Examples Releases: main, 13.4 * [TASK] Add screenshot Releases: main, 13.4 * Update Documentation/ContentBlocks/Index.rst * Apply suggestions from code review * Update Documentation/ContentBlocks/Index.rst Co-authored-by: Nikita Hovratov <[email protected]> * Apply suggestions from code review Co-authored-by: Nikita Hovratov <[email protected]> --------- Co-authored-by: lina.wolf <[email protected]> Co-authored-by: Lina Wolf <[email protected]> Co-authored-by: Nikita Hovratov <[email protected]>
1 parent 18577cb commit 20c1208

File tree

3 files changed

+167
-0
lines changed

3 files changed

+167
-0
lines changed

‎Documentation/ContentBlocks/Index.rst‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
:navigation-title: Custom Content Blocks
2+
.. include:: /Includes.rst.txt
3+
4+
.. _content-blocks:
5+
6+
=====================
7+
Custom Content Blocks
8+
=====================
9+
10+
When we filled the `stage with content <https://docs.typo3.org/permalink/t3sitepackage:slide-mode>`_
11+
we noticed that the content does not look like the content within the original
12+
HTMl layout.
13+
14+
This is because the stage does not contain normal content, as provided by
15+
Fluid-Styled Content, but a Jumbotron element or a slider.
16+
17+
.. note::
18+
The extension :composer:`friendsoftypo3/content-blocks` is not an official
19+
part of the TYPO3 Core yet. It is also possible to
20+
`Create a custom content element with TYPO3 Core only <https://docs.typo3.org/permalink/t3coreapi:adding-your-own-content-elements>`_.
21+
22+
.. _content-blocks-installation:
23+
24+
Install extension Content Blocks
25+
================================
26+
27+
The extension :composer:`friendsoftypo3/content-blocks` is an extension that
28+
is not part of the TYPO3 Core but maintained by a group of community members.
29+
30+
There are plans to integrate this extension into the Core, however at the
31+
time of writing there are no finite decisions yet.
32+
33+
First install the extension :composer:`friendsoftypo3/content-blocks`:
34+
35+
.. code-block:: bash
36+
37+
ddev composer req friendsoftypo3/content-blocks
38+
39+
Set up the extension and delete all caches:
40+
41+
.. code-block:: bash
42+
43+
ddev typo3 extension:setup
44+
ddev typo3 cache:flush
45+
46+
.. _content-blocks-jumbotron:
47+
48+
The jumbotron Content Block
49+
===========================
50+
51+
The site package you generated in step
52+
`Generate a site package <https://docs.typo3.org/permalink/t3sitepackage:minimal-design>`_
53+
comes with two content elements. We look at the more basic content elements first.
54+
55+
You can now replace the content element in the area "Stage" of start page with
56+
one of type "Jumbotron".
57+
58+
.. figure:: /Images/ContentBlocks/CreateContentElement.png
59+
:alt: Screenshot of the "New Page Content" dialog with the Carousel and Jumbotron as additional features
60+
61+
The new Content Blocks "Jumbotron" and "Carousel"
62+
63+
You can now create a jumbotron with a button and a link.
64+
65+
Directory :path:`packages/my_site_package/ContentBlocks/ContentElements` contains
66+
one directory for each Content Block that can be used as normal Content Elements.
67+
68+
.. _content-blocks-jumbotron-directory:
69+
70+
Directory structure of a Content Block
71+
--------------------------------------
72+
73+
A Content Block consists of a configuration (:file:`config.yaml`), a template and
74+
optionally assets and or language files:
75+
76+
The jumbotron consists of the following files:
77+
78+
.. directory-tree::
79+
:level: 2
80+
:show-file-icons: true
81+
82+
* packages/my_site_package/ContentBlocks/ContentElements/jumbotron
83+
84+
* assets
85+
86+
* icon.svg
87+
88+
* language
89+
90+
* labels.xlf
91+
92+
* templates
93+
94+
* frontend.html
95+
96+
* config.yaml
97+
98+
.. _content-blocks-jumbotron-config:
99+
100+
The configuration of the jumbotron Content Block
101+
------------------------------------------------
102+
103+
File :path:`packages/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml`
104+
defines what fields should be available for the Content Block in the backend:
105+
106+
.. literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml
107+
:caption: packages/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml
108+
:linenos:
109+
110+
Each Content Block must have a unique name with a prefix of your choice that
111+
should be unique within your project. (Line 1)
112+
113+
It is possible to use fields that are already pre-defined in the TYPO3 Core like
114+
`header` (Line 8) and `bodytext` (Line 11).
115+
116+
We also newly define two fields, one of type `Text <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-text>`_
117+
(Line 15-19) and one of type `Link <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-type-link>`_
118+
(Line 21-23). You can find all available types here: `Field Types <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:field-types>`_.
119+
120+
The meaning behind the other settings here can be found in the
121+
`YAML reference of the Content Blocks guide <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:yaml-reference>`_.
122+
123+
.. _content-blocks-jumbotron-template:
124+
125+
The jumbotron template
126+
----------------------
127+
128+
The frontend template for the Content Block "Jumbotron" is a normal Fluid
129+
template. You already used Fluid for the
130+
`Page templates <https://docs.typo3.org/permalink/t3sitepackage:fluid-templates>`_
131+
and to adjust the templates of Fluid-Styled Content elements in chapter
132+
`Overriding the default templates of content elements <https://docs.typo3.org/permalink/t3sitepackage:content-element-rendering>`_.
133+
134+
.. literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/jumbotron/templates/frontend.html
135+
:caption: packages/my_site_package/ContentBlocks/ContentElements/jumbotron/templates/frontend.html
136+
:linenos:
137+
138+
Line 3: The values of the database entry of the current content element can be
139+
found in variable `{data}`. In this line we render the content of the field
140+
`header`. The field was defined in line 8 of the :file:`config.yaml`.
141+
142+
Line 4: Here we output the content of field `bodytext` as this field is a
143+
Rich-Text Editor we use the
144+
`Format.html ViewHelper <f:format.html> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-format-html>`_
145+
to format and sanitize the output.
146+
147+
Line 5: We use the `Link.typolink ViewHelper <f:link.typolink> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-link-typolink>`_
148+
to render a link to the target that was defined in our custom field `button_link`.
149+
150+
.. _content-blocks-next:
151+
152+
Next steps
153+
==========
154+
155+
* The generated site package contains a second, more elaborate example in
156+
directory :path:`packages/my_site_package/ContentBlocks/ContentElements/carousel`.
157+
* Learn how to use the `Kickstart command <https://docs.typo3.org/permalink/friendsoftypo3/content-blocks:cb-skeleton>`_
158+
to create your own Content Blocks.

‎Documentation/Images/ContentBlocks/CreateContentElement.png‎

19.2 KB
Loading

‎Documentation/Index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,14 @@ https://github.com/TYPO3-Documentation/site_package
100100
.. card-footer:: :ref:`Learn about the configuration of a site package <t3sitepackage:site-sets-configuration>`
101101
:button-style: btn btn-secondary stretched-link
102102

103+
.. card:: :ref:`Content Blocks <content-blocks>`
104+
105+
We explain how the TYPO3 Extension :composer:`friendsoftypo3/content-blocks`
106+
can be used to create custom Content Elements, for example for a jumbotron
107+
or slider.
108+
109+
.. card-footer:: :ref:`Learn to create custom Content Elements <content-blocks>`
110+
:button-style: btn btn-secondary stretched-link
103111

104112
.. card:: :ref:`Extension Configuration <t3sitepackage:extension-configuration>`
105113

@@ -131,6 +139,7 @@ https://github.com/TYPO3-Documentation/site_package
131139
MainMenuCreation/Index
132140
SiteSets/Index
133141
ContentElementRendering/Index
142+
ContentBlocks/Index
134143
Faq/Index
135144
NextSteps/Index
136145

0 commit comments

Comments
 (0)