Skip to content

Commit 7981ece

Browse files
linawolflinawolf
committed
[TASK] Improve the format.html docs (#208)
Releases: main, 13.4 (cherry picked from commit 9e1261f)
1 parent 9de5630 commit 7981ece

1 file changed

Lines changed: 127 additions & 39 deletions

File tree

‎Documentation/Global/Format/Html.rst‎

Lines changed: 127 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -9,84 +9,172 @@ Format.html ViewHelper `<f:format.html>`
99

1010
.. typo3:viewhelper:: format.html
1111
:source: ../../Global.json
12+
:display: tags,description,gitHubLink
13+
:noindex:
14+
15+
.. contents:: Table of contents
1216

1317
.. _typo3-fluid-format-html-example:
1418

15-
Examples
16-
========
19+
Using the `<f:format.html>` ViewHelper with default arguments
20+
=============================================================
21+
22+
.. code-block:: html
23+
24+
<f:format.html>
25+
{$myConstant.project} is a cool <b>CMS</b>
26+
(<a href="https://www.typo3.org">TYPO3</a>).
27+
</f:format.html>
28+
29+
.. code-block:: html
30+
31+
<p class="bodytext">TYPO3 is a cool <strong>CMS</strong>
32+
(<a href="https://www.typo3.org" target="_blank">TYPO3</a>).</p>
33+
34+
The exact output depends on TYPO3 constants.
35+
36+
.. _typo3-fluid-format-html-arguments:
37+
38+
Arguments of the `<f:format.html>` ViewHelper
39+
=============================================
40+
41+
.. typo3:viewhelper:: format.html
42+
:source: ../../Global.json
43+
:display: arguments-only
44+
45+
.. _typo3-fluid-format-html-parseFunc:
46+
47+
parseFuncTSPath argument: formatting text with a custom parsing function
48+
------------------------------------------------------------------------
1749

18-
Default parameters
19-
------------------
50+
The `parseFuncTSPath` argument specifies which TypoScript `parseFunc`
51+
configuration is used to process the content.
2052

21-
::
53+
.. code-block:: html
2254

23-
<f:format.html>{$myConstant.project} is a cool <b>CMS</b> (<a href="https://www.typo3.org">TYPO3</a>).</f:format.html>
55+
<f:format.html parseFuncTSPath="lib.parseFunc">
56+
{someText}
57+
</f:format.html>
2458

25-
Output::
59+
or inline:
2660

27-
<p class="bodytext">TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).</p>
61+
.. code-block:: html
2862

29-
Depending on TYPO3 constants.
63+
{someText -> f:format.html(parseFuncTSPath: 'lib.myParseFunc')}
3064

31-
Custom parseFunc
32-
----------------
65+
With a custom parsing function defined in TypoScript:
3366

34-
::
67+
.. code-block:: typoscript
68+
:caption: config/site/mysite/setup.typoscript
3569
36-
<f:format.html parseFuncTSPath="lib.parseFunc">TYPO3 is a cool <b>CMS</b> (<a href="https://www.typo3.org">TYPO3</a>).</f:format.html>
70+
lib.myParseFunc < lib.parseFunc
71+
lib.myParseFunc {
72+
// replace --- with soft-hyphen
73+
short.--- = &shy;
74+
}
3775
38-
Output::
76+
.. seealso::
3977

40-
TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).
78+
For all options see the
79+
`TypoScript reference, chapter parseFunc <https://docs.typo3.org/permalink/t3tsref:parsefunc>`_.
80+
81+
.. _typo3-fluid-format-html-arguments-data:
4182

4283
Data argument
4384
--------------
4485

45-
If you work with TypoScript :typoscript:`field` property, you should add the current record as `data`
46-
to the ViewHelper to allow processing the `field` and `dataWrap` properties correctly.
86+
If you use TypoScript properties such as :typoscript:`field` or :typoscript:`dataWrap`,
87+
you should pass the current record as `data`. This ensures that field references like
88+
`{FIELD:title}` are resolved correctly.
89+
90+
.. code-block:: html
91+
92+
<f:format.html
93+
data="{newsRecord}"
94+
parseFuncTSPath="lib.myParseFunc"
95+
>
96+
News title:
97+
</f:format.html>
98+
99+
You may get the following output:
47100

48-
::
101+
.. code-block:: html
49102

50-
<f:format.html data="{newsRecord}" parseFuncTSPath="lib.news">News title: </f:format.html>
103+
News title: <strong>TYPO3, greatest CMS ever</strong>
51104

52-
After "dataWrap = |<strong>{FIELD:title}</strong>" you may have this Output::
105+
With a custom parsing function defined in TypoScript:
53106

54-
News title: <strong>TYPO3, greatest CMS ever</strong>
107+
.. code-block:: typoscript
108+
:caption: config/site/mysite/setup.typoscript
109+
110+
lib.myParseFunc < lib.parseFunc
111+
lib.myParseFunc {
112+
dataWrap = |<strong>{FIELD:title}</strong>
113+
}
114+
115+
.. _typo3-fluid-format-html-arguments-data-current:
55116

56117
Current argument
57118
-----------------
58119

59-
Use the `current` argument to set the current value of the content object.
120+
Use the `current` argument to override the current value used by the TypoScript
121+
content object.
60122

61-
::
123+
.. code-block:: html
62124

63-
<f:format.html current="{strContent}" parseFuncTSPath="lib.info">I'm gone</f:format.html>
125+
<f:format.html
126+
current="{strContent}"
127+
parseFuncTSPath="lib.myParseFunc"
128+
>
129+
I'm gone
130+
</f:format.html>
64131

65-
After `setContentToCurrent = 1` you may have this output::
132+
You may get the following output:
66133

67-
Thanks Kasper for this great CMS
134+
.. code-block:: html
68135

69-
CurrentValueKey argument
70-
-------------------------
136+
Thanks Kasper for this great CMS
137+
138+
With the following custom parsing function defined in TypoScript:
139+
140+
.. code-block:: typoscript
141+
:caption: config/site/mysite/setup.typoscript
71142
72-
Use the `currentValueKey` argument to define a value of data object as the current value.
143+
lib.myParseFunc < lib.parseFunc
144+
lib.myParseFunc {
145+
setContentToCurrent = 1
146+
}
73147
74-
::
148+
.. _typo3-fluid-format-html-arguments-data-CurrentValueKey:
149+
150+
CurrentValueKey argument
151+
-------------------------
75152

76-
<f:format.html data="{contentRecord}" currentValueKey="header" parseFuncTSPath="lib.content">Content: </f:format.html>
153+
Use the `currentValueKey` argument to define a value of data object as the
154+
current value.
77155

78-
After `dataWrap = |{CURRENT:1}` you may have this Output::
156+
.. code-block:: html
79157

80-
Content: How to install TYPO3 in under 2 minutes ;-)
158+
<f:format.html
159+
data="{contentRecord}"
160+
currentValueKey="header"
161+
parseFuncTSPath="lib.content"
162+
>
163+
Content:
164+
</f:format.html>
81165

82-
Inline notation
83-
---------------
166+
You may get the following output:
84167

85-
::
168+
.. code-block:: html
86169

87-
{someText -> f:format.html(parseFuncTSPath: 'lib.parseFunc')}
170+
Content: How to install TYPO3 in under 2 minutes ;-)
88171

89-
Output::
172+
With the following custom parsing function defined in TypoScript:
90173

91-
TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).
174+
.. code-block:: typoscript
175+
:caption: config/site/mysite/setup.typoscript
92176
177+
lib.myParseFunc < lib.parseFunc
178+
lib.myParseFunc {
179+
dataWrap = |{CURRENT:1}
180+
}

0 commit comments

Comments
 (0)