Basics (Mixins)

Basics, also known as partials or mixins, are used to have a pre-defined set of fields that can be used to better organize your config.yaml file and to reduce redundancy by sharing them between multiple Content Blocks.

Note

It is important to understand that Basics are a very simple "search & replace" kind of mechanic. Once included in your Content Block they act like they were defined there directly. This also means that it is normally required to re-define the label in every Content Block. Hence it is recommended to reference labels with the full LLL:EXT path.

Warning

Be cautious when using Basics in multiple Content Blocks with prefixing enabled. This may lead to the database schema creating one new column for each included field. It is recommended to either use fixed prefixes with prefixType: vendor or to disable the prefix for each field in the Basic with prefixField: false.

There are two different ways of using Basics.

Basics as additional fields

The first way of using Basics is to have them added after the fields array of your Content Block. This is useful if you want to have a set of fields that are always available for your Content Block.

This is an example on how to add the classic Fluid Styled Content Appearance Tab and the additional Links palette.

EXT:your_extension/ContentBlocks/ContentElements/basics/config.yaml

name: example/basics
basics:
    - TYPO3/Appearance
    - TYPO3/Links

You can add as many Basics as you need. Note, that all Basics are simply concatenated onto each other. Be careful, not to create an invalid state by gluing incompatible Basics together.

Basics as field type

The second way is to use Basics directly in the fields array. This can be done by using the according Basic identifier and the type Basic.

EXT:your_extension/ContentBlocks/ContentElements/basics/config.yaml

name: example/basics
fields:
    - identifier: TYPO3/Header
      type: Basic

Note

It's not possible to override Basics once they are included as a field type, because they can contain multiple fields, palettes or tabs. If a use case arises, where you need a new "base field", then you probably want to create a new custom field type. This requires PHP code, however.

Pre-defined Basics

List of the standard Basics shipped with Content Blocks. Feel free to copy them into your own project and adjust them as you need.

TYPO3/Header
TYPO3/Appearance
TYPO3/Links
TYPO3/Categories

Define own Basics

You can define your own Basics by placing one or more YAML files into ContentBlocks/Basics. The name of the YAML file can be chosen freely. It is also possible to create sub-folders in order to structure your Basics.

Example on how to create a single Basic:

EXT:your_extension/ContentBlocks/Basics/YourBasic.yaml

identifier: Vendor/YourBasic
fields:
  - identifier: a_basic_field
    type: Text
    label: LLL:EXT:sitepackage/Resources/Private/Language/locallang.xlf:a_basic_field

The fields part is exactly the same as in the config.yaml. Here you can define a Tab, a Palette or simply a set of fields.

The most practical way to use Basics is to use pre-defined tabs as the global basics option, so they are always added at the end. The field type Basic is used best as a palette. There you can define a set of fields, which you always need e.g. various header fields.

Tip

Unlike Content Block names, it is not mandatory to provide a vendor name for your Basic identifier. However, it is recommended to avoid using too generic names to avoid conflicts.

Nested Basics

It is also possible to nest Basics. So if Basic A refers to Basic B in the fields list, then this will be resolved, too. Be careful to not create an infinite loop by circular or self-references. This will be detected automatically, if a high nesting level is reached.

EXT:your_extension/ContentBlocks/Basics/YourBasic.yaml

identifier: Vendor/YourBasic
fields:
  - identifier: a_basic_field
    type: Text
    label: LLL:EXT:sitepackage/Resources/Private/Language/locallang.xlf:a_basic_field
  - identifier: Vendor/AnotherBasic
    type: Basic