TYPO3 Content Blocks

The motivation

"Defining ‘Content Elements’ in TYPO3 can be hard and the learning curve is steep. You need to learn PHP, TCA, TypoScript and Fluid and maybe even other languages."

The concept of Content Blocks

“A content block is defined as a small chunk of information, which is connected to a view and then rendered in the TYPO3 frontend.”

The TYPO3 Content Blocks provide an easy way to define and register content blocks (content elements) in TYPO3.

A content block is a composer package of type typo3-contentblock, that ships everything it needs within itself. Each content block represents a CType. Its configuration is reduced and simplified via abstraction and convention. The registration API applies the facade pattern approach to generate TYPO3 specific configuration based on the editor interface definition of a content block.

To ease the learning curve and enable TYPO3 newcomers, beginners, or frontend-only devs  to create content blocks, the definition of the editing interface is done in YAML, which is a widespread configuration language and well known compared to TYPO3's exclusive TCA. Nevertheless, the field types match the TCA field types (refactored version for v12), and work with strong defaults, which reduces the configuration needed.

The even easier way to define a content block is by using the backend module's GUI, that kickstarts an entire content block package, which then can be stored in a version control system (VCS).

The data is stored by extending the tt_content table, following the example set by stable solutions like Bootstrap Package and Mask. Custom tables are automatically created for collection items (inline relations that are not FAL).

The content blocks bring their own rendering definition and extend the TYPO3 AssetCollector with the feature to utilise the file structure the Content Block registration. Thus, assets can be easily accessed both in the frontend and in the backend view, making less effort to create nice backend previews for the editors.

The vision for content types in TYPO3

With our POC of Content Blocks’ approach of having a composer package per type gaining so much positive feedback, we decided to bring our insights into the TYPO3 core, setting the following goals:

  • Empower integrators/ developers with limited TYPO3 knowledge to easily define CTypes
    • via a configuration file
    • via a GUI
  • Have only really necessary fields in tt_content:
    • system fields (e.g. uid, pid, ...)
    • fields defined by integrator
  • Enable integrators to define the backend preview

An integrator shall be able to decide if he/she wants to install

  • only selected (custom) CTypes or
  • a distribution/ meta package (e.g. FSC for all CTypes, minimal, menu, …, bootstrap-package)

To achieve this, we decided to merge our Content Blocks with the popular extension Mask as a TYPO3 system extension by taking the best of both solutions. However, the development of both extensions will continue until at least the next TYPO3 LTS release after the integration of the TYPO3 Content Blocks system extension into the core.

What about Fluid Styled Content?

Fluid Styled Content (FSC) replaced CSS Styled Content as a system extension “back in the old days”. It provided more flexibility for the integrators and a huge set of default content elements for the TYPO3 core. However, the requirements of modern websites and editors have evolved in the meantime, leading to discussions about thinning out FSC or its necessity in the first place (see recent example). One could argue to not install it, if it’s not needed, but that is actually not so simple, because FSC definitions are currently spread around three system extensions:

  • EXT:fluid_styled_content:
    • TypoScript base rendering definition (lib.contentElement)
    • TypoScript rendering definition (per CType)
    • CType templates, layouts and partials
  • EXT:frontend:
    • Necessary tt_content fields (SQL)
    • CType definitions in TCA
    • TypoScript (tt_content = CASE)
  • EXT:backend:
    • Backend preview

In order to enable the integrator to define Content Blocks without additional data of FSC, which in some places (like backend preview or live search) is in fact needed for the backend, FSC will need to become optional for real, with the long-term goal to be extracted from core to FriendsOfTYPO3. See epic on forge for more information.

Current State

For the POC of the Content Blocks we created the TYPO3 extension contentblocks_reg_api with a repository on GitHub. It’s current major version:

  • stores data by extending tt_content
  • features a custom composer installer
  • has a basic validation of the required content block package
  • has a simple GUI for creating content blocks
  • is compatible with PHP 7.2 to 8.0 and both TYPO3 10.4 LTS and 11.5 LTS
  • is fully tested with a multi-language setup and workspaces
  • supports both composer and non-composer mode
  • has a documentation in RST-format rendered by the TYPO3 documentation  interceptor

The extension features two installation methods: development with ddev, and the usual composer installation to just use the API for your own content blocks in a project.

It also brings a number of example content blocks which are located in the “Build/packages” folder.

However, there are differences to the planned version as core extension:

  • The folder structure is src/dist instead of Resources/Private and Resources/Public
  • The fields are Symfony-based and mapped to TCA

A compatibility release for TYPO3 v12 will depend on our progress with the core extension.

Help wanted!

You can help us with the following topics:

  • Refactoring the Content Blocks Registration API as system extension
  • Rebuilding the GUI of Mask form VueJS to LitElement for the Content Blocks
  • Extracting FSC from EXT:frontend and EXT:backend

Get involved!

On Monday 20:00 CET every 1st and 3rd week of the month on Slack: