Architecture overview 

The extension does not call rek.ai APIs from PHP. Instead, TYPO3 outputs HTML <div> elements with data-* attributes, and the rek.ai JavaScript client reads those attributes at runtime to render personalized content.

Feature overview 

• Middleware-based script embedding in frontend responses
• Consent mode support (data-useconsent attribute)
• Optional autocomplete initialization for a configurable CSS selector
• Content element Rek.ai Recommendations (rekai_recommendations)
• Content element Rek.ai Q&A (rekai_qna)
• Test mode with project ID and secret key for sandbox environments

Compatibility 

• TYPO3: 12.4 LTS, 13.4 LTS, 14.x
• PHP: 8.1 or higher

Requirements 

• TYPO3 12.4 LTS, 13.4 LTS, or 14.x
• PHP 8.1 or higher
• A rek.ai account with a project and script URL

Install via Composer 

composer require pluswerk/rekai

Include TypoScript 

The extension ships TypoScript that must be included in your site template.

1. Open Site Management > Templates
2. Edit the root template of your site
3. In Includes, add Rek.ai to the list of included static templates

Alternatively, if your setup uses Site Sets (TYPO3 13+), include the extension TypoScript via your site's config.yaml:

dependencies:
  - pluswerk/rekai

Activate the extension 

In non-Composer setups, activate the extension manually:

1. Open Admin Tools > Extensions
2. Find rekai and activate it
3. Flush all caches

Configure the extension 

After installation, open Admin Tools > Settings > Extension Configuration > rekai and at minimum:

• Set Enabled to 1
• Enter the Embed Code URL from your rek.ai dashboard

See Configuration for all available settings.

Extension settings 

All global settings are managed in:

Admin Tools > Settings > Extension Configuration > rekai

Content element FlexForm settings 

Each content element exposes additional settings through a FlexForm panel visible in the backend. See Editor Guide for field descriptions.

Validation behaviour 

If the extension is enabled but embedCode is not a valid HTTPS URL, the rek.ai script is silently not injected. No error is thrown.

Adding a content element 

Both rek.ai content elements are available in the new content element wizard under the rek.ai group:

• Rek.ai Recommendations — displays personalized page recommendations
• Rek.ai Q&A — displays context-aware questions and answers

Standard TYPO3 header fields (header, subheader, header layout) are available on each element and rendered by your site template in the standard TYPO3 way.

Rek.ai Recommendations 

Rek.ai Q&A 

Architecture overview 

The extension has three independent parts:

1. Middleware — injects the rek.ai script tag into every frontend response
2. Controllers — produce <div data-*> placeholder markup for the content elements
3. TypoScript / Fluid — integrates the content elements into lib.contentElement

Middleware 

Pluswerk\Rekai\Middleware\RekaiScriptMiddleware runs in the frontend middleware stack (after prepare-tsfe-rendering, before output-compression) and uses TYPO3's AssetCollector to inject:

• the external rek.ai script from embedCode
• an optional data-useconsent="true" attribute when consent mode is active
• an optional inline autocomplete bootstrap script
• window.rek_blocksaveview = true; for backend users and in test mode

Controllers 

RecommendationsController::showAction() and QnaController::showAction() both inherit from AbstractRekaiController. They build a <div> element with the rek.ai data-* attributes derived from the content element's FlexForm settings and the global extension configuration, then assign it to the Fluid template as {divHtml}.

The controllers do not perform any HTTP calls to rek.ai. All data fetching happens in the visitor's browser via the injected JavaScript.

Templates 

Content element integration uses the lib.contentElement FLUIDTEMPLATE mechanism. Two templates are registered under a dedicated template root path:

• Resources/Private/Templates/Content/RekaiRecommendations.fluid.html
• Resources/Private/Templates/Content/RekaiQna.fluid.html

These templates use <f:layout name="Default"/> and define only a Main section, delegating header rendering to the standard TYPO3 Default layout from EXT:fluid_styled_content.

The plugin action templates (consumed by Extbase) are separate:

• Resources/Private/Templates/Recommendations/Show.html
• Resources/Private/Templates/Qna/Show.html

These output only {divHtml} — the raw <div> placeholder.

TypoScript 

Configuration/TypoScript/setup.typoscript adds the content template root path to lib.contentElement:

lib.contentElement {
    templateRootPaths.20 = EXT:rekai/Resources/Private/Templates/Content/
}

The templateName mapping (RekaiRecommendations / RekaiQna) is set in ext_localconf.php via ExtensionManagementUtility::addTypoScript() with position defaultContentRendering, ensuring it runs after ExtensionUtility::configurePlugin() and overrides the generic default.

Extension configuration 

Pluswerk\Rekai\Configuration\ExtensionConfigurationService wraps TYPO3\CMS\Core\Configuration\ExtensionConfiguration::get() and provides typed accessor methods for all settings. It is injected via constructor injection (autowired).

Dependency injection 

All classes use TYPO3's standard DI container (Configuration/Services.yaml with autowire: true and autoconfigure: true). No manual service wiring is required.

Testing 

Unit tests cover ExtensionConfigurationService and RekaiScriptMiddleware:

vendor/bin/phpunit --configuration vendor/pluswerk/rekai/phpunit.xml

No output in frontend 

• Verify that Enabled is set to 1 in Admin Tools > Settings > Extension Configuration > rekai.
• Verify that Embed Code URL is a valid https:// URL.
• Flush all TYPO3 caches.
• Check the browser developer tools network tab to confirm the rek.ai script is loaded without errors.

Header not rendered 

The extension registers its content elements using TYPO3's standard content element API and the --palette--;;headers palette. Header rendering is handled by your site template's Default layout (from EXT:fluid_styled_content). If your sitepackage overrides lib.contentElement without including the standard layout root path (EXT:fluid_styled_content/Resources/Private/Layouts/), the header may not appear.

Autocomplete not working 

• Verify that autocompleteMode is set to auto or manual.
• Verify that autocompleteSelector matches an input element that exists on the page.
• Confirm the rek.ai script is loaded successfully (no console errors).

TypoScript not loaded 

If the content elements render no output at all, the extension TypoScript may not be included in your site template. See Installation for how to add the static template or Site Set dependency.

Content element not available in wizard 

Flush the TYPO3 backend cache after installation. If the problem persists, verify the extension is active under Admin Tools > Extensions.