Add your own data records to the breadcrumb navigation
- September 10, 2026 - TYPO3, Extbase & Fluid - 2 minute read
By default, breadcrumb navigation in TYPO3 is based on the page structure. However, in the case of dynamic content provided by extensions, this structure is not always sufficient. For example, detail pages for data records do not belong directly to the root line and are therefore not automatically displayed as the final entry in the breadcrumb navigation.
This behaviour can be specifically extended using a custom DataProcessor. The processor can retrieve additional data from the current request, load a suitable record from the database and then append it to the existing breadcrumb entries.
This article provides a step-by-step guide to implementing such a custom DataProcessor in a TYPO3 extension. The TYPO3 ConnectionPool is used to retrieve the required record directly from the database and dynamically integrate its title into the breadcrumb navigation. I’ve kept things a bit simpler in this case, so I’m using the ConnectionPool for the database query in this example; however, any repository query can be integrated, as is normally the case with TYPO3 extensions.
To create your own DataProcessor, you first need to create a new PHP class within the Sitepackage extension. To do this, create a separate subfolder called ‘DataProcessing’ in the ‘Classes’ folder. This file does not necessarily have to be created in the Sitepackage; it can also be created directly within your own extension. However, we’ll use a Sitepackage as an example here.
The required structure will then look like this:
packages/
└── sitepackage/
└── Classes/
└── DataProcessing/
└── BlogBreadcrumbProcessor.php
The file BlogBreadcrumbProcessor.php is the actual DataProcessor. This is where the logic will later be implemented to determine the current data record and pass its title to the breadcrumb navigation.
In addition, the DataProcessor is subsequently integrated into the sitepackage’s TypoScript. No further PHP file needs to be created for this. The page’s existing TypoScript configuration is simply extended to include a call to the new processor.
The content of the DataProcessor could, for example, look as follows:
<?php
declare(strict_types=1);
namespace Vendor\Extension\DataProcessing;
use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;
use TYPO3\CMS\Frontend\ContentObject\DataProcessorInterface;
class BlogBreadcrumbProcessor implements DataProcessorInterface
{
public function process(
ContentObjectRenderer $cObj,
array $contentObjectConfiguration,
array $processorConfiguration,
array $processedData
): array {
$request = $GLOBALS['TYPO3_REQUEST'];
$queryParams = $request->getQueryParams();
$postUid = (int) (
$queryParams['tx_t3extblog_blogsystem']['post'] ?? 0;
);
if ($postUid <= 0) {
return $processedData;
}
$connection = GeneralUtility::makeInstance(
ConnectionPool::class
)->getConnectionForTable(
'tx_t3blog_post'
);
$queryBuilder = $connection->createQueryBuilder();
$post = $queryBuilder
->select('uid', 'title')
->from('tx_t3blog_post')
->where(
$queryBuilder->expr()->eq(
'uid',
$queryBuilder->createNamedParameter(
$postUid,
Connection::PARAM_INT
)
)
)
->executeQuery()
->fetchAssociative();
if (!$post) {
return $processedData;
}
$menuName = $processorConfiguration['addToMenus'] ?? 'breadcrumb';
if (
!isset($processedData[$menuName])
|| !is_array($processedData[$menuName])
) {
return $processedData;
}
$processedData[$menuName][] = [
'title' => $post['title'],
'link' => '',
'active' => true,
'current' => true,
];
return $processedData;
}
}The newly created PHP class forms the actual DataProcessor. It implements the TYPO3 interface DataProcessorInterface and thus provides the process() method. This method is subsequently called by TYPO3 and receives, amongst other things, the data that has already been processed, to which the additional breadcrumb entry is then added.
In the example, the current query is first evaluated to determine the UID of the desired record. However, in a different, custom-developed extension, this parameter may have a different name or be passed in a different location. The query parameters must therefore be adapted to the respective extension. It is essential that the DataProcessor knows the UID of the current record.
A database connection to the relevant table is then established via the TYPO3 ConnectionPool. The table name must also be adapted if using a custom extension. The QueryBuilder is used to retrieve the record based on its UID, and its title is then appended to the existing breadcrumb array. In this way, the principle can be applied independently of any specific extension: identify the data record, load the database entry and add the desired value – for example, the title – to the breadcrumb navigation.
The custom DataProcessor is then integrated into the rendering process via TypoScript. First, the menu DataProcessor is used to generate the standard breadcrumb navigation from the rootline and make it available under the name ‘breadcrumb ’. The custom DataProcessor, which is then called, can thus access this existing breadcrumb data and extend it.
The line 451 = Vendor\Extension\DataProcessing\AddRecordToBreadcrumbProcessor calls the previously created PHP class as a DataProcessor. The namespace and class name must be adapted to your own extension. The line ` addToMenus = breadcrumb ` also specifies which processed data array is to be extended. In this case, it is the previously generated ` breadcrumb` array.
The order of the DataProcessors is important here: first, the root line is generated as a breadcrumb; then your own processor is executed and adds the additional record. This ultimately results in a breadcrumb navigation that contains both the normal pages of the root line and the current record of the extension.
Services.yaml
If you would prefer to register the DataProcessor as a separate alias instead, the Configuration/Services.yaml file might look like this, for example:
services:
Vendor\Extension\DataProcessing\AddRecordToBreadcrumbProcessor:
tags:
- name: frontend.data.processor
identifier: add-record-to-breadcrumbThe Services.yaml file is used to register your own DataProcessor as a TYPO3 service. This allows you to assign a unique identifier to the PHP class, which is then used to reference the DataProcessor in TypoScript. In the example, this identifier is add-record-to-breadcrumb.
The actual PHP class is specified under `services:` with its full namespace. The `frontend.data.processor` tag tells TYPO3 that this is a custom DataProcessor for the frontend. The `identifier` value then defines the name under which the processor can be used in TypoScript.
However, for the example shown here, the Services.yaml file is not strictly necessary. TYPO3 can also call a DataProcessor directly via its full class name in TypoScript. Registration via `Services.yaml` is particularly useful if the processor is to be given its own, descriptive identifier and integrated neatly as a TYPO3 service.
This completes the integration of your own DataProcessor into TypoScript. The existing breadcrumb navigation is first generated from the root line as usual and then extended by your own processor to include the current data record.
The major advantage of this solution is that the actual logic remains fully encapsulated within the PHP class. In TypoScript, you simply specify when the DataProcessor is to be executed and which data array it should process. This keeps the configuration clear and allows the processor to be reused for other records or breadcrumb structures if required.
Which parameters are required to determine the current data record and from which database table it is loaded depends on the specific extension. It is precisely these two points that must be adapted accordingly when used within your own extension.
0 comments