Custom Content Blocks

When we filled the stage with content we noticed that the content does not look like the content within the original HTMl layout.

This is because the stage does not contain normal content, as provided by Fluid-Styled Content, but a Jumbotron element or a slider.

Note

The extension friendsoftypo3/content-blocks is not an official part of the TYPO3 Core yet. It is also possible to Create a custom content element with TYPO3 Core only.

Install extension Content Blocks

The extension friendsoftypo3/content-blocks is an extension that is not part of the TYPO3 Core but maintained by a group of community members.

There are plans to integrate this extension into the Core, however at the time of writing there are no finite decisions yet.

First install the extension friendsoftypo3/content-blocks :

ddev composer req friendsoftypo3/content-blocks

Set up the extension and delete all caches:

ddev typo3 extension:setup
ddev typo3 cache:flush

The jumbotron Content Block

The site package you generated in step Generate a site package comes with two content elements. We look at the more basic content elements first.

You can now replace the content element in the area "Stage" of start page with one of type "Jumbotron".

Screenshot of the "New Page Content" dialog with the Carousel and Jumbotron as additional features — The new Content Blocks "Jumbotron" and "Carousel"

You can now create a jumbotron with a button and a link.

Directory packages/my_site_package/ContentBlocks/ContentElements contains one directory for each Content Block that can be used as normal Content Elements.

Directory structure of a Content Block

A Content Block consists of a configuration (config.yaml), a template and optionally assets and or language files:

The jumbotron consists of the following files:

packages/my_site_package/ContentBlocks/ContentElements/jumbotron
- assets
  - icon.svg
- language
  - labels.xlf
- templates
  - frontend.html
- config.yaml

The configuration of the jumbotron Content Block

File packages/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml defines what fields should be available for the Content Block in the backend:

packages/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml

name: my-site-package/jumbotron
typeName: my_site_package_jumbotron
group: default
prefixFields: true
prefixType: full
fields:
  -
    identifier: header
    useExistingField: true
  -
    identifier: bodytext
    useExistingField: true
    enableRichtext: true
  -
    identifier: button_text
    type: Text
    default: 'Read more'
    min: 4
    max: 15
  -
    identifier: button_link
    type: Link
    required: true

Each Content Block must have a unique name with a prefix of your choice that should be unique within your project. (Line 1)

It is possible to use fields that are already pre-defined in the TYPO3 Core like header (Line 8) and bodytext (Line 11).

We also newly define two fields, one of type Text (Line 15-19) and one of type Link (Line 21-23). You can find all available types here: Field Types.

The meaning behind the other settings here can be found in the YAML reference of the Content Blocks guide.

The jumbotron template

The frontend template for the Content Block "Jumbotron" is a normal Fluid template. You already used Fluid for the Page templates and to adjust the templates of Fluid-Styled Content elements in chapter Overriding the default templates of content elements.

        packages/my_site_package/ContentBlocks/ContentElements/jumbotron/templates/frontend.html
    

<div class="p-5 mb-4 bg-body-tertiary">
    <div class="container-fluid py-5">
        <h1 class="display-5 fw-bold">{data.header}</h1>
        <p class="col-md-8 fs-4"><f:format.html>{data.bodytext}</f:format.html></p>
        <f:link.typolink class="btn btn-dark btn-lg" parameter="{data.button_link}">{data.button_text}</f:link.typolink>
    </div>
</div>

Line 3: The values of the database entry of the current content element can be found in variable {data}. In this line we render the content of the field header. The field was defined in line 8 of the config.yaml.

Line 4: Here we output the content of field bodytext as this field is a Rich-Text Editor we use the Format.html ViewHelper <f:format.html> to format and sanitize the output.

Line 5: We use the Link.typolink ViewHelper <f:link.typolink> to render a link to the target that was defined in our custom field button_link.

Next steps

The generated site package contains a second, more elaborate example in directory packages/my_site_package/ContentBlocks/ContentElements/carousel.
Learn how to use the Kickstart command to create your own Content Blocks.