You are currently viewing Fluid Styled Content – Next Generation TYPO3 Templating

Fluid Styled Content – Next Generation TYPO3 Templating

Fluid Styled Content (FSC) is the new standard for rendering the standard content elements of TYPO3 in the frontend. It is a replacement for the good old system extension “CSS Styled Content“ (CSC). The goal of FSC is to ease the templating for the frontend. This article shows how to use and customize FSC.

What’s new?

CSC has done the complete rendering via TypoScript since the beginning. As you probably know, it was really a pain to customize the frontend rendering, especially if it is / was not your daily business. In contrary to that FSC comes only with some basic lines of typoscript. The defintion of the frontend rendering takes place in fluid templates.

Furthermore the content elements of CSC „Text“, „Text & Images“ and „Images“ were replaced by a single content element „Text & Media“. An upgrade wizard in the install tool is available, if there is only FSC installed in the TYPO3 instance. Otherwise it is possible to use both in parallel.

The third focus was to integrate not only images to the content element, but also video and audio files and links. That is, why it is called „Text & Media“.

From CSS Styled Content to Fluid Styled Content

As already written there is an upgrade wizard available in the install tool, if CSC is not installed on the system any more. But running the upgrade wizard is only one part of the job. The other part is to refactor the stylesheets and the templating configuration.

The stylesheet refactoring is due, because all default css classes changed. There is a static typoscript to add some css styling to the default rendering, but I doubt that it will fit your needs.

The refactoring of the templating configuration is the other part. The default rendering definitions „styles.content.getLeft“, „styles.content.getRight“ and „styles.content.getBorder“ were removed. There were just a shortcut to colPos 1 – 3. If you use them, you must provide them yourself.

Furthermore there are some fields, which are not shown in the backend and not used in the frontend any more with FSC:

  • Top Margin (field: spaceBefore)
  • Bottom Margin (field: spaceAfter)
  • Indentation and Frames (field: section_frames)
  • Quality and Type (field: image_compression)
  • Effect (field: image_effects)
  • Display as Rows (field:image_noRows)

If the current rendering relies on one or more of these fields, there are two possibilities:

1) Refactor templating and rendering to fit to FSC

In many cases this will work out, if „layout“ and „section_frames“ are not used in at the same time..

2) Create own custom content elements based on FSC and tt_content

If the first possibility does not suffice your needs, custom content elements will be the solution. In one of the next blog posts, I will cover this topic.

Another minor thing is, that the positioning of the header is not working out right of the box.

(Optional) Steps in the Backend

Both system extensions bring their own additions to the content element wizard. Both are loaded per default. The automatic loading can be deactivated in the extension manager. Just uncheck the option “basic.loadContentElementWizardTsConfig (boolean)“ in one or both system extensions „CSS Styled Content“ and „Fluid Styled Content“.

typo3worx_fsc_01_CSC-em-configuration
Extension Manager Configuration

After that it is possible to add it in the page properties on a per page(tree) basis.

Add pageTSconfig on a per page basis
Add pageTSconfig on a per page basis

Be aware that this only effects the „New Content Element Wizard“. The editor can still switch between the different types of content elements, when (s)he edits the content element itself.

A good news at the end of the backend section: The configuration of the backend fields via TCEforms stays the same. You can use the existing configuration for both CSC and FSC. There is no difference in configuring the backend.

Basic Configuration for the Frontend

As already said, CSC and FSC can be used in parallel. It is easy as adding both static typoscripts to your configuration. In order to benefit from FSC, its static typoscript must be included after the typoscript of CSC. Why? At the start of CSC all definition of the „tt_content“ typoscript are deleted with

tt_content >

Whereas FSC leaves the existing typoscript configurations intact and only overwrites those, for which it provides its own configurations. This leads to a situation in the TypoScript Object Browser, where parts of CSC are shown, but not interpreted while rendering the frontend.

Unused TypoScript definitions
Unused TypoScript definitions

The sections „[10]“ and “[20]“ are still shown, but not interpreted any more. In order to generalize it, you can say:

1) Where a content element is defined as a COA, the rendering of CSC is executed
2) Where „lib.fluidContent“ is referenced, the rendering of FSC is executed.

Available defintions of the other rendering type are just ignored.

TypoScript Configuration

FSC comes with two typoscript configurations: „tt_content“ and „lib.fluidContent“. In the section „tt_content“ the default configuration from „lib.fluidContent“ is referenced in each content element. The key „templateName“ defines which fluid template is rendered. The templateName must be the same as the filename of the template.

The central part of „lib.fluidContent“ is the configuration of the various „*RootPaths”. These paths define where templates, layouts and partials reside.

Rootpath defintions
Rootpath defintions

Using numeric keys, multiple paths can be defined. Not every path has to provide the complete set of templating files. TYPO3 searches starting in the path with the highest key number. If the template, partial or layout is not found, the next path is checked. If nothing is found in the custom paths, TYPO3 will use the defaults delivered by the core.

Templates, Partials and Layouts

Templates are the starting point of the rendering defintion. An example is this piece of code:

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
   <f:layout name="HeaderContentFooter" />
   <f:section name="content001">
      <f:comment>
         What you do in this part, is up to you
      </f:comment>
   </f:section>
   <f:section name="content002">
      <f:comment>
         What you do in this part, is up to you
      </f:comment>
   </f:section>
</html>

At the beginning of a template the (optional) layout is defined. The layout tells TYPO3, which overall structure of the content element must be rendered. If a layout is used, the template defines usually at least one section. Multiple sections can be defined in the template. It is important that they must have a unique name.

The layout „HeaderContentFooter.html“  serves as an example. It is used by several templates of FSC.

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
<div id="c{data.uid}">
   <f:render partial="Header" arguments="{_all}" />
   <f:render section="content" />
   <f:render partial="Footer" arguments="{_all}" />
</div>
</html>

The first line is necessary to comply the xml standards. The next line renders the starting div tag of the content element to the browser. The data array contains all values of the current database row of the table “tt_content”.

The third line calls the partial „Header“ and renders its content accordingly. All arguments, which are available in the layout, are passed to the partial. You can use them in the partial for whatever you want to.

Next is the section „content“. It is replaced by the section definition with the identical name of the template file referencing. The layout is closed by another partial „Footer“ which is followed by the closing div and html tag.

A partial is a fluid template, that can be reused at several places. The code and formatting is identical to the templates and layouts. A simple example is the partial “Footer”. It just renders the „link to top“ at the end of a content element. It is available in any content element. The code looks like this:

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" xmlns:ce="http://typo3.org/ns/TYPO3/CMS/FluidStyledContent/ViewHelpers" data-namespace-typo3-fluid="true">
<f:if condition="{data.linkToTop}">
   <p>
      <ce:link.section name="top"><f:translate key="toTop" extensionName="fluid_styled_content" /></ce:link.section>
   </p>
</f:if>
</html>

Probably you are curious, which data is available in the partial / layout / template, you can find it out by using the debug viewhelper. Just add the following line to one of the files … and you will see the all the arrays and values:
<f:debug title="My Debug Statement">{data}</f:debug>
<f:debug title="My Debug Statement">{_all}</f:debug>

The difference between those two that {_all} is a superset of {data}. {_all} contains more information. For example the typoscript settings array is included.

If you have a look in the code, you see many viewhelpers used. To describe them all here is out of the scope of the article. All TYPO3 Fluid Viewhelpers are documented on typo3.org: https://docs.typo3.org/typo3cms/ExtbaseGuide/stable/Fluid/Index.html

Conclusion

Fluid Styled Content (FSC) is a really clean and easy way to do proper future proof templating for TYPO3. Furthermore you gain performance compared to the old CSC templating. If you did not use it already, give it a try!

This Post Has One Comment

Leave a Reply