Skip to content

[TASK] Improve the format.html docs #208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
linawolf merged 1 commit into from
Mar 23, 2026
Merged

[TASK] Improve the format.html docs #208

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 127 additions & 38 deletions Documentation/Global/Format/Html.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,83 +9,172 @@ Format.html ViewHelper `<f:format.html>`

.. typo3:viewhelper:: format.html
:source: ../../Global.json
:display: tags,description,gitHubLink
:noindex:

.. contents:: Table of contents

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

Examples
========
Using the `<f:format.html>` ViewHelper with default arguments
=============================================================

.. code-block:: html

<f:format.html>
{$myConstant.project} is a cool <b>CMS</b>
(<a href="https://www.typo3.org">TYPO3</a>).
</f:format.html>

.. code-block:: html

<p class="bodytext">TYPO3 is a cool <strong>CMS</strong>
(<a href="https://www.typo3.org" target="_blank">TYPO3</a>).</p>

The exact output depends on TYPO3 constants.

.. _typo3-fluid-format-html-arguments:

Arguments of the `<f:format.html>` ViewHelper
=============================================

.. typo3:viewhelper:: format.html
:source: ../../Global.json
:display: arguments-only

.. _typo3-fluid-format-html-parseFunc:

parseFuncTSPath argument: formatting text with a custom parsing function
------------------------------------------------------------------------

Default parameters
------------------
The `parseFuncTSPath` argument specifies which TypoScript `parseFunc`
configuration is used to process the content.

::
.. code-block:: html

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

Output::
or inline:

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

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

Custom parseFunc
----------------
With a custom parsing function defined in TypoScript:

::
.. code-block:: typoscript
:caption: config/site/mysite/setup.typoscript

<f:format.html parseFuncTSPath="lib.parseFunc">TYPO3 is a cool <b>CMS</b> (<a href="https://www.typo3.org">TYPO3</a>).</f:format.html>
lib.myParseFunc < lib.parseFunc
lib.myParseFunc {
// replace --- with soft-hyphen
short.--- = &shy;
}

Output::
.. seealso::

TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).
For all options see the
`TypoScript reference, chapter parseFunc <https://docs.typo3.org/permalink/t3tsref:parsefunc>`_.

.. _typo3-fluid-format-html-arguments-data:

Data argument
--------------

If you work with TypoScript :typoscript:`field` property, you should add the current record as `data`
to the ViewHelper to allow processing the `field` and `dataWrap` properties correctly.
If you use TypoScript properties such as :typoscript:`field` or :typoscript:`dataWrap`,
you should pass the current record as `data`. This ensures that field references like
`{FIELD:title}` are resolved correctly.

.. code-block:: html

<f:format.html
data="{newsRecord}"
parseFuncTSPath="lib.myParseFunc"
>
News title:
</f:format.html>

You may get the following output:

.. code-block:: html

News title: <strong>TYPO3, greatest CMS ever</strong>

::
With a custom parsing function defined in TypoScript:

<f:format.html data="{newsRecord}" parseFuncTSPath="lib.news">News title: </f:format.html>
.. code-block:: typoscript
:caption: config/site/mysite/setup.typoscript

After "dataWrap = |<strong>{FIELD:title}</strong>" you may have this Output::
lib.myParseFunc < lib.parseFunc
lib.myParseFunc {
dataWrap = |<strong>{FIELD:title}</strong>
}

News title: <strong>TYPO3, greatest CMS ever</strong>
.. _typo3-fluid-format-html-arguments-data-current:

Current argument
-----------------

Use the `current` argument to set the current value of the content object.
Use the `current` argument to override the current value used by the TypoScript
content object.

::
.. code-block:: html

<f:format.html current="{strContent}" parseFuncTSPath="lib.info">I'm gone</f:format.html>
<f:format.html
current="{strContent}"
parseFuncTSPath="lib.myParseFunc"
>
I'm gone
</f:format.html>

After `setContentToCurrent = 1` you may have this output::
You may get the following output:

Thanks Kasper for this great CMS
.. code-block:: html

Thanks Kasper for this great CMS

With the following custom parsing function defined in TypoScript:

.. code-block:: typoscript
:caption: config/site/mysite/setup.typoscript

lib.myParseFunc < lib.parseFunc
lib.myParseFunc {
setContentToCurrent = 1
}

.. _typo3-fluid-format-html-arguments-data-CurrentValueKey:

CurrentValueKey argument
-------------------------

Use the `currentValueKey` argument to define a value of data object as the current value.

::
Use the `currentValueKey` argument to define a value of data object as the
current value.

<f:format.html data="{contentRecord}" currentValueKey="header" parseFuncTSPath="lib.content">Content: </f:format.html>
.. code-block:: html

After `dataWrap = |{CURRENT:1}` you may have this Output::
<f:format.html
data="{contentRecord}"
currentValueKey="header"
parseFuncTSPath="lib.content"
>
Content:
</f:format.html>

Content: How to install TYPO3 in under 2 minutes ;-)
You may get the following output:

Inline notation
---------------
.. code-block:: html

::
Content: How to install TYPO3 in under 2 minutes ;-)

{someText -> f:format.html(parseFuncTSPath: 'lib.parseFunc')}
With the following custom parsing function defined in TypoScript:

Output::
.. code-block:: typoscript
:caption: config/site/mysite/setup.typoscript

TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).
lib.myParseFunc < lib.parseFunc
lib.myParseFunc {
dataWrap = |{CURRENT:1}
}