Skip to content

Commit 65b2bea

Browse files
s2bs2b
committed
[DOC] Rewrite Fluid introduction chapter
1 parent e6cff4d commit 65b2bea

File tree

1 file changed

+130
-111
lines changed

1 file changed

+130
-111
lines changed

‎Documentation/Concepts/Fluid/Index.rst‎

Lines changed: 130 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -7,159 +7,178 @@
77
Fluid templates
88
===============
99

10-
.. todo: This chapter was moved from the site package tutorial:
11-
Overhaul and improve
12-
1310
.. _quick-introduction-to-fluid:
1411

1512
Quick Introduction to Fluid
1613
===========================
1714

18-
Like many other templating engines, Fluid reads *template files*,
19-
processes them and replaces certain variables and specific tags with dynamic
20-
content. The result is a fully working website with a clean and valid HTML
21-
output. Dynamic elements are automatically updated as required. Navigation
22-
menus are a typical example for this type of content. A menu exists on all
23-
pages across the entire website. Whenever pages are added, deleted or renamed,
24-
the menu items change.
25-
26-
Fluid takes modern templating a step further. By using *ViewHelpers*,
27-
developers can implement complex functionality and therefore extend the
28-
original functionality of Fluid to their heart's content. ViewHelpers are built
29-
in the programming language PHP. Having said that, website integrators or
30-
editors are not required to learn or understand these (this is the
31-
responsibility of a software developer). Integrators only need to **apply**
32-
them -- and this is as easy as adding an HTML tag such as :html:`<image.../>` to an
33-
HTML file.
34-
35-
More than 80 ViewHelpers are shipped with the TYPO3 core already. They enable
36-
integrators and web developers to use translations of variables, generate forms
37-
and dynamic links, resize images, embed other HTML files and even implement
38-
logical functions such as :html:`if ... then ... else ...`. An overview of the
39-
available ViewHelpers and how to apply them can be found in the
40-
:doc:`Fluid ViewHelper reference <t3viewhelper:Index>`.
15+
TYPO3 uses a template engine to generate the necessary HTML
16+
markup for a website. The template engine provides data from
17+
the backend, such as content or menu structures, which can
18+
then be formatted with HTML.
19+
20+
TYPO3's template engine of choice is called Fluid. Fluid's
21+
syntax is inspired by the syntax of HTML or XML documents,
22+
so it should already be familiar for users that already know
23+
HTML.
24+
25+
While Fluid is extendable by PHP developers, knowing any
26+
PHP is not necessary to write templates for TYPO3. However,
27+
Fluid comes with its own syntax rules, which need to be
28+
obeyed when writing templates.
29+
30+
.. _fluid-basics:
31+
32+
Fluid Basics
33+
============
34+
35+
Accessing Variables
36+
-------------------
37+
38+
An integral part of Fluid are variables. This is the data
39+
that is provided by the backend to be used inside your
40+
template. You can access variables like this:
41+
42+
.. code-block:: xml
43+
44+
<h1>{myHeadline}</h1>
45+
46+
47+
If a variable contains subitems, these can be accessed
48+
with the dot syntax:
49+
50+
.. code-block:: xml
51+
52+
<p>{myVariable.mySubItem}</p>
53+
54+
Modifying Variables
55+
-------------------
56+
57+
You can also do some basic math operations:
58+
59+
.. code-block:: xml
60+
61+
{myNumber + 5}
62+
63+
64+
If you need to modify the provided data even more, you
65+
can use so-called ViewHelpers. These are functions that
66+
take some input values, perform operations on those
67+
values and then output the result. The following example
68+
converts a variable to uppercase:
69+
70+
.. code-block:: xml
71+
72+
<f:format.case mode="upper">{myText}</f:format.case>
73+
74+
If you want to perform multiple operations on one variable
75+
or if your templates become more complex, you might also
76+
want to use :ref:`Fluid's inline notation <t3coreapi:fluid-inline-notation>`.
77+
78+
Using Control Structures
79+
------------------------
80+
81+
ViewHelpers are also used for so-called control structures.
82+
If you want to add a condition to your template, you can
83+
use the :ref:`If ViewHelper <f:if> <t3viewhelper:typo3fluid-fluid-if>`:
84+
85+
.. code-block:: xml
86+
87+
<f:if condition="{myVariable} == 'hello'">
88+
The variable is "hello".
89+
</f:if>
90+
91+
You can also use the :ref:`For ViewHelper <f:for> <t3viewhelper:typo3fluid-fluid-for>` to loop over an
92+
array:
93+
94+
.. code-block:: xml
95+
96+
<ul>
97+
<f:for each="{myList}" as="myItem">
98+
<li>This item is {myItem}.</li>
99+
</f:for>
100+
</ul>
41101
42102
43103
.. _ft-directory-structure:
44104

45105
Directory structure
46106
===================
47107

48-
Fluid requires a specific directory structure to store the template files. If
49-
you are working through this tutorial now, this is a perfect time to create the
50-
first set of folders of the site package extension. The initial directory can
51-
be named :file:`site_package/`, which we assume is located on your local
52-
machine. You can also choose a different name such as "site_example" or
53-
"site_clientname", but this tutorial uses "site_package".
54-
55-
The aforementioned folders for Fluid are all located as sub-directories of a
56-
folder called :file:`Resources/`. Therefore, create the directory structure as
57-
listed below.
108+
Nowadays, Fluid templates in TYPO3 are always part of an
109+
extension. As they are neither PHP code nor configuration files
110+
and don't need to be accessed by end users, they are placed in the
111+
`Resources/Private/` subfolder.
58112

59113
.. directory-tree::
60-
:level: 4
114+
:level: 6
61115
:show-file-icons: true
62116

63-
* EXT:my_sitepackage
117+
* my_sitepackage
64118

65119
* Resources
66120

67121
* Private
68122

69-
* Language
70-
71123
* Templates
72124

73125
* Layouts
74126

127+
* DefaultLayout.html
128+
75129
* Pages
76130

131+
* MyPage.html
132+
77133
* Partials
78134

79-
* Public
135+
* MyPartial.html
80136

81-
* Css
82137

83-
* Images
138+
The displayed folder structure is the convention for the location
139+
of template files in a sitepackage extension.
140+
However, be aware that these paths might vary slightly between
141+
projects or extensions as they can be configured individually.
84142

85-
* JavaScript
143+
.. _fluid-templates-folders-under-private:
86144

87-
* StaticTemplate
145+
Templates, Layouts and Partials
146+
-------------------------------
88147

89-
The :file:`Public/` directory branch is self-explanatory: it contains folders
90-
such as :file:`Css/`, :file:`Images/`, :file:`JavaScript/` and
91-
:file:`StaticTemplate/`. All files in these folders will be delivered to the
92-
user (website visitors) *as they are*. These are **static** files which are not
93-
modified by TYPO3 at all before they are sent to the user.
148+
.. uml::
149+
:caption: Fluid template structure
94150

95-
The :file:`Private/` directory with its two sub-folders :file:`Language/` and
96-
:file:`Templates/` in contrast, requires some explanation.
151+
frame layout as "Templates/Layouts/DefaultLayout.html" {
152+
frame page as "Templates/Pages/MyPage.html" {
153+
rectangle partial [
154+
<b>Templates/Partials/MyPartial.html</b>
155+
(reusable code snippet)
156+
]
157+
}
158+
}
97159

98-
.. _fluid-templates-folders-under-private:
99160

100-
Folders under 'Private/'
101-
------------------------
161+
Fluid knows three different types of template files: **Templates**,
162+
**Layouts** and **Partials**. Templates are always the starting point
163+
and thus are always required, while both Partials and Layouts are optional.
164+
However, these can be very helpful to improve the structure of
165+
your templates and can avoid duplicate code, which makes
166+
maintenance much easier.
167+
168+
**Layouts** are a flexible method to reuse HTML markup that should wrap
169+
around multiple template files. You could for example extract your
170+
header and footer markup to a layout file and only keep the content
171+
in-between in your template. Layouts automatically have access to all
172+
variables defined within the template.
102173

103-
.. _fluid-templates-folders-under-private-templates-layouts:
104-
105-
Templates/Layouts
106-
~~~~~~~~~~~~~~~~~
107-
HTML files, which build the overall *layout* of the website, are stored in the
108-
:file:`Layouts/` folder. Typically this is only **one** construct for all
109-
pages across the entire website. Pages can have different layouts of course,
110-
but *page layouts* do not belong into the :file:`Layouts/` directory. They are
111-
stored in the :file:`Templates/Pages/` directory (see below). In other words, the
112-
:file:`Layouts/` directory should contain the global layout for the entire website
113-
with elements which appear on all pages (e.g. the company logo, navigation
114-
menu, footer area, etc.). This is the skeleton of your website.
115-
116-
.. _fluid-templates-folders-under-private-templates-pages:
117-
118-
Templates/Pages
119-
~~~~~~~~~~~~~~~
120-
The most important fact about HTML files in the :file:`Templates/Pages` directory
121-
has been described above already: this folder contains layouts, which are page-
122-
specific. Due to the fact that a website usually consists of a number of pages
123-
and some pages possibly show a different layout than others (e.g. number of
124-
columns), the :file:`Templates/Pages/` directory may contain one or multiple HTML files.
125-
126-
.. _fluid-templates-folders-under-private-templates-partials:
127-
128-
Templates/Partials
129-
~~~~~~~~~~~~~~~~~~
130-
The directory called :file:`Partials/` may contain small
131-
snippets of HTML template files. "Partials" are similar to templates, but their
132-
purpose is to represent small units, which are perfect to fulfil recurring
133-
tasks. A good example of a partial is a specially styled box with content that
134-
may appear on several pages. If this box would be part of a page layout, it
135-
would be implemented in one or more HTML files inside the :file:`Templates/Pages/`
136-
directory. If an adjustment of the box is required at one point in the future,
137-
this would mean that several template files need to be updated. However, if we
138-
store the HTML code of the box as a small HTML snippet into the :file:`Partials/`
139-
directory, we can include this snippet at several places. An adjustment only
140-
requires an update of the partial and therefore in one file only.
141-
142-
The use of partials is optional, whereas files in the :file:`Layouts/` and
143-
:file:`Templates/Pages` directories are mandatory for a typical sitepackage
144-
extension.
145-
146-
The sitepackage extension described in this tutorial focuses on the
147-
implementation of pages, rather than specific content elements.
148-
149-
.. _fluid-templates-folders-under-private-language:
150-
151-
Language
152-
~~~~~~~~
153-
The directory :file:`Language/` may contain :file:`.xlf` files that are used for
154-
the localization of labels and text strings (frontend as well as backend) by
155-
TYPO3. This topic is not strictly related to the Fluid template engine and is
156-
documented in section
157-
:ref:`Internationalization and Localization <t3coreapi:internationalization>`.
174+
**Partials** are an easy way to abstract and reuse code snippets in
175+
your templates. They don't have access to all template variables, instead
176+
the required variables need to be provided to the partial when it is used.
158177

159178
.. _fluid-in-depth:
160179

161180
Fluid in depth
162-
================
181+
==============
163182

164183
.. card-grid::
165184
:columns: 1

0 commit comments

Comments
 (0)