TYPO3 Fluid: Partials vs Sections for Reusable Markup

The problem: the same card markup in five templates

You maintain a TYPO3 site package with several page templates. Each template renders a "feature card" block—an image, a heading, and a link. The markup is copied into Template A, Template B, and Template C. When marketing asks to add a badge icon, you edit three files and still miss one. The practical question is whether to extract the card into a Fluid partial or define it as a section inside each template.

Thesis

Use Fluid partials when the same markup appears across multiple templates or extensions. Use sections when a block is rendered more than once within a single template or passed to a layout. Partials live in separate files and are referenced by path; sections are named blocks inside the current template. Choosing the wrong one creates either file sprawl or duplicated edits.

1. Fluid partials: reusable files

A partial is a standalone Fluid file, typically stored in Resources/Private/Partials/. You include it with <f:render partial="FeatureCard" arguments="{...}" />. TYPO3 resolves the file relative to the configured partial root path. Because the file is separate, any template in the same site package can render it, and a change to the partial updates every consumer.

2. Fluid sections: named blocks in one template

A section is defined inside a template with <f:section name="FeatureCard">...</f:section> and rendered with <f:render section="FeatureCard" />. Sections are useful inside layouts, where a page template fills a named block that the wrapper renders. They are not visible to other templates unless copied.

3. Worked example: a shared feature card

Assume a site package extension my_site running on TYPO3 12 LTS or later. Fluid resolves partials from Resources/Private/Partials/ by default.

3.1 Create the partial

<!-- Resources/Private/Partials/FeatureCard.html -->
<div class="card">
  <a href="{link}">
    <img src="{image}" alt="{title}">
    <h3>{title}</h3>
  </a>
</div>

3.2 Render it from two templates

<!-- Template A -->
<f:render partial="FeatureCard" arguments="{link: '/services', image: 'EXT:my_site/Resources/Public/Image/service.svg', title: 'Consulting'}" />

<!-- Template B -->
<f:render partial="FeatureCard" arguments="{link: '/contact', image: 'EXT:my_site/Resources/Public/Image/contact.svg', title: 'Get in touch'}" />

Fluid automatically escapes variables such as {title}, so untrusted editor input is rendered as text rather than executable HTML unless you explicitly use f:format.raw.

3.3 Verify the output

Open a page that uses Template A and inspect the page source. You should see the card markup with the escaped title text. Change class="card" to class="card card--featured" in the partial, reload the page, and confirm both templates render the new class without editing either template.

4. Trade-offs and limitations

• File management: Partials add files to the extension. A team must agree on naming and location, or partials become hard to find.
• Scope: Sections cannot be shared across templates without duplication. Use them only within one template or layout.
• Caching: TYPO3 compiles Fluid templates to PHP and caches the result. Editing a partial does not always invalidate every cache entry that includes it. Flush the system cache after changing shared partials.
• Debugging: A missing partial throws a rendering exception; a missing section usually fails more quietly with an empty output, depending on context.

5. Cache flush command

Run this from the TYPO3 project root:

./vendor/bin/typo3 cache:flush

Required permissions: the CLI user must have read/write access to var/cache/ or the configured cache path. Expected check: after flushing, reload the page and verify the updated partial markup appears. Risk: flushing clears all cache groups, which can briefly increase database load on a busy site.

Actionable closing

1. Extract repeated markup into Resources/Private/Partials/.
2. Pass data with arguments, not by relying on variables leaked from the parent template.
3. Reserve f:section for layout placeholders and repeated blocks inside one template.
4. Flush the cache after editing any shared partial.
5. Inspect page source to confirm automatic escaping is working as expected.