Decoupling Presentation in TYPO3: Custom Content Elements with Fluid

The Struggle with Rigid Content Layouts

A common frustration in TYPO3 development is the "all-or-nothing" approach to content. Standard text elements often force editors into a rigid structure, while developers find themselves fighting with legacy TSconfig or complex PHP renderers to achieve a specific design requirement—like a highlighted feature box or a custom call-to-action section.

The solution is to implement custom content elements using Fluid Styled Content. By separating the backend data structure (TCA) from the frontend presentation (Fluid), you can give editors specific fields to fill while maintaining total control over the HTML output without touching the TYPO3 core.

Defining the Data Structure via TCA

Before a template can render data, the backend must know what data to collect. This is handled by the Table Configuration Array (TCA), which defines the fields, validation, and UI of the content element in the Page module.

To avoid update conflicts, never modify core files. Instead, use a site package to override the tt_content table. You will typically define your custom element in TCA/Overrides/tt_content.php. This allows you to add custom fields—such as a specific color picker or a reference to another page—that only appear when your specific content type is selected.

Mapping Backend Input to Fluid Templates

Once the TCA is defined, TYPO3 maps the database columns from the tt_content table directly to variables in a Fluid template. Fluid is a template engine that uses tags (like <f:if>) to handle logic, keeping PHP out of your HTML.

The Fluid Styled Content extension looks for templates in a specific directory structure within your site package. By creating a template file that matches your custom element's name, you tell TYPO3: "When this element is used, ignore the default text layout and use this specific HTML structure instead."

Worked Example: Creating a "Feature Highlight" Element

Suppose you need a content element that consists of a short title, a description, and a custom background color.

Step 1: TCA Override

Run this in your site package at TCA/Overrides/tt_content.php. This adds a custom field tx_myext_bg_color to the content element.

 'Background Color',
    'config' => [
        'type' => 'select',
        'renderType' => 'select',
        'items' => [
            ['value' => 'blue', 'label' => 'Blue'],
            ['value' => 'green', 'label' => 'Green'],
            ['value' => 'yellow', 'label' => 'Yellow'],
        ],
    ],
];

// Add the field to the 'form' tab of your custom element
$GLOBALS['TCA']['tt_content']['types']['my_feature_element'] = [
    'value' => 'Feature Highlight',
    'setValue' => 'piContent',
    'icon' => 'highlight',
];

Step 2: The Fluid Template

Create the template file in Resources/Private/Templates/ContentElement/FeatureHighlight.html.

<div class="feature-box feature-box--{tx_myext_bg_color}">
    <f:if condition="{header}">
        <h3 class="feature-title">{header}</h3>
    </f:if>
    
    <f:if condition="{bodytext}">
        <div class="feature-body">
            {bodytext} </div>
    </f:if>
</div>

Verification

1. Clear all caches in the TYPO3 Install Tool or Maintenance module.
2. Go to the Page module and create a new content element.
3. Select "Feature Highlight" from the dropdown.
4. Enter a title and select a color, then save and view the frontend.

Trade-offs and Performance

While Fluid is powerful, it is not without limits. Complex logic—such as heavy loops or deep nested conditionals—can slow down page rendering because Fluid is interpreted at runtime. For highly complex data processing, it is more efficient to write a custom ViewHelper in PHP to handle the logic and simply pass the final result to the Fluid template.

Additionally, be cautious when changing TCA field types in a live environment. If you change a field from a select to a text field, existing data may not map correctly, potentially leading to empty fields in the frontend.

Actionable Summary

To implement custom elements effectively: use TCA overrides in a site package for data definition, leverage Fluid for HTML structure, and keep logic simple. If the template becomes too complex, move the logic into a PHP ViewHelper to maintain performance.