Skip to content

Commit

Permalink
[TASK] Avoid the term "template" for TypoScript (#1395)
Browse files Browse the repository at this point in the history
As this PR will be backported to v12, the distinction
TypoScript record / TypoScript provided by site will be made in a follow up.

Releases: main, 13.4, 12.4
  • Loading branch information
linawolf authored Nov 1, 2024
1 parent c327c9f commit ba50393
Show file tree
Hide file tree
Showing 13 changed files with 62 additions and 56 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,11 @@ The basic extension for rendering content in TYPO3 since TYPO3 v8 is
`fluid_styled_content`. The example shows how
`fluid_styled_content` is set up: It defines a basic content element based
on the content object `FLUIDTEMPLATE` which is able to render html
templates using the `fluid` templating engine. For every content element,
templates using the Fluid templating engine. For every content element,
the basic template, layout and partial parts are defined. As you can see by
looking at the lines starting with `10 =` there is the possibility to
add your own templates by setting the corresponding `constant` (in the
`Constants` section of a TypoScript template):
`Constants` section of a TypoScript record):

.. literalinclude:: _lib.contentElement.typoscript
:caption: Taken from typo3/sysext/fluid_styled_content/Configuration/TypoScript/Helper/ContentElement.typoscript
Expand Down Expand Up @@ -62,6 +62,6 @@ take a look at how the text element is rendered:

The database field `bodytext` from the `tt_content` table (which is
the main text input field for content elements of type `text`) is
available as `{data.bodytext}` in the fluid template. For more
available as `{data.bodytext}` in the Fluid template. For more
information about `fluid_styled_content` see its :doc:`manual
<typo3/cms-fluid-styled-content:Index>`.
2 changes: 1 addition & 1 deletion Documentation/Guide/TypoScriptFunctions/Typolink/Index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ as they will be processed by TYPO3 CMS. This is a prerequisite,
for example, for the anti-spam protection of email addresses.

Please resist the urge to a straight `<a href="...">...</a>` construct
in your templates.
in your TypoScript and Fluid templates.

Basically `typolink` links the specified text according to
the defined parameters. One example:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,5 @@ backend user group or in the TSconfig field of a page. It will then
change the look and behavior of forms in the *backend*.

The *frontend* rendering in contrast is defined by the TypoScript
used in TypoScript templates. This document covers only frontend
used in TypoScript records. This document covers only frontend
rendering.
4 changes: 2 additions & 2 deletions Documentation/Guide/TypoScriptOverview/FirstSteps/Index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
First steps
===========

The basic rendering is defined in the "Setup" field of the main template.
The basic rendering is defined in the "Setup" field of the main TypoScript record.

TypoScript essentially consists of objects, which have certain
properties. Some of these properties can accept other objects, others
Expand All @@ -23,7 +23,7 @@ The :ref:`PAGE <page>` object on the one hand offers numerous named properties
numbered objects (a so-called content array). The names of these
objects only consist of numbers and the objects are sorted
accordingly when they are rendered, from the smallest number to the
largest. The order of the lines in the TypoScript template is
largest. The order of the lines in the TypoScript record is
irrelevant:

.. literalinclude:: _mypage2.typoscript
Expand Down
15 changes: 8 additions & 7 deletions Documentation/Guide/TypoScriptOverview/MainTemplate/Index.rst
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
.. include:: /Includes.rst.txt
.. _guide-main-template:
.. _guide-main-typoscript-record:

=================
The main template
=================
==========================
The main TypoScript record
==========================

The TypoScript code used to define how pages are rendered is
located in the "main" template. In this template a so-called
located in the "main" TypoScript record. In this record a so-called
"rootlevel flag" is set.

.. include:: /Images/AutomaticScreenshots/RootlevelFlag.rst.txt

When the frontend renders a page, TYPO3 CMS searches along the page tree up
to the root page to find a "main" template. Normally, there are
additional templates besides the "main" template.
For now, we will assume we are only using the "main" template.
to the root page to find a "main" TypoScript record. Normally, there are
additional TypoScript records besides the "main" TypoScript record.
For now, we will assume we are only using the "main" TypoScript record.

TypoScript syntax is very straightforward. On the left side, objects
and properties are defined. On the right side are the assigned values.
Expand Down
43 changes: 22 additions & 21 deletions Documentation/Guide/TypoScriptOverview/TheTermTemplate/Index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,47 +2,48 @@

.. _guide-template:

=================
The term template
=================

The term template has a double meaning in TYPO3 CMS. On the one hand,
there is the *HTML template file*, which serves as the skeletal
structure in which the content, provided by the CMS,
will be rendered. On the other hand, there is the *TypoScript template*,
which is created in the template module in the TYPO3 CMS
Backend and can exist on any page.

The :doc:`Sitepackage Tutorial <t3sitepackage:Index>` shows how the two are related
together. This manual is purely about TypoScript templates.
===================
The term "template"
===================

Sometimes the term "template" is used as a synonym for the TypoScript record
or the combined TypoScript configuration from all sources. This has historic
reasons. Until TYPO3 v11 TypoScript could be edited in a backend module
called "Template". In the beginning of TYPO3 sites were build almost
exclusively with TypoScript while it slowly evolved to be mainly a configuration
language.

As a Fluid template is also called "template" the terms took on a double meaning
in TYPO3. With TYPO3 v12 we speak about TypoScript records, TypoScript files
and the complete TypoScript configuration. However you will still find the
outdated term "TypoScript template" or just "template" in places.

.. _guide-troubleshooting:

Troubleshooting
===============

Common mistakes made with TypoScript templates can cause a message like this:
Common mistakes made in the TypoScript configuration can cause a message like this:

.. figure:: /Images/ManualScreenshots/NoTypoScriptTemplateFoundDebuggingOff.png
:alt: Error message "No TypoScript template found! Without debug mode"
:alt: Error message "No TypoScript record found!"

If you turn on the :ref:`debug mode <t3coreapi:troubleshooting-debug-mode>`
you will get more detailed information:

.. figure:: /Images/ManualScreenshots/NoTypoScriptTemplateFound.png
:alt: Error message "No TypoScript template found!"
:alt: Error message "No TypoScript record found!"

`No TypoScript template found`: This warning appears if no template,
`No TypoScript record found!`: This warning appears if no TypoScript record,
with the `root level` flag enabled, is found in the page tree.

.. figure:: /Images/ManualScreenshots/ThePageIsNotConfigured.png
:alt: Error message "The page is not configured!"


`The page is not configured! [type=0][]. This means that there is no TypoScript
`The page is not configured! [type=0][]`. This means that there is no TypoScript
object of type PAGE with typeNum=0 configured.`: This warning appears if the
root level flag of a template in the page tree is enabled (i.e. this template
is used), but no :ref:`PAGE <page>` Object can be found.
TypoScript Configuration of the current page contains no :ref:`page`
definition.

The following TypoScript setup code is enough to remove this warning:

Expand Down
35 changes: 23 additions & 12 deletions Documentation/Guide/UsingFluidStyledContent/Index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,42 @@
Using fluid\_styled\_content
============================

It is worth taking a deeper look at "fluid\_styled\_content". It comes with
more than 600 lines of TypoScript code containing definitions for each type of
It is worth taking a deeper look at the TypoScript of the system extension
:composer:`typo3/cms-fluid-styled-content`. It comes with
more than 900 lines of TypoScript code containing definitions for each type of
content element.

Although it may seem daunting, it is very instructive to review all this code,
as there is much to learn by example. To view the raw code, place yourself on
the root page of your website and move to the **WEB > Template** module. Then
choose the *Template Analyzer* function.
the root page of your website and move to the
:guilabel:`Site Management > TypoScript` module. Then
choose the submodule :guilabel:`Included TypoScript` from the drop-down.

You should see a list of all used TypoScript templates and how they possibly
include one another. All templates are evaluated by TYPO3 CMS from top to
You should see a list of all used TypoScript records and files and how they possibly
include one another. All TypoScript is evaluated by TYPO3 CMS from top to
bottom.

.. include:: /Images/AutomaticScreenshots/TemplateAnalyzerStructure.rst.txt
.. figure:: /Images/ManualScreenshots/IncludedTypoScript.png
:alt: Screenshot of the module Site Management > TypoScript > Included TypoScript

With a click on "EXT:fluid\_styled\_content/static/", you can view the content
of that template (below the hierarchical view), first the constants, then the
setup (scroll down).
Click on the :guilabel:`{ }`, "show code", button to see the code

You will see that "fluid\_styled\_content" adds rendering definitions for all
With a click on the :guilabel:`{ }`, "show code", button, you can view the content
of that TypoScript file.

As the TypoScript is split up in several files you can also use the
:guilabel:`{ + }`, "show resolved code", button to show the code including all
its includes.

You will see that the set `set:typo3/fluid-styled-content` adds rendering
definitions for all
content elements. When rendering special content like file relations or menus
the concept of data processors is used. You can find out more about data
processors in the :doc:`manual of fluid_styled_content
<typo3/cms-fluid-styled-content:Index>`.

HTML purists may find that "fluid\_styled\_content" generates too much markup.
HTML purists may find that the set `set:typo3/fluid-styled-content` generates
too much markup.

It is perfectly possible to trim down this setup or write one's own entirely.
However this is not recommended for beginners.
2 changes: 1 addition & 1 deletion Documentation/Guide/UsingStdWrap/HeedTheOrder/Index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Heed the order
The single most important thing to know about `stdWrap` is that all
properties are parsed/executed exactly in the order in which they appear in the
:ref:`TypoScript Reference <stdwrap>`, no matter in which order you
have set them in your TypoScript template.
have set them in your TypoScript record.

Let's consider this example:

Expand Down
2 changes: 1 addition & 1 deletion Documentation/Guide/UsingStdWrap/TheDataType/Index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,5 @@ arbitrarily, until the anticipated result is finally achieved by accident.

The :ref:`TypoScript reference <stdWrap>` is very clear about
which properties exist and what their data type is, so please refer
to that essential resource while developing your templates.
to that essential resource while writing your TypoScript configuration.

Binary file not shown.

This file was deleted.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit ba50393

Please sign in to comment.