Checkpoint: headless JSON architecture documented + cleanup (Stufe 1+2)

Restore point before Stufe 3 (central resolver-service refactoring).

Includes this session's work:
- Success Story (usecase) rebuild: new fields/tabs, UsecaseSerializer,
  thin List/Show renderers, MM relations, inline content elements.
- vitec_columns content block (two-column layout with per-item content)
  incl. unified header section; special-cased JSON resolution.
- Container per-column flex (items[].config align/justify) + gap on parent.
- Unified header section across CEs/plugins/containers; header fields in JSON.
- ISO-style architecture spec: Documentation/Headless-JSON-Architecture.md.
- Cleanup: removed local scratch + verified .bak backups.
- Fixes: B-6 (undefined thumbnail variable in Downloadcardcollection image
  resolver), B-7 (unsatisfiable legacy CType OR branch in Downloadcard/Datasheets).

Rollback: git reset --hard snapshot-2026-07-09-pre-stufe3

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/vitec/Classes/Controller/EventController.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Evomedien\Vitec\Controller;
+
+use Evomedien\Vitec\Domain\Repository\EventRepository;
+use Psr\Http\Message\ResponseInterface;
+use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
+
+/**
+ * This file is part of the "VITEC" Extension for TYPO3 CMS.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * (c) 2026
+ */
+
+/**
+ * EventController — Extbase registration target for the Eventlist plugin.
+ * In headless mode the JSON output is produced by EventlistJsonRenderer,
+ * not by this controller.
+ */
+class EventController extends ActionController
+{
+    protected EventRepository $eventRepository;
+
+    public function __construct(EventRepository $eventRepository)
+    {
+        $this->eventRepository = $eventRepository;
+    }
+
+    public function listAction(): ResponseInterface
+    {
+        $this->view->assign('events', $this->eventRepository->findUpcoming());
+        return $this->htmlResponse();
+    }
+}

packages/vitec/Classes/DataProcessing/ContainerChildrenProcessor.php

@@ -12,6 +12,8 @@ use Evomedien\Vitec\UserFunc\SolutionShowJsonRenderer;
 use Evomedien\Vitec\UserFunc\DownloadcardJsonRenderer;
 use Evomedien\Vitec\UserFunc\DownloadcardcollectionJsonRenderer;
 use Evomedien\Vitec\UserFunc\DatasheetsJsonRenderer;
+use Evomedien\Vitec\UserFunc\EventlistJsonRenderer;
+use Evomedien\Vitec\UserFunc\NewsJsonRenderer;
 use TYPO3\CMS\Core\Database\Connection;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
@@ -20,9 +22,13 @@ use TYPO3\CMS\Frontend\ContentObject\DataProcessorInterface;
 
 /**
  * Collect container children grouped by colPos and emit a lean, transport-
- * ready structure. Each child is normalised to:
- *   { id, type, colPos, sorting, appearance, data }
- * `data` only contains non-empty content-relevant fields.
+ * ready structure. Each column is normalised to:
+ *   { config: { colPos, align, justify }, contentElements: [ { id, type, … } ] }
+ * `align`/`justify` are the PARENT container's per-column flex settings
+ * (tx_vitec_col{N}_align/justify) and therefore apply to ALL children of that
+ * column. Each child is normalised to { id, type, colPos, sorting, appearance,
+ * data }, where `data` only contains non-empty content-relevant fields —
+ * container-level fields (gap, col flex) are never leaked to children.
  *
  * VITEC list-plugins nested as container children (productlist, productshow,
  * usecaselist, usecaseshow) are resolved to the SAME JSON the top-level
@@ -59,6 +65,30 @@ final class ContainerChildrenProcessor implements DataProcessorInterface
         'uploads_description', 'uploads_type',
     ];
 
+    /**
+     * Container-level fields — they belong on the parent container (grid gap
+     * and per-column flex) and must never appear in a child's `data`.
+     */
+    private const CONTAINER_FIELDS = [
+        'tx_vitec_gap',
+        'tx_vitec_col1_align', 'tx_vitec_col1_justify',
+        'tx_vitec_col2_align', 'tx_vitec_col2_justify',
+        'tx_vitec_col3_align', 'tx_vitec_col3_justify',
+        'tx_vitec_col4_align', 'tx_vitec_col4_justify',
+    ];
+
+    /**
+     * Per container CType: colPos value => 1-based column number. Used to pick
+     * the parent's tx_vitec_col{N}_align/justify for each rendered column.
+     */
+    private const COLPOS_TO_COLUMN = [
+        'vitec_cols_50_50'       => [211 => 1, 212 => 2],
+        'vitec_cols_33_66'       => [251 => 1, 252 => 2],
+        'vitec_cols_66_33'       => [241 => 1, 242 => 2],
+        'vitec_cols_33_33_33'    => [221 => 1, 222 => 2, 223 => 3],
+        'vitec_cols_25_25_25_25' => [231 => 1, 232 => 2, 233 => 3, 234 => 4],
+    ];
+
     /** Fields whose 0/empty value is still meaningful. */
     private const KEEP_IF_ZERO = [
         'header_layout',
@@ -80,6 +110,16 @@ final class ContainerChildrenProcessor implements DataProcessorInterface
         'vitec_downloadcard' => [DownloadcardJsonRenderer::class, 'downloadcard'],
         'vitec_downloadcardcollection' => [DownloadcardcollectionJsonRenderer::class, 'downloadcardcollection'],
         'vitec_datasheets' => [DatasheetsJsonRenderer::class, 'datasheets'],
+        'vitec_eventlist' => [EventlistJsonRenderer::class, 'eventlist'],
+        'news_pi1' => [NewsJsonRenderer::class, 'news'],
+        'news_newsliststicky' => [NewsJsonRenderer::class, 'news'],
+        'news_newsselectedlist' => [NewsJsonRenderer::class, 'news'],
+        'news_newsdetail' => [NewsJsonRenderer::class, 'news'],
+        'news_newsdatemenu' => [NewsJsonRenderer::class, 'news'],
+        'news_categorylist' => [NewsJsonRenderer::class, 'news'],
+        'news_newssearchform' => [NewsJsonRenderer::class, 'news'],
+        'news_newssearchresult' => [NewsJsonRenderer::class, 'news'],
+        'news_taglist' => [NewsJsonRenderer::class, 'news'],
     ];
 
     public function process(
@@ -121,10 +161,20 @@ final class ContainerChildrenProcessor implements DataProcessorInterface
             }
             ksort($byColPos);
 
+            // Per-column flex settings come from the parent container record.
+            $parentCType = (string)($cObj->data['CType'] ?? '');
+            $colMap = self::COLPOS_TO_COLUMN[$parentCType] ?? [];
+
             $items = [];
             foreach ($byColPos as $colPos => $contentElements) {
+                $config = ['colPos' => $colPos];
+                $columnNo = $colMap[$colPos] ?? null;
+                if ($columnNo !== null) {
+                    $config['align'] = (string)($cObj->data['tx_vitec_col' . $columnNo . '_align'] ?? 'stretch');
+                    $config['justify'] = (string)($cObj->data['tx_vitec_col' . $columnNo . '_justify'] ?? 'flex-start');
+                }
                 $items[] = [
-                    'config' => ['colPos' => $colPos],
+                    'config' => $config,
                     'contentElements' => $contentElements,
                 ];
             }
@@ -147,6 +197,9 @@ final class ContainerChildrenProcessor implements DataProcessorInterface
             if (in_array($field, self::SYSTEM_FIELDS, true)) {
                 continue;
             }
+            if (in_array($field, self::CONTAINER_FIELDS, true)) {
+                continue;
+            }
             if ($this->isEmpty($value) && !in_array($field, self::KEEP_IF_ZERO, true)) {
                 continue;
             }

packages/vitec/Classes/Domain/Model/Event.php

@@ -0,0 +1,266 @@
+<?php
+
+namespace Evomedien\Vitec\Domain\Model;
+
+use TYPO3\CMS\Extbase\Domain\Model\Category;
+use TYPO3\CMS\Extbase\Domain\Model\FileReference;
+use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
+use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
+
+class Event extends AbstractEntity
+{
+    /** @var string */
+    protected $title = '';
+
+    /** @var string */
+    protected $slug = '';
+
+    /** @var string */
+    protected $teaser = '';
+
+    /** @var string */
+    protected $description = '';
+
+    /** @var \DateTime|null */
+    protected $eventstart;
+
+    /** @var \DateTime|null */
+    protected $eventend;
+
+    /** @var string */
+    protected $venue = '';
+
+    /** @var string */
+    protected $booth = '';
+
+    /** @var string */
+    protected $city = '';
+
+    /** @var string */
+    protected $country = '';
+
+    /** @var string */
+    protected $attendancemode = 'offline';
+
+    /** @var string */
+    protected $eventstatus = 'scheduled';
+
+    /** @var string */
+    protected $eventurl = '';
+
+    /** @var string */
+    protected $meetinglink = '';
+
+    /**
+     * @var \TYPO3\CMS\Extbase\Domain\Model\FileReference|null
+     * @TYPO3\CMS\Extbase\Annotation\ORM\Cascade("remove")
+     */
+    protected $image;
+
+    /** @var bool */
+    protected $hideonwebsite = false;
+
+    /** @var bool */
+    protected $hideonapp = false;
+
+    /**
+     * @var \TYPO3\CMS\Extbase\Persistence\ObjectStorage<\TYPO3\CMS\Extbase\Domain\Model\Category>
+     * @TYPO3\CMS\Extbase\Annotation\ORM\Lazy
+     */
+    protected $categories;
+
+    public function __construct()
+    {
+        $this->categories = new ObjectStorage();
+    }
+
+    public function getTitle(): string
+    {
+        return $this->title;
+    }
+
+    public function setTitle(string $title): void
+    {
+        $this->title = $title;
+    }
+
+    public function getSlug(): string
+    {
+        return $this->slug;
+    }
+
+    public function setSlug(string $slug): void
+    {
+        $this->slug = $slug;
+    }
+
+    public function getTeaser(): string
+    {
+        return $this->teaser;
+    }
+
+    public function setTeaser(string $teaser): void
+    {
+        $this->teaser = $teaser;
+    }
+
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
+    public function setDescription(string $description): void
+    {
+        $this->description = $description;
+    }
+
+    public function getEventstart(): ?\DateTime
+    {
+        return $this->eventstart;
+    }
+
+    public function setEventstart(?\DateTime $eventstart): void
+    {
+        $this->eventstart = $eventstart;
+    }
+
+    public function getEventend(): ?\DateTime
+    {
+        return $this->eventend;
+    }
+
+    public function setEventend(?\DateTime $eventend): void
+    {
+        $this->eventend = $eventend;
+    }
+
+    public function getVenue(): string
+    {
+        return $this->venue;
+    }
+
+    public function setVenue(string $venue): void
+    {
+        $this->venue = $venue;
+    }
+
+    public function getBooth(): string
+    {
+        return $this->booth;
+    }
+
+    public function setBooth(string $booth): void
+    {
+        $this->booth = $booth;
+    }
+
+    public function getCity(): string
+    {
+        return $this->city;
+    }
+
+    public function setCity(string $city): void
+    {
+        $this->city = $city;
+    }
+
+    public function getCountry(): string
+    {
+        return $this->country;
+    }
+
+    public function setCountry(string $country): void
+    {
+        $this->country = $country;
+    }
+
+    public function getAttendancemode(): string
+    {
+        return $this->attendancemode;
+    }
+
+    public function setAttendancemode(string $attendancemode): void
+    {
+        $this->attendancemode = $attendancemode;
+    }
+
+    public function getEventstatus(): string
+    {
+        return $this->eventstatus;
+    }
+
+    public function setEventstatus(string $eventstatus): void
+    {
+        $this->eventstatus = $eventstatus;
+    }
+
+    public function getEventurl(): string
+    {
+        return $this->eventurl;
+    }
+
+    public function setEventurl(string $eventurl): void
+    {
+        $this->eventurl = $eventurl;
+    }
+
+    public function getMeetinglink(): string
+    {
+        return $this->meetinglink;
+    }
+
+    public function setMeetinglink(string $meetinglink): void
+    {
+        $this->meetinglink = $meetinglink;
+    }
+
+    public function getImage(): ?FileReference
+    {
+        return $this->image;
+    }
+
+    public function setImage(?FileReference $image): void
+    {
+        $this->image = $image;
+    }
+
+    public function getHideonwebsite(): bool
+    {
+        return $this->hideonwebsite;
+    }
+
+    public function setHideonwebsite(bool $hideonwebsite): void
+    {
+        $this->hideonwebsite = $hideonwebsite;
+    }
+
+    public function getHideonapp(): bool
+    {
+        return $this->hideonapp;
+    }
+
+    public function setHideonapp(bool $hideonapp): void
+    {
+        $this->hideonapp = $hideonapp;
+    }
+
+    public function addCategory(Category $category): void
+    {
+        $this->categories->attach($category);
+    }
+
+    public function removeCategory(Category $categoryToRemove): void
+    {
+        $this->categories->detach($categoryToRemove);
+    }
+
+    public function getCategories(): ObjectStorage
+    {
+        return $this->categories;
+    }
+
+    public function setCategories(ObjectStorage $categories): void
+    {
+        $this->categories = $categories;
+    }
+}

packages/vitec/Classes/Domain/Repository/EventRepository.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Evomedien\Vitec\Domain\Repository;
+
+use TYPO3\CMS\Extbase\Persistence\QueryInterface;
+use TYPO3\CMS\Extbase\Persistence\QueryResultInterface;
+use TYPO3\CMS\Extbase\Persistence\Repository;
+
+/**
+ * The repository for Event
+ */
+class EventRepository extends Repository
+{
+    protected $defaultOrderings = [
+        'eventstart' => QueryInterface::ORDER_ASCENDING,
+    ];
+
+    /**
+     * All upcoming (or currently running) events, soonest first.
+     * "Upcoming" = event end (or start, when no end is set) is today or later.
+     */
+    public function findUpcoming(): QueryResultInterface
+    {
+        $todayMidnight = strtotime('today');
+
+        $query = $this->createQuery();
+        $query->getQuerySettings()->setRespectStoragePage(false);
+        $query->matching(
+            $query->logicalAnd(
+                $query->equals('hideonwebsite', 0),
+                $query->logicalOr(
+                    $query->greaterThanOrEqual('eventend', $todayMidnight),
+                    $query->logicalAnd(
+                        $query->equals('eventend', 0),
+                        $query->greaterThanOrEqual('eventstart', $todayMidnight)
+                    )
+                )
+            )
+        );
+        return $query->execute();
+    }
+
+    /**
+     * Past events, most recent first.
+     */
+    public function findPast(): QueryResultInterface
+    {
+        $todayMidnight = strtotime('today');
+
+        $query = $this->createQuery();
+        $query->getQuerySettings()->setRespectStoragePage(false);
+        $query->matching(
+            $query->logicalAnd(
+                $query->equals('hideonwebsite', 0),
+                $query->logicalOr(
+                    $query->logicalAnd(
+                        $query->greaterThan('eventend', 0),
+                        $query->lessThan('eventend', $todayMidnight)
+                    ),
+                    $query->logicalAnd(
+                        $query->equals('eventend', 0),
+                        $query->greaterThan('eventstart', 0),
+                        $query->lessThan('eventstart', $todayMidnight)
+                    )
+                )
+            )
+        );
+        $query->setOrderings(['eventstart' => QueryInterface::ORDER_DESCENDING]);
+        return $query->execute();
+    }
+}

packages/vitec/Classes/EventListener/LoadContainerCollapseAssets.php

@@ -0,0 +1,27 @@
+<?php
+declare(strict_types=1);
+
+namespace Evomedien\Vitec\EventListener;
+
+use TYPO3\CMS\Backend\Controller\Event\ModifyPageLayoutContentEvent;
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Core\Page\PageRenderer;
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+
+/**
+ * Loads the container collapse/expand JS + CSS into the Page module.
+ * Pure additive DOM enhancement — see
+ * Resources/Public/JavaScript/container-collapse.js.
+ */
+#[AsEventListener(identifier: 'vitec/load-container-collapse-assets')]
+final class LoadContainerCollapseAssets
+{
+    public function __invoke(ModifyPageLayoutContentEvent $event): void
+    {
+        $pageRenderer = GeneralUtility::makeInstance(PageRenderer::class);
+        $pageRenderer->loadJavaScriptModule('@evomedien/vitec/container-collapse.js');
+        $pageRenderer->addCssFile(
+            'EXT:vitec/Resources/Public/Css/backend-container-collapse.css'
+        );
+    }
+}

packages/vitec/Classes/Service/ContentElementResolver.php

@@ -14,6 +14,8 @@ use Evomedien\Vitec\UserFunc\SolutionShowJsonRenderer;
 use Evomedien\Vitec\UserFunc\DownloadcardJsonRenderer;
 use Evomedien\Vitec\UserFunc\DownloadcardcollectionJsonRenderer;
 use Evomedien\Vitec\UserFunc\DatasheetsJsonRenderer;
+use Evomedien\Vitec\UserFunc\EventlistJsonRenderer;
+use Evomedien\Vitec\UserFunc\NewsJsonRenderer;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
 
@@ -73,6 +75,16 @@ final class ContentElementResolver
         'vitec_downloadcard' => [DownloadcardJsonRenderer::class, 'downloadcard'],
         'vitec_downloadcardcollection' => [DownloadcardcollectionJsonRenderer::class, 'downloadcardcollection'],
         'vitec_datasheets' => [DatasheetsJsonRenderer::class, 'datasheets'],
+        'vitec_eventlist' => [EventlistJsonRenderer::class, 'eventlist'],
+        'news_pi1' => [NewsJsonRenderer::class, 'news'],
+        'news_newsliststicky' => [NewsJsonRenderer::class, 'news'],
+        'news_newsselectedlist' => [NewsJsonRenderer::class, 'news'],
+        'news_newsdetail' => [NewsJsonRenderer::class, 'news'],
+        'news_newsdatemenu' => [NewsJsonRenderer::class, 'news'],
+        'news_categorylist' => [NewsJsonRenderer::class, 'news'],
+        'news_newssearchform' => [NewsJsonRenderer::class, 'news'],
+        'news_newssearchresult' => [NewsJsonRenderer::class, 'news'],
+        'news_taglist' => [NewsJsonRenderer::class, 'news'],
     ];
 
     /**

packages/vitec/Classes/Service/StructuredDataService.php

@@ -305,6 +305,148 @@ final class StructuredDataService
         return $video;
     }
 
+    /**
+     * schema.org FAQPage from a list of question/answer pairs.
+     * Answers may contain RTE HTML — tags are stripped for the JSON-LD text.
+     *
+     * @param list<array{question:string,answer:string}> $items
+     */
+    public function buildFaqPage(array $items, string $base): ?array
+    {
+        $mainEntity = [];
+        foreach ($items as $item) {
+            $question = trim((string)($item['question'] ?? ''));
+            $answer = trim(strip_tags((string)($item['answer'] ?? '')));
+            if ($question === '' || $answer === '') {
+                continue;
+            }
+            $mainEntity[] = [
+                '@type' => 'Question',
+                'name' => $question,
+                'acceptedAnswer' => [
+                    '@type' => 'Answer',
+                    'text' => $answer,
+                ],
+            ];
+        }
+
+        if ($mainEntity === []) {
+            return null;
+        }
+
+        return [
+            '@type' => 'FAQPage',
+            'mainEntity' => $mainEntity,
+        ];
+    }
+
+    /**
+     * schema.org ExhibitionEvent (trade-show) node from a
+     * tx_vitec_domain_model_event row.
+     *
+     * Google rich-result requirements: name, startDate, location.
+     * Recommended extras handled here: endDate, description, image, url,
+     * eventStatus, eventAttendanceMode, organizer.
+     *
+     * @param array<string,mixed> $e        Event DB row
+     * @param list<string>        $imageUrls Absolute or root-relative logo URLs
+     */
+    public function buildEvent(array $e, string $base, array $imageUrls, bool $hasOrganization): ?array
+    {
+        $name = trim((string)($e['title'] ?? ''));
+        $start = (int)($e['eventstart'] ?? 0);
+        if ($name === '' || $start === 0) {
+            return null;
+        }
+
+        $event = [
+            '@type' => 'ExhibitionEvent',
+            'name' => $name,
+            'startDate' => date('Y-m-d', $start),
+        ];
+
+        $end = (int)($e['eventend'] ?? 0);
+        if ($end > 0) {
+            $event['endDate'] = date('Y-m-d', $end);
+        }
+
+        $description = trim(strip_tags((string)($e['description'] ?? '')));
+        if ($description === '') {
+            $description = trim((string)($e['teaser'] ?? ''));
+        }
+        if ($description !== '') {
+            $event['description'] = $description;
+        }
+
+        // Location: Place with venue + city/country, or VirtualLocation for online.
+        $mode = (string)($e['attendancemode'] ?? 'offline');
+        $venue = trim((string)($e['venue'] ?? ''));
+        $city = trim((string)($e['city'] ?? ''));
+        $country = trim((string)($e['country'] ?? ''));
+
+        if ($mode === 'online') {
+            $url = trim((string)($e['eventurl'] ?? ''));
+            if ($url !== '') {
+                $event['location'] = [
+                    '@type' => 'VirtualLocation',
+                    'url' => $this->absUrl($url, $base),
+                ];
+            }
+        } else {
+            $address = array_filter([
+                '@type' => 'PostalAddress',
+                'addressLocality' => $city !== '' ? $city : null,
+                'addressCountry' => $country !== '' ? $country : null,
+            ]);
+            $place = array_filter([
+                '@type' => 'Place',
+                'name' => $venue !== '' ? $venue : ($city !== '' ? $city : null),
+                'address' => count($address) > 1 ? $address : null,
+            ]);
+            if (count($place) > 1) {
+                $event['location'] = $place;
+            }
+        }
+
+        $statusMap = [
+            'scheduled' => 'https://schema.org/EventScheduled',
+            'cancelled' => 'https://schema.org/EventCancelled',
+            'postponed' => 'https://schema.org/EventPostponed',
+            'rescheduled' => 'https://schema.org/EventRescheduled',
+            'movedonline' => 'https://schema.org/EventMovedOnline',
+        ];
+        $event['eventStatus'] = $statusMap[(string)($e['eventstatus'] ?? 'scheduled')] ?? $statusMap['scheduled'];
+
+        $modeMap = [
+            'offline' => 'https://schema.org/OfflineEventAttendanceMode',
+            'online' => 'https://schema.org/OnlineEventAttendanceMode',
+            'mixed' => 'https://schema.org/MixedEventAttendanceMode',
+        ];
+        $event['eventAttendanceMode'] = $modeMap[$mode] ?? $modeMap['offline'];
+
+        $images = [];
+        foreach ($imageUrls as $imageUrl) {
+            $abs = $this->absUrl((string)$imageUrl, $base);
+            if ($abs !== '') {
+                $images[] = $abs;
+            }
+        }
+        if ($images !== []) {
+            $event['image'] = $images;
+        }
+
+        $eventUrl = trim((string)($e['eventurl'] ?? ''));
+        if ($eventUrl !== '' && !str_starts_with($eventUrl, 't3://')) {
+            $event['url'] = $this->absUrl($eventUrl, $base);
+        }
+
+        if ($hasOrganization) {
+            $event['organizer'] = ['@id' => $base . '/#organization'];
+        }
+
+        return $event;
+    }
+
     /**
      * Wrap one or more schema nodes into a single @graph document string.
      *

packages/vitec/Classes/Service/UsecaseSerializer.php

@@ -0,0 +1,530 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Evomedien\Vitec\Service;
+
+use Doctrine\DBAL\ParameterType;
+use TYPO3\CMS\Core\Database\ConnectionPool;
+use TYPO3\CMS\Core\Resource\ResourceFactory;
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+use TYPO3\CMS\Extbase\Service\ImageService;
+
+/**
+ * Serialises a Success Story (tx_vitec_domain_model_usecase) DB row to the
+ * headless JSON shapes consumed by the React frontend.
+ *
+ *   serializeListItem()  -> lean card data for the list plugin
+ *   serializeDetail()    -> full detail (hero, content elements, related, seo)
+ *
+ * Inline content elements are resolved flat; the VITEC Columns content block
+ * (vitec_columns) is resolved specially into { header…, layout, columns:{…} }.
+ *
+ * All relation/FAL resolution lives here so the List/Show UserFunc renderers
+ * stay thin. Every resolver is exception-safe and returns null/[] on failure.
+ */
+final class UsecaseSerializer
+{
+    private const TABLE = 'tx_vitec_domain_model_usecase';
+    private const IMAGE_WIDTHS = [400, 800, 1200, 1600];
+    private const COLUMNS_CTYPE = 'vitec_columns';
+
+    /**
+     * @param array<string,mixed> $u
+     * @return array<string,mixed>
+     */
+    public function serializeListItem(array $u): array
+    {
+        $uid = (int)$u['uid'];
+
+        return [
+            'uid'          => $uid,
+            'title'        => (string)($u['title'] ?? ''),
+            'slug'         => (string)($u['slug'] ?? ''),
+            'subtitle'     => (string)($u['subtitle'] ?? ''),
+            'teaser'       => (string)($u['teaser'] ?? ''),
+            'cardImage'    => $this->image($uid, 'card_image'),
+            'customerLogo' => $this->image($uid, 'customer_logo'),
+            'market'       => $this->market((int)($u['market'] ?? 0)),
+            'categories'   => $this->categories($uid),
+            'featured'     => (bool)($u['featured'] ?? false),
+            'layoutVariant'     => (string)($u['layout_variant'] ?? 'standard'),
+            'backgroundVariant' => (string)($u['background_variant'] ?? 'none'),
+        ];
+    }
+
+    /**
+     * @param array<string,mixed> $u
+     * @return array<string,mixed>
+     */
+    public function serializeDetail(array $u): array
+    {
+        $uid  = (int)$u['uid'];
+        $base = $this->serializeListItem($u);
+
+        return array_merge($base, [
+            'hero' => [
+                'bgImage'        => $this->image($uid, 'hero_bgimage'),
+                'smallImage'     => $this->image($uid, 'hero_small_image'),
+                'video'          => $this->video($uid, 'hero_video'),
+                'overlayColor'   => (string)($u['hero_overlay_color'] ?? ''),
+                'overlayOpacity' => (float)($u['hero_overlay_opacity'] ?? 0),
+                'layout'         => (string)($u['hero_layout'] ?? 'fullscreen'),
+                'textTheme'      => (string)($u['text_theme'] ?? 'light'),
+            ],
+            'contentElements' => $this->contentElements($uid),
+            'related' => [
+                'show'       => (bool)($u['show_related'] ?? true),
+                'market'     => $base['market'],
+                'solutions'  => $this->relationMulti('tx_vitec_usecase_solution_mm', 'tx_vitec_domain_model_solution', $uid),
+                'products'   => $this->relationMulti('tx_vitec_usecase_product_mm', 'tx_vitec_domain_model_product', $uid),
+                'categories' => $base['categories'],
+            ],
+            'seo' => $this->seo($u),
+            'appearance' => [
+                'layoutVariant'     => (string)($u['layout_variant'] ?? 'standard'),
+                'backgroundVariant' => (string)($u['background_variant'] ?? 'none'),
+                'accentColor'       => (string)($u['accent_color'] ?? ''),
+                'featured'          => (bool)($u['featured'] ?? false),
+                'heroLayout'        => (string)($u['hero_layout'] ?? 'fullscreen'),
+                'textTheme'         => (string)($u['text_theme'] ?? 'light'),
+            ],
+        ]);
+    }
+
+    // ---------------------------------------------------------------- images
+
+    /**
+     * FAL image (with srcset). $table defaults to the usecase table but can be
+     * a content-block collection table (for Columns items).
+     *
+     * @return array<string,mixed>|null
+     */
+    public function image(int $recordUid, string $fieldName, ?string $table = null): ?array
+    {
+        try {
+            $table = $table ?? self::TABLE;
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('sys_file_reference');
+            $ref = $qb
+                ->select('sfr.uid', 'sfr.title', 'sfr.description', 'sfr.alternative', 'sfr.crop')
+                ->from('sys_file_reference', 'sfr')
+                ->where(
+                    $qb->expr()->eq('sfr.tablenames', $qb->createNamedParameter($table, ParameterType::STRING)),
+                    $qb->expr()->eq('sfr.fieldname', $qb->createNamedParameter($fieldName, ParameterType::STRING)),
+                    $qb->expr()->eq('sfr.uid_foreign', $qb->createNamedParameter($recordUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('sfr.deleted', 0),
+                    $qb->expr()->eq('sfr.hidden', 0)
+                )
+                ->orderBy('sfr.sorting_foreign')
+                ->setMaxResults(1)
+                ->executeQuery()
+                ->fetchAssociative();
+
+            if (!$ref) {
+                return null;
+            }
+
+            $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
+            $imageService = GeneralUtility::makeInstance(ImageService::class);
+            $fileReference = $resourceFactory->getFileReferenceObject((int)$ref['uid']);
+
+            $srcset = [];
+            foreach (self::IMAGE_WIDTHS as $width) {
+                $variant = $imageService->applyProcessingInstructions(
+                    $fileReference,
+                    ['width' => $width, 'crop' => $ref['crop'] ?? null]
+                );
+                $srcset[] = [
+                    'url'        => $imageService->getImageUri($variant),
+                    'width'      => $width,
+                    'descriptor' => $width . 'w',
+                ];
+            }
+
+            $default = $imageService->applyProcessingInstructions(
+                $fileReference,
+                ['width' => 800, 'crop' => $ref['crop'] ?? null]
+            );
+
+            return [
+                'uid'         => (int)$ref['uid'],
+                'url'         => $imageService->getImageUri($default),
+                'title'       => (string)($ref['title'] ?? ''),
+                'alternative' => (string)($ref['alternative'] ?? ''),
+                'description' => (string)($ref['description'] ?? ''),
+                'srcset'      => $srcset,
+                'properties'  => [
+                    'width'    => $fileReference->getProperty('width'),
+                    'height'   => $fileReference->getProperty('height'),
+                    'mimeType' => $fileReference->getProperty('mime_type'),
+                ],
+            ];
+        } catch (\Throwable $e) {
+            return null;
+        }
+    }
+
+    /**
+     * FAL video (public URL only). $table as in image().
+     *
+     * @return array<string,mixed>|null
+     */
+    public function video(int $recordUid, string $fieldName, ?string $table = null): ?array
+    {
+        try {
+            $table = $table ?? self::TABLE;
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('sys_file_reference');
+            $ref = $qb
+                ->select('uid', 'title', 'description')
+                ->from('sys_file_reference')
+                ->where(
+                    $qb->expr()->eq('tablenames', $qb->createNamedParameter($table, ParameterType::STRING)),
+                    $qb->expr()->eq('fieldname', $qb->createNamedParameter($fieldName, ParameterType::STRING)),
+                    $qb->expr()->eq('uid_foreign', $qb->createNamedParameter($recordUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('deleted', 0),
+                    $qb->expr()->eq('hidden', 0)
+                )
+                ->orderBy('sorting_foreign')
+                ->setMaxResults(1)
+                ->executeQuery()
+                ->fetchAssociative();
+
+            if (!$ref) {
+                return null;
+            }
+
+            $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
+            $fileReference = $resourceFactory->getFileReferenceObject((int)$ref['uid']);
+
+            return [
+                'uid'      => (int)$ref['uid'],
+                'url'      => $fileReference->getPublicUrl(),
+                'title'    => (string)($ref['title'] ?? ''),
+                'mimeType' => $fileReference->getProperty('mime_type'),
+            ];
+        } catch (\Throwable $e) {
+            return null;
+        }
+    }
+
+    // ------------------------------------------------------------- relations
+
+    /**
+     * Single market (foreign_table, no MM) -> title/slug.
+     *
+     * @return array<string,mixed>|null
+     */
+    public function market(int $marketUid): ?array
+    {
+        if ($marketUid <= 0) {
+            return null;
+        }
+        try {
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('tx_vitec_domain_model_market');
+            $row = $qb
+                ->select('uid', 'title', 'subtitle', 'teaser')
+                ->from('tx_vitec_domain_model_market')
+                ->where(
+                    $qb->expr()->eq('uid', $qb->createNamedParameter($marketUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('deleted', 0),
+                    $qb->expr()->eq('hidden', 0)
+                )
+                ->executeQuery()
+                ->fetchAssociative();
+
+            if (!$row) {
+                return null;
+            }
+
+            return [
+                'uid'      => (int)$row['uid'],
+                'title'    => (string)($row['title'] ?? ''),
+                'subtitle' => (string)($row['subtitle'] ?? ''),
+                'teaser'   => (string)($row['teaser'] ?? ''),
+            ];
+        } catch (\Throwable $e) {
+            return null;
+        }
+    }
+
+    /**
+     * n:n relation resolved through an MM table -> [{uid,title}, …].
+     *
+     * @return array<int,array<string,mixed>>
+     */
+    public function relationMulti(string $mmTable, string $foreignTable, int $usecaseUid): array
+    {
+        try {
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable($foreignTable);
+            $rows = $qb
+                ->select('f.uid', 'f.title')
+                ->from($foreignTable, 'f')
+                ->join('f', $mmTable, 'mm', 'mm.uid_foreign = f.uid')
+                ->where(
+                    $qb->expr()->eq('mm.uid_local', $qb->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('f.deleted', 0),
+                    $qb->expr()->eq('f.hidden', 0)
+                )
+                ->orderBy('mm.sorting', 'ASC')
+                ->executeQuery()
+                ->fetchAllAssociative();
+
+            return array_map(static fn ($r) => [
+                'uid'   => (int)$r['uid'],
+                'title' => (string)($r['title'] ?? ''),
+            ], $rows);
+        } catch (\Throwable $e) {
+            return [];
+        }
+    }
+
+    /**
+     * System categories (sys_category MM) -> [{uid,title,description}, …].
+     *
+     * @return array<int,array<string,mixed>>
+     */
+    public function categories(int $usecaseUid): array
+    {
+        try {
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('sys_category');
+            $rows = $qb
+                ->select('c.uid', 'c.title', 'c.description')
+                ->from('sys_category', 'c')
+                ->join(
+                    'c',
+                    'sys_category_record_mm',
+                    'mm',
+                    'mm.uid_local = c.uid AND mm.tablenames = ' .
+                    $qb->createNamedParameter(self::TABLE, ParameterType::STRING) .
+                    ' AND mm.fieldname = ' .
+                    $qb->createNamedParameter('categories', ParameterType::STRING)
+                )
+                ->where(
+                    $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('c.deleted', 0),
+                    $qb->expr()->eq('c.hidden', 0)
+                )
+                ->orderBy('mm.sorting', 'ASC')
+                ->executeQuery()
+                ->fetchAllAssociative();
+
+            return array_map(static fn ($c) => [
+                'uid'         => (int)$c['uid'],
+                'title'       => (string)($c['title'] ?? ''),
+                'description' => (string)($c['description'] ?? ''),
+            ], $rows);
+        } catch (\Throwable $e) {
+            return [];
+        }
+    }
+
+    // ------------------------------------------------------- content elements
+
+    /**
+     * Inline content elements (tt_content owned via tx_vitec_usecase_content).
+     * Flat CEs are normalised; a VITEC Columns element is resolved specially.
+     *
+     * @return array<int,array<string,mixed>>
+     */
+    public function contentElements(int $usecaseUid): array
+    {
+        try {
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('tt_content');
+            $rows = $qb
+                ->select('*')
+                ->from('tt_content')
+                ->where(
+                    $qb->expr()->eq('tx_vitec_usecase_content', $qb->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('deleted', 0),
+                    $qb->expr()->eq('hidden', 0)
+                )
+                ->orderBy('sorting', 'ASC')
+                ->executeQuery()
+                ->fetchAllAssociative();
+
+            $out = [];
+            foreach ($rows as $row) {
+                $resolved = $this->resolveInlineElement($row);
+                if ($resolved !== null) {
+                    $out[] = $resolved;
+                }
+            }
+            return $out;
+        } catch (\Throwable $e) {
+            return [];
+        }
+    }
+
+    /**
+     * @param array<string,mixed> $row
+     * @return array<string,mixed>|null
+     */
+    private function resolveInlineElement(array $row): ?array
+    {
+        if ((string)($row['CType'] ?? '') === self::COLUMNS_CTYPE) {
+            return $this->resolveColumnsElement($row);
+        }
+        return ContentElementResolver::normaliseRecord($row);
+    }
+
+    /**
+     * VITEC Columns content block -> { header…, layout, columns:{left,right} }.
+     * Items live in a content-blocks collection table (discovered from TCA) and
+     * carry a `column` (left/right) plus a typed payload.
+     *
+     * @param array<string,mixed> $row
+     * @return array<string,mixed>
+     */
+    private function resolveColumnsElement(array $row): array
+    {
+        $uid = (int)$row['uid'];
+
+        $left = [];
+        $right = [];
+
+        $table = $this->collectionTable('vitec_items') ?? $this->collectionTable('items');
+        if ($table !== null) {
+            try {
+                $qb = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable($table);
+                $items = $qb
+                    ->select('*')
+                    ->from($table)
+                    ->where(
+                        $qb->expr()->eq('foreign_table_parent_uid', $qb->createNamedParameter($uid, ParameterType::INTEGER)),
+                        $qb->expr()->eq('deleted', 0),
+                        $qb->expr()->eq('hidden', 0)
+                    )
+                    ->orderBy('sorting', 'ASC')
+                    ->executeQuery()
+                    ->fetchAllAssociative();
+
+                foreach ($items as $it) {
+                    $column = (string)($it['vitec_column'] ?? $it['column'] ?? 'left');
+                    $resolved = $this->resolveColumnItem($it, $table);
+                    if ($column === 'right') {
+                        $right[] = $resolved;
+                    } else {
+                        $left[] = $resolved;
+                    }
+                }
+            } catch (\Throwable $e) {
+                // collection table not ready / query failed -> empty columns
+            }
+        }
+
+        return [
+            'id'             => $uid,
+            'type'           => self::COLUMNS_CTYPE,
+            'colPos'         => (int)($row['colPos'] ?? 0),
+            'sorting'        => (int)($row['sorting'] ?? 0),
+            'header'         => (string)($row['header'] ?? ''),
+            'subheader'      => (string)($row['subheader'] ?? ''),
+            'headerLayout'   => (int)($row['header_layout'] ?? 0),
+            'headerPosition' => (string)($row['header_position'] ?? ''),
+            'headerLink'     => (string)($row['header_link'] ?? ''),
+            'layout'         => (string)($row['vitec_layout'] ?? $row['layout'] ?? 'cols_50_50'),
+            'columns'        => [
+                'left'  => $left,
+                'right' => $right,
+            ],
+        ];
+    }
+
+    /**
+     * @param array<string,mixed> $it
+     * @return array<string,mixed>
+     */
+    private function resolveColumnItem(array $it, string $table): array
+    {
+        $uid = (int)$it['uid'];
+        $get = static fn (string $k): string => (string)($it['vitec_' . $k] ?? $it[$k] ?? '');
+
+        $imageField = array_key_exists('vitec_image', $it) ? 'vitec_image' : 'image';
+        $videoField = array_key_exists('vitec_video', $it) ? 'vitec_video' : 'video';
+
+        return [
+            'type'      => $get('item_type') !== '' ? $get('item_type') : 'text',
+            'headline'  => $get('headline'),
+            'text'      => $get('text'),
+            'image'     => $this->image($uid, $imageField, $table),
+            'video'     => $this->video($uid, $videoField, $table),
+            'link'      => $get('link'),
+            'linkLabel' => $get('link_label'),
+        ];
+    }
+
+    /**
+     * Resolve a content-blocks collection field's storage table from TCA.
+     */
+    private function collectionTable(string $field): ?string
+    {
+        $t = $GLOBALS['TCA']['tt_content']['columns'][$field]['config']['foreign_table'] ?? null;
+        return (is_string($t) && $t !== '') ? $t : null;
+    }
+
+    // ------------------------------------------------------------------- seo
+
+    /**
+     * SEO bundle with fallback resolution (title/teaser/card/hero images).
+     *
+     * @param array<string,mixed> $u
+     * @return array<string,mixed>
+     */
+    public function seo(array $u): array
+    {
+        $uid = (int)$u['uid'];
+
+        $title = $this->firstNonEmpty([(string)($u['seo_title'] ?? ''), (string)($u['title'] ?? '')]);
+        $desc  = $this->firstNonEmpty([(string)($u['seo_description'] ?? ''), (string)($u['teaser'] ?? '')]);
+
+        $ogTitle = $this->firstNonEmpty([(string)($u['og_title'] ?? ''), $title]);
+        $ogDesc  = $this->firstNonEmpty([(string)($u['og_description'] ?? ''), $desc]);
+        $ogImage = $this->image($uid, 'og_image')
+            ?? $this->image($uid, 'card_image')
+            ?? $this->image($uid, 'hero_bgimage');
+
+        $twTitle = $this->firstNonEmpty([(string)($u['twitter_title'] ?? ''), $ogTitle]);
+        $twDesc  = $this->firstNonEmpty([(string)($u['twitter_description'] ?? ''), $ogDesc]);
+        $twImage = $this->image($uid, 'twitter_image') ?? $ogImage;
+
+        return [
+            'title'       => $title,
+            'description' => $desc,
+            'canonical'   => (string)($u['canonical_link'] ?? ''),
+            'robots'      => [
+                'noIndex'  => (bool)($u['no_index'] ?? false),
+                'noFollow' => (bool)($u['no_follow'] ?? false),
+            ],
+            'openGraph' => [
+                'title'       => $ogTitle,
+                'description' => $ogDesc,
+                'image'       => $ogImage,
+            ],
+            'twitter' => [
+                'title'       => $twTitle,
+                'description' => $twDesc,
+                'image'       => $twImage,
+            ],
+        ];
+    }
+
+    /**
+     * @param array<int,string> $candidates
+     */
+    private function firstNonEmpty(array $candidates): string
+    {
+        foreach ($candidates as $c) {
+            $c = trim($c);
+            if ($c !== '') {
+                return $c;
+            }
+        }
+        return '';
+    }
+}

packages/vitec/Classes/UserFunc/DatasheetsJsonRenderer.php

@@ -7,6 +7,7 @@ namespace Evomedien\Vitec\UserFunc;
 
 use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
+use TYPO3\CMS\Core\Core\Environment;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Resource\ResourceFactory;
 use TYPO3\CMS\Core\Service\FlexFormService;
@@ -49,13 +50,7 @@ class DatasheetsJsonRenderer
             ->from('tt_content')
             ->where(
                 $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
-                $qb->expr()->or(
-                    $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_datasheets', ParameterType::STRING)),
-                    $qb->expr()->and(
-                        $qb->expr()->eq('CType', $qb->createNamedParameter('list', ParameterType::STRING)),
-                        $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_datasheets', ParameterType::STRING))
-                    )
-                ),
+                $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_datasheets', ParameterType::STRING)),
                 $qb->expr()->eq('deleted', 0),
                 $qb->expr()->eq('hidden', 0)
             )
@@ -118,6 +113,7 @@ class DatasheetsJsonRenderer
                 $response['debug'] = [
                     'productCount' => count($itemsOut),
                     'settings'     => $settings,
+                    'fallbackFiles' => $this->collectFallbackFilesFromItems($itemsOut),
                 ];
             }
 
@@ -259,6 +255,7 @@ class DatasheetsJsonRenderer
     private function serializeDatasheet(array $download): array
     {
         $uid = (int)$download['uid'];
+        $filetype = $this->getDownloadFileType($uid);
         return [
             'uid'         => $uid,
             'title'       => (string)($download['title'] ?? ''),
@@ -266,10 +263,48 @@ class DatasheetsJsonRenderer
             'teaser'      => (string)($download['teaser'] ?? ''),
             'description' => (string)($download['description'] ?? ''),
             'tstamp'      => (int)($download['tstamp'] ?? 0),
-            'file'        => $this->getDownloadFile($uid),
+            'filetype'    => $filetype,
+            'file'        => $this->getDownloadFile($uid, (string)($download['fileprefix'] ?? ''), $filetype),
         ];
     }
 
+    private function getDownloadFileType(int $downloadUid): string
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        $categories = $qb
+            ->select('c.filetype')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid AND mm.tablenames = ' .
+                $qb->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING) .
+                ' AND mm.fieldname = ' .
+                $qb->createNamedParameter('categories', ParameterType::STRING)
+            )
+            ->where(
+                $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($downloadUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('c.deleted', 0),
+                $qb->expr()->eq('c.hidden', 0),
+                $qb->expr()->eq('c.parent', $qb->createNamedParameter(4, ParameterType::INTEGER))
+            )
+            ->orderBy('mm.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        foreach ($categories as $category) {
+            $filetype = trim((string)($category['filetype'] ?? ''));
+            if ($filetype !== '') {
+                return $filetype;
+            }
+        }
+
+        return '';
+    }
+
     /**
      * @return array<string,mixed>|null
      */
@@ -356,7 +391,7 @@ class DatasheetsJsonRenderer
     /**
      * @return array<string,mixed>|null
      */
-    private function getDownloadFile(int $downloadUid): ?array
+    private function getDownloadFile(int $downloadUid, string $fileprefix = '', string $filetype = ''): ?array
     {
         $qb = GeneralUtility::makeInstance(ConnectionPool::class)
             ->getQueryBuilderForTable('sys_file_reference');
@@ -378,7 +413,7 @@ class DatasheetsJsonRenderer
             ->fetchAssociative();
 
         if (!$row) {
-            return null;
+            return $this->resolveFileByConvention($fileprefix, $filetype);
         }
 
         return [
@@ -392,4 +427,129 @@ class DatasheetsJsonRenderer
             'description' => (string)($row['description'] ?? ''),
         ];
     }
+
+    /**
+     * Resolve file from naming convention:
+     * [fileprefix]__[filetype]__[number]-[letter].ext
+     * and pick highest number + highest letter.
+     *
+     * @return array<string,mixed>|null
+     */
+    private function resolveFileByConvention(string $fileprefix, string $filetype): ?array
+    {
+        $fileprefix = trim($fileprefix);
+        $filetype = trim($filetype);
+        if ($fileprefix === '' || $filetype === '') {
+            return null;
+        }
+
+        $baseDir = Environment::getPublicPath() . '/fileadmin/downloads/Collateral';
+        if (!is_dir($baseDir) || !is_readable($baseDir)) {
+            return null;
+        }
+
+        $escapedPrefix = preg_quote($fileprefix, '/');
+        $escapedType = preg_quote($filetype, '/');
+        $pattern = '/^' . $escapedPrefix . '__' . $escapedType . '__(\\d+)-([A-Za-z]+)\\.([A-Za-z0-9]+)$/';
+
+        $bestFile = null;
+        $bestNumber = -1;
+        $bestLetterRank = -1;
+
+        $entries = scandir($baseDir);
+        if ($entries === false) {
+            return null;
+        }
+
+        foreach ($entries as $entry) {
+            if (!is_string($entry) || $entry === '.' || $entry === '..') {
+                continue;
+            }
+
+            if (!preg_match($pattern, $entry, $matches)) {
+                continue;
+            }
+
+            $number = (int)$matches[1];
+            $letter = strtoupper($matches[2]);
+            $letterRank = $this->letterSequenceToRank($letter);
+
+            if ($number > $bestNumber || ($number === $bestNumber && $letterRank > $bestLetterRank)) {
+                $bestNumber = $number;
+                $bestLetterRank = $letterRank;
+                $bestFile = $entry;
+            }
+        }
+
+        if ($bestFile === null) {
+            return null;
+        }
+
+        $fullPath = $baseDir . '/' . $bestFile;
+        if (!is_file($fullPath) || !is_readable($fullPath)) {
+            return null;
+        }
+
+        $extension = strtolower(pathinfo($bestFile, PATHINFO_EXTENSION));
+        $mimeType = function_exists('mime_content_type') ? (string)(mime_content_type($fullPath) ?: '') : '';
+
+        return [
+            'uid' => 0,
+            'name' => $bestFile,
+            'url' => '/fileadmin/downloads/Collateral/' . rawurlencode($bestFile),
+            'size' => (int)(filesize($fullPath) ?: 0),
+            'extension' => $extension,
+            'mimeType' => $mimeType,
+            'title' => '',
+            'description' => '',
+        ];
+    }
+
+    private function letterSequenceToRank(string $letters): int
+    {
+        $rank = 0;
+        $letters = strtoupper($letters);
+        $length = strlen($letters);
+
+        for ($i = 0; $i < $length; $i++) {
+            $char = ord($letters[$i]);
+            if ($char < 65 || $char > 90) {
+                continue;
+            }
+
+            $rank = ($rank * 26) + ($char - 64);
+        }
+
+        return $rank;
+    }
+
+    /**
+     * @param array<int,array<string,mixed>> $items
+     * @return array<int,array<string,mixed>>
+     */
+    private function collectFallbackFilesFromItems(array $items): array
+    {
+        $fallbackFiles = [];
+
+        foreach ($items as $item) {
+            $datasheet = $item['datasheet'] ?? null;
+            if (!is_array($datasheet)) {
+                continue;
+            }
+
+            $file = $datasheet['file'] ?? null;
+            if (!is_array($file) || (int)($file['uid'] ?? 1) !== 0) {
+                continue;
+            }
+
+            $fallbackFiles[] = [
+                'datasheetUid' => (int)($datasheet['uid'] ?? 0),
+                'name' => (string)($file['name'] ?? ''),
+                'url' => (string)($file['url'] ?? ''),
+                'source' => 'naming-convention-fallback',
+            ];
+        }
+
+        return $fallbackFiles;
+    }
 }

packages/vitec/Classes/UserFunc/DownloadcardJsonRenderer.php

@@ -7,6 +7,7 @@ namespace Evomedien\Vitec\UserFunc;
 
 use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
+use TYPO3\CMS\Core\Core\Environment;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Service\FlexFormService;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
@@ -44,20 +45,12 @@ class DownloadcardJsonRenderer
         $qb = GeneralUtility::makeInstance(ConnectionPool::class)
             ->getQueryBuilderForTable('tt_content');
 
-        // After v14 migration the CType is the plugin signature; for legacy
-        // (unmigrated) records the CType is still "list" with list_type set.
         $rows = $qb
             ->select('*')
             ->from('tt_content')
             ->where(
                 $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
-                $qb->expr()->or(
-                    $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_downloadcard', ParameterType::STRING)),
-                    $qb->expr()->and(
-                        $qb->expr()->eq('CType', $qb->createNamedParameter('list', ParameterType::STRING)),
-                        $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_downloadcard', ParameterType::STRING))
-                    )
-                ),
+                $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_downloadcard', ParameterType::STRING)),
                 $qb->expr()->eq('deleted', 0),
                 $qb->expr()->eq('hidden', 0)
             )
@@ -106,14 +99,17 @@ class DownloadcardJsonRenderer
                         : '';
                 }
 
+                $serializedDownload = $this->serializeDownload($download);
+
                 $response = [
                     'mode'     => 'single',
-                    'download' => $this->serializeDownload($download),
+                    'download' => $serializedDownload,
                     'settings' => $settingsOut,
                 ];
                 if ($debugMode) {
                     $response['debug'] = [
                         'pageId' => $pageId, 'downloadUid' => $downloadUid, 'settings' => $settings,
+                        'fallbackFiles' => $this->collectFallbackFilesFromDownloads([$serializedDownload]),
                     ];
                 }
                 return json_encode($response);
@@ -123,11 +119,12 @@ class DownloadcardJsonRenderer
             if ($productUid > 0) {
                 $downloads = $this->fetchDownloadsForProduct($productUid);
                 $product   = $this->fetchProductContext($productUid);
+                $serializedDownloads = array_map(fn($r) => $this->serializeDownload($r), $downloads);
 
                 $response = [
                     'mode'      => 'product-downloads',
                     'product'   => $product,
-                    'downloads' => array_map(fn($r) => $this->serializeDownload($r), $downloads),
+                    'downloads' => $serializedDownloads,
                     'settings'  => $settingsOut,
                 ];
                 if ($debugMode) {
@@ -136,6 +133,7 @@ class DownloadcardJsonRenderer
                         'productUid' => $productUid,
                         'downloadCount' => count($downloads),
                         'settings' => $settings,
+                        'fallbackFiles' => $this->collectFallbackFilesFromDownloads($serializedDownloads),
                     ];
                 }
                 return json_encode($response);
@@ -248,6 +246,8 @@ class DownloadcardJsonRenderer
     protected function serializeDownload(array $download): array
     {
         $uid = (int)$download['uid'];
+        $fileprefix = (string)($download['fileprefix'] ?? '');
+        $filetype = $this->getDownloadFileType($uid);
 
         return [
             'uid'              => $uid,
@@ -258,22 +258,60 @@ class DownloadcardJsonRenderer
             'keywords'         => (string)($download['keywords'] ?? ''),
             'icon'             => (string)($download['icon'] ?? ''),
             'filepath'         => (string)($download['filepath'] ?? ''),
-            'fileprefix'       => (string)($download['fileprefix'] ?? ''),
+            'fileprefix'       => $fileprefix,
+            'filetype'         => $filetype,
             'private_download' => (bool)($download['private_download'] ?? false),
             'hideonapp'        => (bool)($download['hideonapp'] ?? false),
             'hideonwebsite'    => (bool)($download['hideonwebsite'] ?? false),
             'hideondatasheets' => (bool)($download['hideondatasheets'] ?? false),
             'hideonproducts'   => (bool)($download['hideonproducts'] ?? false),
-            'file'             => $this->getDownloadFile($uid),
+            'file'             => $this->getDownloadFile($uid, $fileprefix, $filetype),
         ];
     }
 
+    private function getDownloadFileType(int $downloadUid): string
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        $categories = $qb
+            ->select('c.filetype')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid AND mm.tablenames = ' .
+                $qb->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING) .
+                ' AND mm.fieldname = ' .
+                $qb->createNamedParameter('categories', ParameterType::STRING)
+            )
+            ->where(
+                $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($downloadUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('c.deleted', 0),
+                $qb->expr()->eq('c.hidden', 0),
+                $qb->expr()->eq('c.parent', $qb->createNamedParameter(4, ParameterType::INTEGER))
+            )
+            ->orderBy('mm.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        foreach ($categories as $category) {
+            $filetype = trim((string)($category['filetype'] ?? ''));
+            if ($filetype !== '') {
+                return $filetype;
+            }
+        }
+
+        return '';
+    }
+
     /**
      * Resolve the FAL file reference (fieldname=file) for a download.
      *
      * @return array<string,mixed>|null
      */
-    protected function getDownloadFile(int $downloadUid): ?array
+    protected function getDownloadFile(int $downloadUid, string $fileprefix = '', string $filetype = ''): ?array
     {
         $qb = GeneralUtility::makeInstance(ConnectionPool::class)
             ->getQueryBuilderForTable('sys_file_reference');
@@ -295,7 +333,7 @@ class DownloadcardJsonRenderer
             ->fetchAssociative();
 
         if (!$row) {
-            return null;
+            return $this->resolveFileByConvention($fileprefix, $filetype);
         }
 
         $thumbnailUrl = null;
@@ -324,4 +362,124 @@ class DownloadcardJsonRenderer
             'description' => (string)($row['description'] ?? ''),
         ];
     }
+
+    /**
+     * @return array<string,mixed>|null
+     */
+    private function resolveFileByConvention(string $fileprefix, string $filetype): ?array
+    {
+        $fileprefix = trim($fileprefix);
+        $filetype = trim($filetype);
+        if ($fileprefix === '' || $filetype === '') {
+            return null;
+        }
+
+        $baseDir = Environment::getPublicPath() . '/fileadmin/downloads/Collateral';
+        if (!is_dir($baseDir) || !is_readable($baseDir)) {
+            return null;
+        }
+
+        $escapedPrefix = preg_quote($fileprefix, '/');
+        $escapedType = preg_quote($filetype, '/');
+        $pattern = '/^' . $escapedPrefix . '__' . $escapedType . '__(\\d+)-([A-Za-z]+)\\.([A-Za-z0-9]+)$/';
+
+        $bestFile = null;
+        $bestNumber = -1;
+        $bestLetterRank = -1;
+
+        $entries = scandir($baseDir);
+        if ($entries === false) {
+            return null;
+        }
+
+        foreach ($entries as $entry) {
+            if (!is_string($entry) || $entry === '.' || $entry === '..') {
+                continue;
+            }
+
+            if (!preg_match($pattern, $entry, $matches)) {
+                continue;
+            }
+
+            $number = (int)$matches[1];
+            $letterRank = $this->letterSequenceToRank((string)$matches[2]);
+
+            if ($number > $bestNumber || ($number === $bestNumber && $letterRank > $bestLetterRank)) {
+                $bestNumber = $number;
+                $bestLetterRank = $letterRank;
+                $bestFile = $entry;
+            }
+        }
+
+        if ($bestFile === null) {
+            return null;
+        }
+
+        $fullPath = $baseDir . '/' . $bestFile;
+        if (!is_file($fullPath) || !is_readable($fullPath)) {
+            return null;
+        }
+
+        $extension = strtolower(pathinfo($bestFile, PATHINFO_EXTENSION));
+        $mimeType = function_exists('mime_content_type') ? (string)(mime_content_type($fullPath) ?: '') : '';
+
+        return [
+            'uid' => 0,
+            'name' => $bestFile,
+            'url' => '/fileadmin/downloads/Collateral/' . rawurlencode($bestFile),
+            'thumbnail' => null,
+            'size' => (int)(filesize($fullPath) ?: 0),
+            'extension' => $extension,
+            'mimeType' => $mimeType,
+            'title' => '',
+            'description' => '',
+        ];
+    }
+
+    private function letterSequenceToRank(string $letters): int
+    {
+        $rank = 0;
+        $letters = strtoupper($letters);
+        $length = strlen($letters);
+
+        for ($i = 0; $i < $length; $i++) {
+            $char = ord($letters[$i]);
+            if ($char < 65 || $char > 90) {
+                continue;
+            }
+
+            $rank = ($rank * 26) + ($char - 64);
+        }
+
+        return $rank;
+    }
+
+    /**
+     * @param array<int,array<string,mixed>> $downloads
+     * @return array<int,array<string,mixed>>
+     */
+    private function collectFallbackFilesFromDownloads(array $downloads): array
+    {
+        $fallbackFiles = [];
+
+        foreach ($downloads as $download) {
+            $file = $download['file'] ?? null;
+            if (!is_array($file)) {
+                continue;
+            }
+
+            if ((int)($file['uid'] ?? 1) !== 0) {
+                continue;
+            }
+
+            $fallbackFiles[] = [
+                'downloadUid' => (int)($download['uid'] ?? 0),
+                'name' => (string)($file['name'] ?? ''),
+                'url' => (string)($file['url'] ?? ''),
+                'source' => 'naming-convention-fallback',
+            ];
+        }
+
+        return $fallbackFiles;
+    }
 }

packages/vitec/Classes/UserFunc/DownloadcardcollectionJsonRenderer.php

@@ -7,6 +7,7 @@ namespace Evomedien\Vitec\UserFunc;
 
 use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
+use TYPO3\CMS\Core\Core\Environment;
 use TYPO3\CMS\Core\Database\Connection;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Resource\ResourceFactory;
@@ -96,13 +97,14 @@ class DownloadcardcollectionJsonRenderer
             // --- Downloads: comma-separated UID list from settings.download ---
             $downloadUids = $this->parseUidList($settings['download'] ?? '');
             $downloads = $downloadUids === [] ? [] : $this->fetchDownloadsByUids($downloadUids);
+            $serializedDownloads = array_map(fn($r) => $this->serializeDownload($r), $downloads);
 
             // --- Header image (inline FAL on this tt_content element, fieldname=image) ---
             $image = $this->getCollectionImage($ttContentUid);
 
             $response = [
                 'image'     => $image,
-                'downloads' => array_map(fn($r) => $this->serializeDownload($r), $downloads),
+                'downloads' => $serializedDownloads,
                 'settings'  => $settingsOut,
             ];
 
@@ -112,6 +114,7 @@ class DownloadcardcollectionJsonRenderer
                     'downloadUids'   => $downloadUids,
                     'downloadCount'  => count($downloads),
                     'settings'       => $settings,
+                    'fallbackFiles'  => $this->collectFallbackFilesFromDownloads($serializedDownloads),
                 ];
             }
 
@@ -212,7 +215,6 @@ class DownloadcardcollectionJsonRenderer
                 );
                 $srcset[] = [
                     'url'        => $imageService->getImageUri($variant),
-            'thumbnail' => $thumbnailUrl,
                     'width'      => $width,
                     'descriptor' => $width . 'w',
                 ];
@@ -226,7 +228,6 @@ class DownloadcardcollectionJsonRenderer
             return [
                 'uid'         => (int)$fileRefData['uid'],
                 'url'         => $imageService->getImageUri($default),
-            'thumbnail' => $thumbnailUrl,
                 'title'       => $fileRefData['title'] ?? '',
                 'alternative' => $fileRefData['alternative'] ?? '',
                 'description' => $fileRefData['description'] ?? '',
@@ -249,6 +250,8 @@ class DownloadcardcollectionJsonRenderer
     protected function serializeDownload(array $download): array
     {
         $uid = (int)$download['uid'];
+        $fileprefix = (string)($download['fileprefix'] ?? '');
+        $filetype = $this->getDownloadFileType($uid);
 
         return [
             'uid'              => $uid,
@@ -259,22 +262,60 @@ class DownloadcardcollectionJsonRenderer
             'keywords'         => (string)($download['keywords'] ?? ''),
             'icon'             => (string)($download['icon'] ?? ''),
             'filepath'         => (string)($download['filepath'] ?? ''),
-            'fileprefix'       => (string)($download['fileprefix'] ?? ''),
+            'fileprefix'       => $fileprefix,
+            'filetype'         => $filetype,
             'private_download' => (bool)($download['private_download'] ?? false),
             'hideonapp'        => (bool)($download['hideonapp'] ?? false),
             'hideonwebsite'    => (bool)($download['hideonwebsite'] ?? false),
             'hideondatasheets' => (bool)($download['hideondatasheets'] ?? false),
             'hideonproducts'   => (bool)($download['hideonproducts'] ?? false),
-            'file'             => $this->getDownloadFile($uid),
+            'file'             => $this->getDownloadFile($uid, $fileprefix, $filetype),
         ];
     }
 
+    private function getDownloadFileType(int $downloadUid): string
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        $categories = $qb
+            ->select('c.filetype')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid AND mm.tablenames = ' .
+                $qb->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING) .
+                ' AND mm.fieldname = ' .
+                $qb->createNamedParameter('categories', ParameterType::STRING)
+            )
+            ->where(
+                $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($downloadUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('c.deleted', 0),
+                $qb->expr()->eq('c.hidden', 0),
+                $qb->expr()->eq('c.parent', $qb->createNamedParameter(4, ParameterType::INTEGER))
+            )
+            ->orderBy('mm.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        foreach ($categories as $category) {
+            $filetype = trim((string)($category['filetype'] ?? ''));
+            if ($filetype !== '') {
+                return $filetype;
+            }
+        }
+
+        return '';
+    }
+
     /**
      * Resolve the FAL file reference (fieldname=file) for a download.
      *
      * @return array<string,mixed>|null
      */
-    protected function getDownloadFile(int $downloadUid): ?array
+    protected function getDownloadFile(int $downloadUid, string $fileprefix = '', string $filetype = ''): ?array
     {
         $qb = GeneralUtility::makeInstance(ConnectionPool::class)
             ->getQueryBuilderForTable('sys_file_reference');
@@ -296,7 +337,7 @@ class DownloadcardcollectionJsonRenderer
             ->fetchAssociative();
 
         if (!$row) {
-            return null;
+            return $this->resolveFileByConvention($fileprefix, $filetype);
         }
 
 
@@ -325,4 +366,124 @@ class DownloadcardcollectionJsonRenderer
             'description' => (string)($row['description'] ?? ''),
         ];
     }
+
+    /**
+     * @return array<string,mixed>|null
+     */
+    private function resolveFileByConvention(string $fileprefix, string $filetype): ?array
+    {
+        $fileprefix = trim($fileprefix);
+        $filetype = trim($filetype);
+        if ($fileprefix === '' || $filetype === '') {
+            return null;
+        }
+
+        $baseDir = Environment::getPublicPath() . '/fileadmin/downloads/Collateral';
+        if (!is_dir($baseDir) || !is_readable($baseDir)) {
+            return null;
+        }
+
+        $escapedPrefix = preg_quote($fileprefix, '/');
+        $escapedType = preg_quote($filetype, '/');
+        $pattern = '/^' . $escapedPrefix . '__' . $escapedType . '__(\\d+)-([A-Za-z]+)\\.([A-Za-z0-9]+)$/';
+
+        $bestFile = null;
+        $bestNumber = -1;
+        $bestLetterRank = -1;
+
+        $entries = scandir($baseDir);
+        if ($entries === false) {
+            return null;
+        }
+
+        foreach ($entries as $entry) {
+            if (!is_string($entry) || $entry === '.' || $entry === '..') {
+                continue;
+            }
+
+            if (!preg_match($pattern, $entry, $matches)) {
+                continue;
+            }
+
+            $number = (int)$matches[1];
+            $letterRank = $this->letterSequenceToRank((string)$matches[2]);
+
+            if ($number > $bestNumber || ($number === $bestNumber && $letterRank > $bestLetterRank)) {
+                $bestNumber = $number;
+                $bestLetterRank = $letterRank;
+                $bestFile = $entry;
+            }
+        }
+
+        if ($bestFile === null) {
+            return null;
+        }
+
+        $fullPath = $baseDir . '/' . $bestFile;
+        if (!is_file($fullPath) || !is_readable($fullPath)) {
+            return null;
+        }
+
+        $extension = strtolower(pathinfo($bestFile, PATHINFO_EXTENSION));
+        $mimeType = function_exists('mime_content_type') ? (string)(mime_content_type($fullPath) ?: '') : '';
+
+        return [
+            'uid' => 0,
+            'name' => $bestFile,
+            'url' => '/fileadmin/downloads/Collateral/' . rawurlencode($bestFile),
+            'thumbnail' => null,
+            'size' => (int)(filesize($fullPath) ?: 0),
+            'extension' => $extension,
+            'mimeType' => $mimeType,
+            'title' => '',
+            'description' => '',
+        ];
+    }
+
+    private function letterSequenceToRank(string $letters): int
+    {
+        $rank = 0;
+        $letters = strtoupper($letters);
+        $length = strlen($letters);
+
+        for ($i = 0; $i < $length; $i++) {
+            $char = ord($letters[$i]);
+            if ($char < 65 || $char > 90) {
+                continue;
+            }
+
+            $rank = ($rank * 26) + ($char - 64);
+        }
+
+        return $rank;
+    }
+
+    /**
+     * @param array<int,array<string,mixed>> $downloads
+     * @return array<int,array<string,mixed>>
+     */
+    private function collectFallbackFilesFromDownloads(array $downloads): array
+    {
+        $fallbackFiles = [];
+
+        foreach ($downloads as $download) {
+            $file = $download['file'] ?? null;
+            if (!is_array($file)) {
+                continue;
+            }
+
+            if ((int)($file['uid'] ?? 1) !== 0) {
+                continue;
+            }
+
+            $fallbackFiles[] = [
+                'downloadUid' => (int)($download['uid'] ?? 0),
+                'name' => (string)($file['name'] ?? ''),
+                'url' => (string)($file['url'] ?? ''),
+                'source' => 'naming-convention-fallback',
+            ];
+        }
+
+        return $fallbackFiles;
+    }
 }

packages/vitec/Classes/UserFunc/EventlistJsonRenderer.php

@@ -0,0 +1,314 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Evomedien\Vitec\UserFunc;
+
+use Doctrine\DBAL\ParameterType;
+use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
+use TYPO3\CMS\Core\Database\ConnectionPool;
+use TYPO3\CMS\Core\Resource\ResourceFactory;
+use TYPO3\CMS\Core\Service\FlexFormService;
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+use TYPO3\CMS\Extbase\Service\ImageService;
+
+/**
+ * UserFunc to render the event list (tx_vitec_domain_model_event) as JSON.
+ *
+ * Default: upcoming events (event end — or start, when no end is set — is
+ * today or later), soonest first. FlexForm options: showpast (append past
+ * events, most recent first, under "pastEvents"), limit, debug.
+ *
+ * `render()` = TypoScript entry (cObj->data or page discovery).
+ * `renderForRecord()` = one specific tt_content row; reused by
+ * ContainerChildrenProcessor / ContentElementResolver. Exception-safe.
+ */
+class EventlistJsonRenderer
+{
+    #[AsAllowedCallable]
+    public function render(string $content, array $conf): string
+    {
+        // 1) cObj data path
+        $row = is_array($this->cObj->data ?? null) ? $this->cObj->data : null;
+        if ($row && (string)($row['CType'] ?? '') === 'vitec_eventlist') {
+            return $this->renderForRecord($row);
+        }
+
+        // 2) Page discovery via v14 request attribute
+        $pageId = 0;
+        $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
+        if ($request !== null) {
+            $pageInfo = $request->getAttribute('frontend.page.information');
+            if ($pageInfo !== null) {
+                $pageId = (int)$pageInfo->getId();
+            }
+        }
+        if ($pageId <= 0) {
+            $pageId = (int)($GLOBALS['TSFE']->id ?? 0);
+        }
+        if ($pageId <= 0) {
+            return '';
+        }
+
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tt_content');
+
+        $contentElements = $qb
+            ->select('*')
+            ->from('tt_content')
+            ->where(
+                $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
+                $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_eventlist', ParameterType::STRING)),
+                $qb->expr()->eq('deleted', 0),
+                $qb->expr()->eq('hidden', 0)
+            )
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        if (empty($contentElements)) {
+            return '';
+        }
+
+        return $this->renderForRecord($contentElements[0]);
+    }
+
+    /**
+     * @param array<string,mixed> $contentElement
+     */
+    public function renderForRecord(array $contentElement): string
+    {
+        try {
+            $flexFormService = GeneralUtility::makeInstance(FlexFormService::class);
+            $flexFormData = $flexFormService->convertFlexFormContentToArray($contentElement['pi_flexform'] ?? '');
+            $settings = $flexFormData['settings'] ?? [];
+
+            $showPast = (bool)($settings['showpast'] ?? false);
+            $daysInAdvance = (int)($settings['daysinadvance'] ?? 0);
+            $limit = (int)($settings['limit'] ?? 0);
+            $debugMode = (bool)($settings['debug'] ?? false);
+
+            $upcoming = $this->fetchEvents(true, $limit, $daysInAdvance);
+
+            $response = [
+                'events' => array_map(fn($e) => $this->serializeEvent($e), $upcoming),
+                'settings' => [
+                    'showpast' => $showPast,
+                    'daysinadvance' => $daysInAdvance,
+                    'limit' => $limit,
+                ],
+            ];
+
+            if ($showPast) {
+                $past = $this->fetchEvents(false, $limit);
+                $response['pastEvents'] = array_map(fn($e) => $this->serializeEvent($e), $past);
+            }
+
+            if ($debugMode) {
+                $response['debug'] = [
+                    'upcomingCount' => count($upcoming),
+                    'settings' => $settings,
+                ];
+            }
+
+            return json_encode($response);
+        } catch (\Throwable $e) {
+            return '';
+        }
+    }
+
+    /**
+     * @return array<int,array<string,mixed>>
+     */
+    private function fetchEvents(bool $upcoming, int $limit, int $daysInAdvance = 0): array
+    {
+        $todayMidnight = strtotime('today');
+
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_vitec_domain_model_event');
+        $expr = $qb->expr();
+
+        $qb
+            ->select('*')
+            ->from('tx_vitec_domain_model_event')
+            ->where(
+                $expr->eq('deleted', 0),
+                $expr->eq('hidden', 0),
+                $expr->eq('hideonwebsite', 0)
+            );
+
+        if ($upcoming) {
+            // running or future: end >= today, or (no end and start >= today)
+            $qb->andWhere(
+                $expr->or(
+                    $expr->gte('eventend', $qb->createNamedParameter($todayMidnight, ParameterType::INTEGER)),
+                    $expr->and(
+                        $expr->eq('eventend', 0),
+                        $expr->gte('eventstart', $qb->createNamedParameter($todayMidnight, ParameterType::INTEGER))
+                    )
+                )
+            );
+            $qb->orderBy('eventstart', 'ASC');
+            if ($daysInAdvance > 0) {
+                $qb->andWhere(
+                    $expr->lt('eventstart', $qb->createNamedParameter($todayMidnight + ($daysInAdvance * 86400), ParameterType::INTEGER))
+                );
+            }
+        } else {
+            // past: (end > 0 and end < today) or (no end and 0 < start < today)
+            $qb->andWhere(
+                $expr->or(
+                    $expr->and(
+                        $expr->gt('eventend', 0),
+                        $expr->lt('eventend', $qb->createNamedParameter($todayMidnight, ParameterType::INTEGER))
+                    ),
+                    $expr->and(
+                        $expr->eq('eventend', 0),
+                        $expr->gt('eventstart', 0),
+                        $expr->lt('eventstart', $qb->createNamedParameter($todayMidnight, ParameterType::INTEGER))
+                    )
+                )
+            );
+            $qb->orderBy('eventstart', 'DESC');
+        }
+
+        if ($limit > 0) {
+            $qb->setMaxResults($limit);
+        }
+
+        return $qb->executeQuery()->fetchAllAssociative();
+    }
+
+    /**
+     * @param array<string,mixed> $event
+     * @return array<string,mixed>
+     */
+    protected function serializeEvent(array $event): array
+    {
+        $uid = (int)$event['uid'];
+        $start = (int)($event['eventstart'] ?? 0);
+        $end = (int)($event['eventend'] ?? 0);
+
+        return [
+            'uid' => $uid,
+            'title' => (string)($event['title'] ?? ''),
+            'slug' => (string)($event['slug'] ?? ''),
+            'teaser' => (string)($event['teaser'] ?? ''),
+            'description' => (string)($event['description'] ?? ''),
+            'eventstart' => $start > 0 ? date('Y-m-d', $start) : null,
+            'eventend' => $end > 0 ? date('Y-m-d', $end) : null,
+            'venue' => (string)($event['venue'] ?? ''),
+            'booth' => (string)($event['booth'] ?? ''),
+            'city' => (string)($event['city'] ?? ''),
+            'country' => (string)($event['country'] ?? ''),
+            'attendancemode' => (string)($event['attendancemode'] ?? 'offline'),
+            'eventstatus' => (string)($event['eventstatus'] ?? 'scheduled'),
+            'eventurl' => (string)($event['eventurl'] ?? ''),
+            'meetinglink' => (string)($event['meetinglink'] ?? ''),
+            'image' => $this->getEventImage($uid),
+            'categories' => $this->getEventCategories($uid),
+        ];
+    }
+
+    /**
+     * @return array<string,mixed>|null
+     */
+    protected function getEventImage(int $eventUid): ?array
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_file_reference');
+
+        $fileRefData = $qb
+            ->select('sfr.uid', 'sfr.title', 'sfr.description', 'sfr.alternative', 'sfr.crop')
+            ->from('sys_file_reference', 'sfr')
+            ->where(
+                $qb->expr()->eq('sfr.tablenames', $qb->createNamedParameter('tx_vitec_domain_model_event', ParameterType::STRING)),
+                $qb->expr()->eq('sfr.fieldname', $qb->createNamedParameter('image', ParameterType::STRING)),
+                $qb->expr()->eq('sfr.uid_foreign', $qb->createNamedParameter($eventUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('sfr.deleted', 0),
+                $qb->expr()->eq('sfr.hidden', 0)
+            )
+            ->orderBy('sfr.sorting_foreign')
+            ->setMaxResults(1)
+            ->executeQuery()
+            ->fetchAssociative();
+
+        if (!$fileRefData) {
+            return null;
+        }
+
+        try {
+            $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
+            $imageService = GeneralUtility::makeInstance(ImageService::class);
+            $fileReference = $resourceFactory->getFileReferenceObject((int)$fileRefData['uid']);
+
+            $srcset = [];
+            foreach ([400, 800] as $width) {
+                $variant = $imageService->applyProcessingInstructions(
+                    $fileReference,
+                    ['width' => $width, 'crop' => $fileRefData['crop'] ?? null]
+                );
+                $srcset[] = [
+                    'url' => $imageService->getImageUri($variant),
+                    'width' => $width,
+                    'descriptor' => $width . 'w',
+                ];
+            }
+
+            $default = $imageService->applyProcessingInstructions(
+                $fileReference,
+                ['width' => 400, 'crop' => $fileRefData['crop'] ?? null]
+            );
+
+            return [
+                'uid' => (int)$fileRefData['uid'],
+                'url' => $imageService->getImageUri($default),
+                'title' => $fileRefData['title'] ?? '',
+                'alternative' => $fileRefData['alternative'] ?? '',
+                'description' => $fileRefData['description'] ?? '',
+                'srcset' => $srcset,
+                'properties' => [
+                    'width' => $fileReference->getProperty('width'),
+                    'height' => $fileReference->getProperty('height'),
+                    'mimeType' => $fileReference->getProperty('mime_type'),
+                ],
+            ];
+        } catch (\Exception $e) {
+            return null;
+        }
+    }
+
+    protected function getEventCategories(int $eventUid): array
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        $categories = $qb
+            ->select('c.uid', 'c.title', 'c.description')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid AND mm.tablenames = ' .
+                $qb->createNamedParameter('tx_vitec_domain_model_event', ParameterType::STRING) .
+                ' AND mm.fieldname = ' .
+                $qb->createNamedParameter('categories', ParameterType::STRING)
+            )
+            ->where(
+                $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($eventUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('c.deleted', 0),
+                $qb->expr()->eq('c.hidden', 0)
+            )
+            ->orderBy('mm.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        return array_map(static function ($cat) {
+            return [
+                'uid' => (int)$cat['uid'],
+                'title' => (string)($cat['title'] ?? ''),
+                'description' => (string)($cat['description'] ?? ''),
+            ];
+        }, $categories);
+    }
+}

packages/vitec/Classes/UserFunc/NewsJsonRenderer.php

@@ -0,0 +1,753 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Evomedien\Vitec\UserFunc;
+
+use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\ArrayParameterType;
+use Doctrine\DBAL\ParameterType;
+use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
+use TYPO3\CMS\Core\Database\ConnectionPool;
+use TYPO3\CMS\Core\Resource\ResourceFactory;
+use TYPO3\CMS\Core\Service\FlexFormService;
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+use TYPO3\CMS\Extbase\Service\ImageService;
+
+/**
+ * Headless JSON renderer for EXT:news content elements.
+ *
+ * The renderer supports the news list/detail plugin variants used in this
+ * project and emits a stable JSON structure for the frontend.
+ *
+ * Exception-safe: returns '' on any failure.
+ */
+final class NewsJsonRenderer
+{
+    private const NEWS_CTYPES = [
+        'news_pi1',
+        'news_newsliststicky',
+        'news_newsselectedlist',
+        'news_newsdetail',
+        'news_newsdatemenu',
+        'news_categorylist',
+        'news_newssearchform',
+        'news_newssearchresult',
+        'news_taglist',
+    ];
+
+    private const TEMPLATE_LAYOUTS = [
+        '1' => 'Compact List',
+        '2' => 'Featured Story',
+        '3' => 'Editorial Grid',
+        '4' => 'Detail Spotlight',
+    ];
+
+    private const TEMPLATE_LAYOUT_DEFAULTS = [
+        'news_pi1' => '1',
+        'news_newsliststicky' => '1',
+        'news_newsselectedlist' => '1',
+        'news_newsdetail' => '2',
+        'news_newsdatemenu' => '3',
+        'news_categorylist' => '3',
+        'news_newssearchform' => '4',
+        'news_newssearchresult' => '4',
+        'news_taglist' => '3',
+    ];
+
+    #[AsAllowedCallable]
+    public function render(string $content, array $conf): string
+    {
+        try {
+            $row = is_array($this->cObj->data ?? null) ? $this->cObj->data : null;
+            if ($row !== null && in_array((string)($row['CType'] ?? ''), self::NEWS_CTYPES, true)) {
+                return $this->renderForRecord($row);
+            }
+
+            $pageId = $this->resolveCurrentPageId();
+            if ($pageId <= 0) {
+                return '';
+            }
+
+            $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('tt_content');
+
+            $ctypeConstraints = [];
+            foreach (self::NEWS_CTYPES as $ctype) {
+                $ctypeConstraints[] = $queryBuilder->expr()->eq(
+                    'CType',
+                    $queryBuilder->createNamedParameter($ctype, ParameterType::STRING)
+                );
+            }
+
+            $contentElements = $queryBuilder
+                ->select('*')
+                ->from('tt_content')
+                ->where(
+                    $queryBuilder->expr()->eq('pid', $queryBuilder->createNamedParameter($pageId, ParameterType::INTEGER)),
+                    $queryBuilder->expr()->or(...$ctypeConstraints),
+                    $queryBuilder->expr()->eq('deleted', 0),
+                    $queryBuilder->expr()->eq('hidden', 0)
+                )
+                ->orderBy('sorting', 'ASC')
+                ->executeQuery()
+                ->fetchAllAssociative();
+
+            if ($contentElements === []) {
+                return '';
+            }
+
+            return $this->renderForRecord($contentElements[0]);
+        } catch (\Throwable $e) {
+            return '';
+        }
+    }
+
+    /**
+     * Render exactly the given news tt_content row.
+     *
+     * @param array<string,mixed> $contentElement
+     */
+    public function renderForRecord(array $contentElement): string
+    {
+        try {
+            $flexFormService = GeneralUtility::makeInstance(FlexFormService::class);
+            $flexFormData = $flexFormService->convertFlexFormContentToArray($contentElement['pi_flexform'] ?? '');
+            $settings = $flexFormData['settings'] ?? [];
+
+            $type = (string)($contentElement['CType'] ?? '');
+            $mode = $type === 'news_newsdetail' ? 'detail' : 'list';
+            $debug = (bool)($settings['debug'] ?? false);
+
+            if ($mode === 'detail') {
+                $news = $this->resolveDetailNews($contentElement, $settings);
+                $response = [
+                    'mode' => 'detail',
+                    'news' => $news !== null ? $this->serializeNews($news, $settings) : null,
+                    'settings' => $this->buildSettingsPayload($contentElement, $settings),
+                ];
+
+                if ($debug) {
+                    $response['debug'] = [
+                        'contentElementUid' => (int)($contentElement['uid'] ?? 0),
+                        'settings' => $settings,
+                    ];
+                }
+
+                return json_encode($response) ?: '';
+            }
+
+            $newsRows = $this->fetchNewsList($contentElement, $settings);
+            $items = array_map(fn (array $newsRow): array => $this->serializeNews($newsRow, $settings), $newsRows);
+
+            $response = [
+                'mode' => 'list',
+                'items' => $items,
+                'settings' => $this->buildSettingsPayload($contentElement, $settings),
+            ];
+
+            if ($debug) {
+                $response['debug'] = [
+                    'contentElementUid' => (int)($contentElement['uid'] ?? 0),
+                    'count' => count($items),
+                    'settings' => $settings,
+                ];
+            }
+
+            return json_encode($response) ?: '';
+        } catch (\Throwable $e) {
+            return json_encode([
+                'mode' => 'error',
+                'message' => $e->getMessage(),
+            ]) ?: '';
+        }
+    }
+
+    /**
+     * @param array<string,mixed> $contentElement
+     * @param array<string,mixed> $settings
+     * @return array<string,mixed>|null
+     */
+    private function resolveDetailNews(array $contentElement, array $settings): ?array
+    {
+        $newsUid = $this->resolveNewsUid((string)($settings['singleNews'] ?? ''));
+        if ($newsUid <= 0) {
+            $queryParams = $GLOBALS['TYPO3_REQUEST']?->getQueryParams() ?? [];
+            $newsParam = $queryParams['tx_news_pi1']['news'] ?? null;
+            $newsUid = $this->resolveNewsUid((string)($newsParam ?? ''));
+        }
+
+        if ($newsUid > 0) {
+            $news = $this->fetchNewsByUid($newsUid, (int)($contentElement['sys_language_uid'] ?? 0));
+            if ($news !== null) {
+                return $news;
+            }
+        }
+
+        $list = $this->fetchNewsList($contentElement, $settings, 1);
+        return $list[0] ?? null;
+    }
+
+    /**
+     * @param array<string,mixed> $contentElement
+     * @param array<string,mixed> $settings
+     * @param int|null $limitOverride
+     * @return array<int,array<string,mixed>>
+     */
+    private function fetchNewsList(array $contentElement, array $settings, ?int $limitOverride = null): array
+    {
+        $selectedNews = $this->parseUidList((string)($settings['selectedList'] ?? ''));
+        $storagePids = $this->parseUidList((string)($settings['startingpoint'] ?? ''));
+        if ($storagePids === []) {
+            $storagePids = [(int)($contentElement['pid'] ?? 0)];
+        }
+
+        $categoryUids = $this->parseUidList((string)($settings['categories'] ?? ''));
+        $includeSubCategories = (bool)($settings['includeSubCategories'] ?? false);
+        $tagUids = $this->parseUidList((string)($settings['tags'] ?? ''));
+        $limit = $limitOverride ?? (int)($settings['limit'] ?? 0);
+        $orderDirection = strtoupper((string)($settings['orderDirection'] ?? 'DESC')) === 'ASC' ? 'ASC' : 'DESC';
+        $topNewsFirst = (bool)($settings['topNewsFirst'] ?? false);
+        $searchTerm = $this->resolveSearchTerm((string)($contentElement['CType'] ?? ''));
+        $languageUid = (int)($contentElement['sys_language_uid'] ?? 0);
+
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_news_domain_model_news');
+
+        $rows = $queryBuilder
+            ->select('n.*')
+            ->from('tx_news_domain_model_news', 'n')
+            ->where(
+                $queryBuilder->expr()->eq('n.deleted', 0),
+                $queryBuilder->expr()->eq('n.hidden', 0),
+                $queryBuilder->expr()->in('n.pid', $queryBuilder->createNamedParameter($storagePids, ArrayParameterType::INTEGER))
+            )
+            ->orderBy('n.istopnews', $topNewsFirst ? 'DESC' : 'ASC')
+            ->addOrderBy('n.datetime', 'DESC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        if ($languageUid > 0) {
+            $rows = array_values(array_filter($rows, static fn (array $row): bool => (int)($row['sys_language_uid'] ?? 0) === $languageUid));
+        } else {
+            $rows = array_values(array_filter($rows, static fn (array $row): bool => in_array((int)($row['sys_language_uid'] ?? 0), [0, -1], true)));
+        }
+
+        if ($selectedNews !== []) {
+            $selectedLookup = array_fill_keys($selectedNews, true);
+            $rows = array_values(array_filter($rows, static fn (array $row): bool => isset($selectedLookup[(int)($row['uid'] ?? 0)])));
+        }
+
+        if ($categoryUids !== []) {
+            $categoryLookup = $this->newsUidsForCategories($categoryUids, $includeSubCategories);
+            if ($categoryLookup === [] && !$includeSubCategories) {
+                $categoryLookup = $this->newsUidsForCategories($this->expandCategoryUids($categoryUids), true);
+            }
+
+            if ($categoryLookup !== []) {
+                $rows = array_values(array_filter($rows, static fn (array $row): bool => isset($categoryLookup[(int)($row['uid'] ?? 0)])));
+            }
+        }
+
+        if ($tagUids !== []) {
+            $tagLookup = $this->newsUidsForTags($tagUids);
+            if ($tagLookup !== []) {
+                $rows = array_values(array_filter($rows, static fn (array $row): bool => isset($tagLookup[(int)($row['uid'] ?? 0)])));
+            }
+        }
+
+        if ($searchTerm !== '') {
+            $needle = mb_strtolower($searchTerm);
+            $rows = array_values(array_filter($rows, static function (array $row) use ($needle): bool {
+                $haystack = mb_strtolower((string)($row['title'] ?? '') . ' ' . (string)($row['teaser'] ?? '') . ' ' . (string)($row['path_segment'] ?? ''));
+                return str_contains($haystack, $needle);
+            }));
+        }
+
+        if ($limit > 0) {
+            $rows = array_slice($rows, 0, $limit);
+        }
+
+        return $rows;
+    }
+
+    /**
+     * @param int $newsUid
+     * @param int $languageUid
+     * @return array<string,mixed>|null
+     */
+    private function fetchNewsByUid(int $newsUid, int $languageUid): ?array
+    {
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_news_domain_model_news');
+
+        $query = $queryBuilder
+            ->select('n.*')
+            ->from('tx_news_domain_model_news', 'n')
+            ->where(
+                $queryBuilder->expr()->eq('n.uid', $queryBuilder->createNamedParameter($newsUid, ParameterType::INTEGER)),
+                $queryBuilder->expr()->eq('n.deleted', 0),
+                $queryBuilder->expr()->eq('n.hidden', 0)
+            );
+
+        if ($languageUid > 0) {
+            $query->andWhere(
+                $queryBuilder->expr()->eq('n.sys_language_uid', $queryBuilder->createNamedParameter($languageUid, ParameterType::INTEGER))
+            );
+        }
+
+        $news = $query->executeQuery()->fetchAssociative();
+        return is_array($news) ? $news : null;
+    }
+
+    /**
+     * @param array<string,mixed> $news
+     * @param array<string,mixed> $settings
+     * @return array<string,mixed>
+     */
+    private function serializeNews(array $news, array $settings = []): array
+    {
+        $uid = (int)($news['uid'] ?? 0);
+        $pathSegment = (string)($news['path_segment'] ?? '');
+        $urls = $this->buildNewsUrls($pathSegment, $settings);
+
+        return [
+            'uid' => $uid,
+            'title' => (string)($news['title'] ?? ''),
+            'alternativeTitle' => (string)($news['alternative_title'] ?? ''),
+            'pathSegment' => $pathSegment,
+            'detailUrl' => $urls['detailUrl'],
+            'canonicalUrl' => $urls['canonicalUrl'],
+            'teaser' => (string)($news['teaser'] ?? ''),
+            'bodytext' => (string)($news['bodytext'] ?? ''),
+            'datetime' => (int)($news['datetime'] ?? 0),
+            'archive' => (int)($news['archive'] ?? 0),
+            'istopnews' => (bool)($news['istopnews'] ?? false),
+            'author' => (string)($news['author'] ?? ''),
+            'authorEmail' => (string)($news['author_email'] ?? ''),
+            'categories' => $this->resolveCategories($uid),
+            'tags' => $this->resolveTags($uid),
+            'media' => $this->resolveFiles('tx_news_domain_model_news', 'fal_media', $uid),
+            'relatedFiles' => $this->resolveFiles('tx_news_domain_model_news', 'fal_related_files', $uid),
+            'related' => $this->resolveRelatedNews($uid),
+            'relatedLinks' => $this->resolveRelatedLinks($uid),
+        ];
+    }
+
+    /**
+     * @param array<string,mixed> $settings
+     * @return array{detailUrl:string, canonicalUrl:string}
+     */
+    private function buildNewsUrls(string $pathSegment, array $settings): array
+    {
+        $pathSegment = trim($pathSegment, '/');
+        if ($pathSegment === '') {
+            return ['detailUrl' => '', 'canonicalUrl' => ''];
+        }
+
+        $detailPid = (int)($settings['detailPid'] ?? 0);
+        if ($detailPid <= 0) {
+            $detailPid = $this->resolveCurrentPageId();
+        }
+        $detailPageSlug = $detailPid > 0 ? $this->resolvePageSlug($detailPid) : '';
+        if ($detailPageSlug === '') {
+            return ['detailUrl' => '', 'canonicalUrl' => ''];
+        }
+
+        $detailUrl = rtrim($detailPageSlug, '/') . '/' . $pathSegment;
+        $canonicalUrl = $this->absoluteUrl($detailUrl);
+
+        return [
+            'detailUrl' => $detailUrl,
+            'canonicalUrl' => $canonicalUrl,
+        ];
+    }
+
+    private function resolvePageSlug(int $pageId): string
+    {
+        if ($pageId <= 0) {
+            return '';
+        }
+
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('pages');
+
+        $row = $queryBuilder
+            ->select('slug')
+            ->from('pages')
+            ->where(
+                $queryBuilder->expr()->eq('uid', $queryBuilder->createNamedParameter($pageId, ParameterType::INTEGER)),
+                $queryBuilder->expr()->eq('deleted', 0),
+                $queryBuilder->expr()->eq('hidden', 0)
+            )
+            ->executeQuery()
+            ->fetchAssociative();
+
+        return (string)($row['slug'] ?? '');
+    }
+
+    private function absoluteUrl(string $path): string
+    {
+        $path = '/' . ltrim($path, '/');
+
+        $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
+        if ($request !== null) {
+            $normalizedParams = $request->getAttribute('normalizedParams');
+            if ($normalizedParams !== null) {
+                return rtrim($normalizedParams->getSiteUrl(), '/') . $path;
+            }
+        }
+
+        $site = $request?->getAttribute('site');
+        if ($site !== null) {
+            return rtrim((string)$site->getBase(), '/') . $path;
+        }
+
+        return $path;
+    }
+
+    /**
+     * @return array<int,array<string,mixed>>
+     */
+    private function resolveCategories(int $newsUid): array
+    {
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        return $queryBuilder
+            ->select('c.uid', 'c.title')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid'
+            )
+            ->where(
+                $queryBuilder->expr()->eq('mm.uid_foreign', $queryBuilder->createNamedParameter($newsUid, ParameterType::INTEGER)),
+                $queryBuilder->expr()->eq('mm.tablenames', $queryBuilder->createNamedParameter('tx_news_domain_model_news', ParameterType::STRING)),
+                $queryBuilder->expr()->eq('mm.fieldname', $queryBuilder->createNamedParameter('categories', ParameterType::STRING))
+            )
+            ->orderBy('c.title', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+    }
+
+    /**
+     * @return array<int,array<string,mixed>>
+     */
+    private function resolveTags(int $newsUid): array
+    {
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_news_domain_model_tag');
+
+        return $queryBuilder
+            ->select('t.uid', 't.title')
+            ->from('tx_news_domain_model_tag', 't')
+            ->join(
+                't',
+                'tx_news_domain_model_news_tag_mm',
+                'mm',
+                'mm.uid_foreign = t.uid'
+            )
+            ->where(
+                $queryBuilder->expr()->eq('mm.uid_local', $queryBuilder->createNamedParameter($newsUid, ParameterType::INTEGER))
+            )
+            ->orderBy('t.title', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+    }
+
+    /**
+     * @param list<int> $categoryUids
+     * @return array<int,true>
+     */
+    private function newsUidsForCategories(array $categoryUids, bool $includeSubCategories): array
+    {
+        if ($categoryUids === []) {
+            return [];
+        }
+
+        $categories = $includeSubCategories ? $this->expandCategoryUids($categoryUids) : $categoryUids;
+        if ($categories === []) {
+            return [];
+        }
+
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category_record_mm');
+
+        $uids = $queryBuilder
+            ->select('uid_foreign')
+            ->from('sys_category_record_mm')
+            ->where(
+                $queryBuilder->expr()->eq('tablenames', $queryBuilder->createNamedParameter('tx_news_domain_model_news', ParameterType::STRING)),
+                $queryBuilder->expr()->eq('fieldname', $queryBuilder->createNamedParameter('categories', ParameterType::STRING)),
+                $queryBuilder->expr()->in('uid_local', $queryBuilder->createNamedParameter($categories, ArrayParameterType::INTEGER))
+            )
+            ->executeQuery()
+            ->fetchFirstColumn();
+
+        return array_fill_keys(array_map('intval', $uids), true);
+    }
+
+    /**
+     * @param list<int> $tagUids
+     * @return array<int,true>
+     */
+    private function newsUidsForTags(array $tagUids): array
+    {
+        if ($tagUids === []) {
+            return [];
+        }
+
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_news_domain_model_news_tag_mm');
+
+        $uids = $queryBuilder
+            ->select('uid_local')
+            ->from('tx_news_domain_model_news_tag_mm')
+            ->where(
+                $queryBuilder->expr()->in('uid_foreign', $queryBuilder->createNamedParameter($tagUids, ArrayParameterType::INTEGER))
+            )
+            ->executeQuery()
+            ->fetchFirstColumn();
+
+        return array_fill_keys(array_map('intval', $uids), true);
+    }
+
+    /**
+     * @return array<int,array<string,mixed>>
+     */
+    private function resolveRelatedNews(int $newsUid): array
+    {
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_news_domain_model_news');
+
+        return $queryBuilder
+            ->select('n.uid', 'n.title', 'n.path_segment')
+            ->from('tx_news_domain_model_news', 'n')
+            ->join(
+                'n',
+                'tx_news_domain_model_news_related_mm',
+                'mm',
+                'mm.uid_foreign = n.uid'
+            )
+            ->where(
+                $queryBuilder->expr()->eq('mm.uid_local', $queryBuilder->createNamedParameter($newsUid, ParameterType::INTEGER)),
+                $queryBuilder->expr()->eq('n.deleted', 0),
+                $queryBuilder->expr()->eq('n.hidden', 0)
+            )
+            ->orderBy('n.datetime', 'DESC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+    }
+
+    /**
+     * @return array<int,array<string,mixed>>
+     */
+    private function resolveRelatedLinks(int $newsUid): array
+    {
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_news_domain_model_link');
+
+        return $queryBuilder
+            ->select('l.uid', 'l.title', 'l.description', 'l.uri')
+            ->from('tx_news_domain_model_link', 'l')
+            ->where(
+                $queryBuilder->expr()->eq('l.parent', $queryBuilder->createNamedParameter($newsUid, ParameterType::INTEGER)),
+                $queryBuilder->expr()->eq('l.deleted', 0),
+                $queryBuilder->expr()->eq('l.hidden', 0)
+            )
+            ->orderBy('l.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+    }
+
+    /**
+     * @return array<int,array<string,mixed>>
+     */
+    private function resolveFiles(string $tableName, string $fieldName, int $uid): array
+    {
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_file_reference');
+
+        $rows = $queryBuilder
+            ->select('uid')
+            ->from('sys_file_reference')
+            ->where(
+                $queryBuilder->expr()->eq('uid_foreign', $queryBuilder->createNamedParameter($uid, ParameterType::INTEGER)),
+                $queryBuilder->expr()->eq('tablenames', $queryBuilder->createNamedParameter($tableName, ParameterType::STRING)),
+                $queryBuilder->expr()->eq('fieldname', $queryBuilder->createNamedParameter($fieldName, ParameterType::STRING)),
+                $queryBuilder->expr()->eq('deleted', 0),
+                $queryBuilder->expr()->eq('hidden', 0)
+            )
+            ->orderBy('sorting_foreign', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        if ($rows === []) {
+            return [];
+        }
+
+        $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
+        $imageService = GeneralUtility::makeInstance(ImageService::class);
+        $files = [];
+
+        foreach ($rows as $row) {
+            try {
+                $fileReference = $resourceFactory->getFileReferenceObject((int)$row['uid']);
+                $processed = $imageService->applyProcessingInstructions($fileReference, ['width' => 1400]);
+
+                $files[] = [
+                    'uid' => (int)$row['uid'],
+                    'url' => $imageService->getImageUri($processed),
+                ];
+            } catch (\Throwable $e) {
+                continue;
+            }
+        }
+
+        return $files;
+    }
+
+    private function resolveNewsUid(string $rawValue): int
+    {
+        $rawValue = trim($rawValue);
+        if ($rawValue === '') {
+            return 0;
+        }
+
+        if (ctype_digit($rawValue)) {
+            return (int)$rawValue;
+        }
+
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('tx_news_domain_model_news');
+
+        $row = $queryBuilder
+            ->select('uid')
+            ->from('tx_news_domain_model_news')
+            ->where(
+                $queryBuilder->expr()->eq('path_segment', $queryBuilder->createNamedParameter($rawValue, ParameterType::STRING)),
+                $queryBuilder->expr()->eq('deleted', 0),
+                $queryBuilder->expr()->eq('hidden', 0)
+            )
+            ->executeQuery()
+            ->fetchAssociative();
+
+        return (int)($row['uid'] ?? 0);
+    }
+
+    /**
+     * @return list<int>
+     */
+    private function parseUidList(string $rawValue): array
+    {
+        $values = array_filter(array_map('trim', explode(',', $rawValue)));
+
+        return array_values(array_filter(array_map(static fn (string $value): int => (int)$value, $values)));
+    }
+
+    /**
+     * @param list<int> $categoryUids
+     * @return list<int>
+     */
+    private function expandCategoryUids(array $categoryUids): array
+    {
+        if ($categoryUids === []) {
+            return [];
+        }
+
+        $allUids = array_fill_keys($categoryUids, true);
+        $queue = $categoryUids;
+
+        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        while ($queue !== []) {
+            $currentUid = array_shift($queue);
+            if ($currentUid === null) {
+                continue;
+            }
+
+            $children = $queryBuilder
+                ->select('uid')
+                ->from('sys_category')
+                ->where(
+                    $queryBuilder->expr()->eq('parent', $queryBuilder->createNamedParameter($currentUid, ParameterType::INTEGER)),
+                    $queryBuilder->expr()->eq('deleted', 0)
+                )
+                ->executeQuery()
+                ->fetchFirstColumn();
+
+            foreach ($children as $childUid) {
+                $childUid = (int)$childUid;
+                if ($childUid <= 0 || isset($allUids[$childUid])) {
+                    continue;
+                }
+
+                $allUids[$childUid] = true;
+                $queue[] = $childUid;
+            }
+        }
+
+        return array_values(array_map('intval', array_keys($allUids)));
+    }
+
+    private function resolveCurrentPageId(): int
+    {
+        $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
+        if ($request !== null) {
+            $pageInfo = $request->getAttribute('frontend.page.information');
+            if ($pageInfo !== null) {
+                return (int)$pageInfo->getId();
+            }
+        }
+
+        return (int)($GLOBALS['TSFE']->id ?? 0);
+    }
+
+    /**
+     * @param array<string,mixed> $contentElement
+     * @param array<string,mixed> $settings
+     * @return array<string,mixed>
+     */
+    private function buildSettingsPayload(array $contentElement, array $settings): array
+    {
+        $payload = $settings;
+        $payload['type'] = (string)($contentElement['CType'] ?? '');
+        $payload['detailPid'] = (int)($settings['detailPid'] ?? 0);
+        $payload['listPid'] = (int)($settings['listPid'] ?? 0);
+        $payload['templateLayout'] = $this->resolveTemplateLayoutValue((string)($contentElement['CType'] ?? ''), (string)($settings['templateLayout'] ?? ''));
+        $payload['templateLayoutLabel'] = self::TEMPLATE_LAYOUTS[$payload['templateLayout']] ?? '';
+        $payload['templateLayouts'] = array_map(
+            static fn (string $label, string $key): array => ['key' => $key, 'label' => $label],
+            self::TEMPLATE_LAYOUTS,
+            array_keys(self::TEMPLATE_LAYOUTS)
+        );
+
+        return $payload;
+    }
+
+    private function resolveTemplateLayoutValue(string $type, string $value): string
+    {
+        $value = trim($value);
+        if ($value !== '' && isset(self::TEMPLATE_LAYOUTS[$value])) {
+            return $value;
+        }
+
+        return self::TEMPLATE_LAYOUT_DEFAULTS[$type] ?? '';
+    }
+
+    private function resolveSearchTerm(string $type): string
+    {
+        if ($type !== 'news_newssearchresult') {
+            return '';
+        }
+
+        $queryParams = $GLOBALS['TYPO3_REQUEST']?->getQueryParams() ?? [];
+        $search = $queryParams['tx_news_pi1']['search']['sword'] ?? '';
+
+        return trim((string)$search);
+    }
+}

packages/vitec/Classes/UserFunc/PageJsonLdRenderer.php

@@ -93,6 +93,24 @@ final class PageJsonLdRenderer
                     $hasOrganization
                 );
             }
+            // FAQPage when the page contains at least one vitec_faq element.
+            $faqItems = $this->collectFaqItems($pageId);
+            if ($faqItems !== []) {
+                $nodes[] = $service->buildFaqPage($faqItems, $base);
+            }
+            // Event nodes when the page contains a vitec_eventlist element.
+            foreach ($this->collectUpcomingEvents($pageId) as $eventRow) {
+                $nodes[] = $service->buildEvent(
+                    $eventRow,
+                    $base,
+                    $this->eventImageUrls((int)$eventRow['uid'], $base, $service),
+                    $hasOrganization
+                );
+            }
+
+
+
+
 
             return $service->encodeGraph($nodes);
         } catch (\Throwable $e) {
@@ -225,4 +243,171 @@ final class PageJsonLdRenderer
 
         return $urls;
     }
+
+    /**
+     * Collect question/answer pairs from all visible vitec_faq elements on
+     * this page (Content Blocks collection child table).
+     *
+     * @return list<array{question:string,answer:string}>
+     */
+    private function collectFaqItems(int $pageId): array
+    {
+        try {
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('tt_content');
+            $elements = $qb
+                ->select('uid')
+                ->from('tt_content')
+                ->where(
+                    $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
+                    $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_faq', ParameterType::STRING)),
+                    $qb->expr()->eq('deleted', 0),
+                    $qb->expr()->eq('hidden', 0)
+                )
+                ->executeQuery()
+                ->fetchAllAssociative();
+
+            if ($elements === []) {
+                return [];
+            }
+
+            $items = [];
+            foreach ($elements as $element) {
+                $childQb = GeneralUtility::makeInstance(ConnectionPool::class)
+                    ->getQueryBuilderForTable('vitec_faq_items');
+                $rows = $childQb
+                    ->select('*')
+                    ->from('vitec_faq_items')
+                    ->where(
+                        $childQb->expr()->eq('foreign_table_parent_uid', $childQb->createNamedParameter((int)$element['uid'], ParameterType::INTEGER)),
+                        $childQb->expr()->eq('deleted', 0),
+                        $childQb->expr()->eq('hidden', 0)
+                    )
+                    ->orderBy('sorting', 'ASC')
+                    ->executeQuery()
+                    ->fetchAllAssociative();
+
+                foreach ($rows as $row) {
+                    $items[] = [
+                        'question' => (string)($row['question'] ?? $row['vitec_question'] ?? ''),
+                        'answer' => (string)($row['answer'] ?? $row['vitec_answer'] ?? ''),
+                    ];
+                }
+            }
+
+            return $items;
+        } catch (\Throwable $e) {
+            // Table may not exist yet (schema not updated) — skip silently.
+            return [];
+        }
+    }
+
+
+    /**
+     * Upcoming event rows when this page contains at least one visible
+     * vitec_eventlist element. Empty array otherwise.
+     *
+     * @return list<array<string,mixed>>
+     */
+    private function collectUpcomingEvents(int $pageId): array
+    {
+        try {
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('tt_content');
+            $eventlistElement = $qb
+                ->select('uid', 'pi_flexform')
+                ->from('tt_content')
+                ->where(
+                    $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
+                    $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_eventlist', ParameterType::STRING)),
+                    $qb->expr()->eq('deleted', 0),
+                    $qb->expr()->eq('hidden', 0)
+                )
+                ->setMaxResults(1)
+                ->executeQuery()
+                ->fetchAssociative();
+
+            if (!$eventlistElement) {
+                return [];
+            }
+
+            // Mirror the plugin's "days in advance" window so structured data
+            // matches what the page actually shows.
+            $daysInAdvance = 0;
+            $flexFormService = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Service\FlexFormService::class);
+            $flexSettings = $flexFormService->convertFlexFormContentToArray((string)($eventlistElement['pi_flexform'] ?? ''))['settings'] ?? [];
+            $daysInAdvance = (int)($flexSettings['daysinadvance'] ?? 0);
+
+            $todayMidnight = strtotime('today');
+            $eventQb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('tx_vitec_domain_model_event');
+            $expr = $eventQb->expr();
+
+            $eventQb
+                ->select('*')
+                ->from('tx_vitec_domain_model_event')
+                ->where(
+                    $expr->eq('deleted', 0),
+                    $expr->eq('hidden', 0),
+                    $expr->eq('hideonwebsite', 0),
+                    $expr->or(
+                        $expr->gte('eventend', $eventQb->createNamedParameter($todayMidnight, ParameterType::INTEGER)),
+                        $expr->and(
+                            $expr->eq('eventend', 0),
+                            $expr->gte('eventstart', $eventQb->createNamedParameter($todayMidnight, ParameterType::INTEGER))
+                        )
+                    )
+                )
+                ->orderBy('eventstart', 'ASC');
+
+            if ($daysInAdvance > 0) {
+                $eventQb->andWhere(
+                    $expr->lt('eventstart', $eventQb->createNamedParameter($todayMidnight + ($daysInAdvance * 86400), ParameterType::INTEGER))
+                );
+            }
+
+            return $eventQb->executeQuery()->fetchAllAssociative();
+        } catch (\Throwable $e) {
+            // Table may not exist yet — skip silently.
+            return [];
+        }
+    }
+
+    /**
+     * Root-relative logo URLs for an event (fieldname=image).
+     *
+     * @return list<string>
+     */
+    private function eventImageUrls(int $eventUid, string $base, $service): array
+    {
+        try {
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+                ->getQueryBuilderForTable('sys_file_reference');
+            $rows = $qb
+                ->select('f.identifier')
+                ->from('sys_file_reference', 'fr')
+                ->join('fr', 'sys_file', 'f', 'fr.uid_local = f.uid')
+                ->where(
+                    $qb->expr()->eq('fr.tablenames', $qb->createNamedParameter('tx_vitec_domain_model_event', ParameterType::STRING)),
+                    $qb->expr()->eq('fr.fieldname', $qb->createNamedParameter('image', ParameterType::STRING)),
+                    $qb->expr()->eq('fr.uid_foreign', $qb->createNamedParameter($eventUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('fr.deleted', 0),
+                    $qb->expr()->eq('f.missing', 0)
+                )
+                ->executeQuery()
+                ->fetchAllAssociative();
+
+            $urls = [];
+            foreach ($rows as $row) {
+                $identifier = (string)($row['identifier'] ?? '');
+                if ($identifier !== '') {
+                    $urls[] = '/fileadmin' . $identifier;
+                }
+            }
+            return $urls;
+        } catch (\Throwable $e) {
+            return [];
+        }
+    }
+
 }

packages/vitec/Classes/UserFunc/ProductListJsonRenderer.php

@@ -9,6 +9,7 @@ use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
 use Evomedien\Vitec\Domain\Repository\ProductRepository;
 use Psr\Http\Message\ServerRequestInterface;
+use TYPO3\CMS\Core\Core\Environment;
 use TYPO3\CMS\Core\Database\Connection;
 use TYPO3\CMS\Core\Imaging\ImageManipulation\CropVariantCollection;
 use TYPO3\CMS\Core\Resource\FileReference;
@@ -141,6 +142,7 @@ class ProductListJsonRenderer
                         'categoryUids' => $categoryUids,
                         'productCount' => count($productsData),
                         'settings' => $settings,
+                        'fallbackFiles' => $this->collectFallbackFilesFromProducts($productsData),
                     ],
                 ]);
             }
@@ -413,6 +415,168 @@ class ProductListJsonRenderer
         }, $categories);
     }
 
+    private function getDownloadFileType(int $downloadUid): string
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        $categories = $qb
+            ->select('c.filetype')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid AND mm.tablenames = ' .
+                $qb->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING) .
+                ' AND mm.fieldname = ' .
+                $qb->createNamedParameter('categories', ParameterType::STRING)
+            )
+            ->where(
+                $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($downloadUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('c.deleted', 0),
+                $qb->expr()->eq('c.hidden', 0),
+                $qb->expr()->eq('c.parent', $qb->createNamedParameter(4, ParameterType::INTEGER))
+            )
+            ->orderBy('mm.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        foreach ($categories as $category) {
+            $filetype = trim((string)($category['filetype'] ?? ''));
+            if ($filetype !== '') {
+                return $filetype;
+            }
+        }
+
+        return '';
+    }
+
+    /**
+     * @return array<string,mixed>|null
+     */
+    private function resolveFileByConvention(string $fileprefix, string $filetype): ?array
+    {
+        $fileprefix = trim($fileprefix);
+        $filetype = trim($filetype);
+        if ($fileprefix === '' || $filetype === '') {
+            return null;
+        }
+
+        $baseDir = Environment::getPublicPath() . '/fileadmin/downloads/Collateral';
+        if (!is_dir($baseDir) || !is_readable($baseDir)) {
+            return null;
+        }
+
+        $escapedPrefix = preg_quote($fileprefix, '/');
+        $escapedType = preg_quote($filetype, '/');
+        $pattern = '/^' . $escapedPrefix . '__' . $escapedType . '__(\\d+)-([A-Za-z]+)\\.([A-Za-z0-9]+)$/';
+
+        $bestFile = null;
+        $bestNumber = -1;
+        $bestLetterRank = -1;
+
+        $entries = scandir($baseDir);
+        if ($entries === false) {
+            return null;
+        }
+
+        foreach ($entries as $entry) {
+            if (!is_string($entry) || $entry === '.' || $entry === '..') {
+                continue;
+            }
+
+            if (!preg_match($pattern, $entry, $matches)) {
+                continue;
+            }
+
+            $number = (int)$matches[1];
+            $letterRank = $this->letterSequenceToRank((string)$matches[2]);
+
+            if ($number > $bestNumber || ($number === $bestNumber && $letterRank > $bestLetterRank)) {
+                $bestNumber = $number;
+                $bestLetterRank = $letterRank;
+                $bestFile = $entry;
+            }
+        }
+
+        if ($bestFile === null) {
+            return null;
+        }
+
+        $fullPath = $baseDir . '/' . $bestFile;
+        if (!is_file($fullPath) || !is_readable($fullPath)) {
+            return null;
+        }
+
+        $extension = strtolower(pathinfo($bestFile, PATHINFO_EXTENSION));
+        $mimeType = function_exists('mime_content_type') ? (string)(mime_content_type($fullPath) ?: '') : '';
+
+        return [
+            'uid' => 0,
+            'name' => $bestFile,
+            'url' => '/fileadmin/downloads/Collateral/' . rawurlencode($bestFile),
+            'size' => (int)(filesize($fullPath) ?: 0),
+            'extension' => $extension,
+            'mimeType' => $mimeType,
+        ];
+    }
+
+    private function letterSequenceToRank(string $letters): int
+    {
+        $rank = 0;
+        $letters = strtoupper($letters);
+        $length = strlen($letters);
+
+        for ($i = 0; $i < $length; $i++) {
+            $char = ord($letters[$i]);
+            if ($char < 65 || $char > 90) {
+                continue;
+            }
+
+            $rank = ($rank * 26) + ($char - 64);
+        }
+
+        return $rank;
+    }
+
+    /**
+     * @param array<int,array<string,mixed>> $products
+     * @return array<int,array<string,mixed>>
+     */
+    private function collectFallbackFilesFromProducts(array $products): array
+    {
+        $fallbackFiles = [];
+
+        foreach ($products as $product) {
+            $downloads = $product['downloads'] ?? null;
+            if (!is_array($downloads)) {
+                continue;
+            }
+
+            foreach ($downloads as $download) {
+                if (!is_array($download)) {
+                    continue;
+                }
+
+                $file = $download['file'] ?? null;
+                if (!is_array($file) || (int)($file['uid'] ?? 1) !== 0) {
+                    continue;
+                }
+
+                $fallbackFiles[] = [
+                    'productUid' => (int)($product['uid'] ?? 0),
+                    'downloadUid' => (int)($download['uid'] ?? 0),
+                    'name' => (string)($file['name'] ?? ''),
+                    'url' => (string)($file['url'] ?? ''),
+                    'source' => 'naming-convention-fallback',
+                ];
+            }
+        }
+
+        return $fallbackFiles;
+    }
+
     protected function getProductDownloads(int $productUid): array
     {
         $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
@@ -440,6 +604,9 @@ class ProductListJsonRenderer
         $result = [];
         foreach ($downloads as $download) {
             $fileInfo = null;
+            $downloadUid = (int)$download['uid'];
+            $fileprefix = (string)($download['fileprefix'] ?? '');
+            $filetype = $this->getDownloadFileType($downloadUid);
 
             if (!empty($download['file'])) {
                 $fileQueryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
@@ -450,7 +617,7 @@ class ProductListJsonRenderer
                     ->from('sys_file_reference', 'fr')
                     ->join('fr', 'sys_file', 'f', 'fr.uid_local = f.uid')
                     ->where(
-                        $fileQueryBuilder->expr()->eq('fr.uid_foreign', $fileQueryBuilder->createNamedParameter((int)$download['uid'], ParameterType::INTEGER)),
+                        $fileQueryBuilder->expr()->eq('fr.uid_foreign', $fileQueryBuilder->createNamedParameter($downloadUid, ParameterType::INTEGER)),
                         $fileQueryBuilder->expr()->eq('fr.tablenames', $fileQueryBuilder->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING)),
                         $fileQueryBuilder->expr()->eq('fr.fieldname', $fileQueryBuilder->createNamedParameter('file', ParameterType::STRING)),
                         $fileQueryBuilder->expr()->eq('fr.deleted', 0),
@@ -473,14 +640,20 @@ class ProductListJsonRenderer
                 }
             }
 
+            if ($fileInfo === null) {
+                $fileInfo = $this->resolveFileByConvention($fileprefix, $filetype);
+            }
+
             $result[] = [
-                'uid' => (int)$download['uid'],
+                'uid' => $downloadUid,
                 'title' => $download['title'] ?? '',
                 'slug' => $download['slug'] ?? '',
                 'teaser' => $download['teaser'] ?? '',
                 'description' => $download['description'] ?? '',
                 'keywords' => $download['keywords'] ?? '',
                 'icon' => $download['icon'] ?? '',
+                'fileprefix' => $fileprefix,
+                'filetype' => $filetype,
                 'file' => $fileInfo,
             ];
         }

packages/vitec/Classes/UserFunc/ProductShowJsonRenderer.php

@@ -7,6 +7,7 @@ namespace Evomedien\Vitec\UserFunc;
 
 use Evomedien\Vitec\Service\StructuredDataService;
 use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
+use TYPO3\CMS\Core\Core\Environment;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Service\FlexFormService;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
@@ -160,6 +161,7 @@ class ProductShowJsonRenderer
                     'productUid' => $productUid,
                     'layout' => $layout,
                     'settings' => $settings,
+                    'fallbackFiles' => $this->collectFallbackFilesFromDownloads((array)($response['product']['downloads'] ?? [])),
                 ];
             }
 
@@ -495,6 +497,160 @@ class ProductShowJsonRenderer
         }, $categories);
     }
 
+    private function getDownloadFileType(int $downloadUid): string
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        $categories = $qb
+            ->select('c.filetype')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid AND mm.tablenames = ' .
+                $qb->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING) .
+                ' AND mm.fieldname = ' .
+                $qb->createNamedParameter('categories', ParameterType::STRING)
+            )
+            ->where(
+                $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($downloadUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('c.deleted', 0),
+                $qb->expr()->eq('c.hidden', 0),
+                $qb->expr()->eq('c.parent', $qb->createNamedParameter(4, ParameterType::INTEGER))
+            )
+            ->orderBy('mm.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        foreach ($categories as $category) {
+            $filetype = trim((string)($category['filetype'] ?? ''));
+            if ($filetype !== '') {
+                return $filetype;
+            }
+        }
+
+        return '';
+    }
+
+    /**
+     * @return array<string,mixed>|null
+     */
+    private function resolveFileByConvention(string $fileprefix, string $filetype): ?array
+    {
+        $fileprefix = trim($fileprefix);
+        $filetype = trim($filetype);
+        if ($fileprefix === '' || $filetype === '') {
+            return null;
+        }
+
+        $baseDir = Environment::getPublicPath() . '/fileadmin/downloads/Collateral';
+        if (!is_dir($baseDir) || !is_readable($baseDir)) {
+            return null;
+        }
+
+        $escapedPrefix = preg_quote($fileprefix, '/');
+        $escapedType = preg_quote($filetype, '/');
+        $pattern = '/^' . $escapedPrefix . '__' . $escapedType . '__(\\d+)-([A-Za-z]+)\\.([A-Za-z0-9]+)$/';
+
+        $bestFile = null;
+        $bestNumber = -1;
+        $bestLetterRank = -1;
+
+        $entries = scandir($baseDir);
+        if ($entries === false) {
+            return null;
+        }
+
+        foreach ($entries as $entry) {
+            if (!is_string($entry) || $entry === '.' || $entry === '..') {
+                continue;
+            }
+
+            if (!preg_match($pattern, $entry, $matches)) {
+                continue;
+            }
+
+            $number = (int)$matches[1];
+            $letterRank = $this->letterSequenceToRank((string)$matches[2]);
+
+            if ($number > $bestNumber || ($number === $bestNumber && $letterRank > $bestLetterRank)) {
+                $bestNumber = $number;
+                $bestLetterRank = $letterRank;
+                $bestFile = $entry;
+            }
+        }
+
+        if ($bestFile === null) {
+            return null;
+        }
+
+        $fullPath = $baseDir . '/' . $bestFile;
+        if (!is_file($fullPath) || !is_readable($fullPath)) {
+            return null;
+        }
+
+        $extension = strtolower(pathinfo($bestFile, PATHINFO_EXTENSION));
+        $mimeType = function_exists('mime_content_type') ? (string)(mime_content_type($fullPath) ?: '') : '';
+
+        return [
+            'uid' => 0,
+            'name' => $bestFile,
+            'url' => '/fileadmin/downloads/Collateral/' . rawurlencode($bestFile),
+            'size' => (int)(filesize($fullPath) ?: 0),
+            'extension' => $extension,
+            'mimeType' => $mimeType,
+        ];
+    }
+
+    private function letterSequenceToRank(string $letters): int
+    {
+        $rank = 0;
+        $letters = strtoupper($letters);
+        $length = strlen($letters);
+
+        for ($i = 0; $i < $length; $i++) {
+            $char = ord($letters[$i]);
+            if ($char < 65 || $char > 90) {
+                continue;
+            }
+
+            $rank = ($rank * 26) + ($char - 64);
+        }
+
+        return $rank;
+    }
+
+    /**
+     * @param array<int,array<string,mixed>> $downloads
+     * @return array<int,array<string,mixed>>
+     */
+    private function collectFallbackFilesFromDownloads(array $downloads): array
+    {
+        $fallbackFiles = [];
+
+        foreach ($downloads as $download) {
+            if (!is_array($download)) {
+                continue;
+            }
+
+            $file = $download['file'] ?? null;
+            if (!is_array($file) || (int)($file['uid'] ?? 1) !== 0) {
+                continue;
+            }
+
+            $fallbackFiles[] = [
+                'downloadUid' => (int)($download['uid'] ?? 0),
+                'name' => (string)($file['name'] ?? ''),
+                'url' => (string)($file['url'] ?? ''),
+                'source' => 'naming-convention-fallback',
+            ];
+        }
+
+        return $fallbackFiles;
+    }
+
     protected function getProductDownloads(int $productUid): array
     {
         $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
@@ -522,6 +678,9 @@ class ProductShowJsonRenderer
         $result = [];
         foreach ($downloads as $download) {
             $fileInfo = null;
+            $downloadUid = (int)$download['uid'];
+            $fileprefix = (string)($download['fileprefix'] ?? '');
+            $filetype = $this->getDownloadFileType($downloadUid);
 
             if (!empty($download['file'])) {
                 $fileQueryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
@@ -532,7 +691,7 @@ class ProductShowJsonRenderer
                     ->from('sys_file_reference', 'fr')
                     ->join('fr', 'sys_file', 'f', 'fr.uid_local = f.uid')
                     ->where(
-                        $fileQueryBuilder->expr()->eq('fr.uid_foreign', $fileQueryBuilder->createNamedParameter((int)$download['uid'], ParameterType::INTEGER)),
+                        $fileQueryBuilder->expr()->eq('fr.uid_foreign', $fileQueryBuilder->createNamedParameter($downloadUid, ParameterType::INTEGER)),
                         $fileQueryBuilder->expr()->eq('fr.tablenames', $fileQueryBuilder->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING)),
                         $fileQueryBuilder->expr()->eq('fr.fieldname', $fileQueryBuilder->createNamedParameter('file', ParameterType::STRING)),
                         $fileQueryBuilder->expr()->eq('fr.deleted', 0),
@@ -555,14 +714,20 @@ class ProductShowJsonRenderer
                 }
             }
 
+            if ($fileInfo === null) {
+                $fileInfo = $this->resolveFileByConvention($fileprefix, $filetype);
+            }
+
             $result[] = [
-                'uid' => (int)$download['uid'],
+                'uid' => $downloadUid,
                 'title' => $download['title'] ?? '',
                 'slug' => $download['slug'] ?? '',
                 'teaser' => $download['teaser'] ?? '',
                 'description' => $download['description'] ?? '',
                 'keywords' => $download['keywords'] ?? '',
                 'icon' => $download['icon'] ?? '',
+                'fileprefix' => $fileprefix,
+                'filetype' => $filetype,
                 'file' => $fileInfo,
             ];
         }

packages/vitec/Classes/UserFunc/UsecaseListJsonRenderer.php

@@ -4,34 +4,33 @@ declare(strict_types=1);
 
 namespace Evomedien\Vitec\UserFunc;
 
-
-use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
+use Evomedien\Vitec\Service\UsecaseSerializer;
+use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use TYPO3\CMS\Core\Database\ConnectionPool;
-use TYPO3\CMS\Core\Resource\ResourceFactory;
 use TYPO3\CMS\Core\Service\FlexFormService;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
-use TYPO3\CMS\Extbase\Service\ImageService;
 
 /**
- * UserFunc to render the usecase list as JSON for headless output.
+ * UserFunc: render the Success Story list as JSON (headless).
  *
- * `render()` = page discovery (top-level plugin). `renderForRecord()` =
- * one specific tt_content row, reused by ContainerChildrenProcessor for
- * usecase-list plugins nested in a b13 container. Exception-safe.
+ * `render()` = top-level plugin / page discovery. `renderForRecord()` = one
+ * specific tt_content row (reused by ContainerChildrenProcessor for nested
+ * usecase-list plugins). All serialisation is delegated to UsecaseSerializer.
+ * Exception-safe.
  */
 class UsecaseListJsonRenderer
 {
+    private const TABLE = 'tx_vitec_domain_model_usecase';
+
     #[AsAllowedCallable]
     public function render(string $content, array $conf): string
     {
-        // 1) cObj data path
         $row = is_array($this->cObj->data ?? null) ? $this->cObj->data : null;
         if ($row && (string)($row['CType'] ?? '') === 'vitec_usecaselist') {
             return $this->renderForRecord($row);
         }
 
-        // 2) Page-id via v14 request attribute (TSFE->id is often null in JSON cObj context)
         $pageId = 0;
         $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
         if ($request !== null) {
@@ -47,29 +46,26 @@ class UsecaseListJsonRenderer
             return '';
         }
 
-        $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
-            ->getQueryBuilderForTable('tt_content');
-
-        $contentElements = $queryBuilder
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable('tt_content');
+        $ces = $qb
             ->select('*')
             ->from('tt_content')
             ->where(
-                $queryBuilder->expr()->eq('pid', $queryBuilder->createNamedParameter($pageId, ParameterType::INTEGER)),
-                $queryBuilder->expr()->eq('CType', $queryBuilder->createNamedParameter('vitec_usecaselist', ParameterType::STRING)),
-                $queryBuilder->expr()->eq('deleted', 0),
-                $queryBuilder->expr()->eq('hidden', 0)
+                $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
+                $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_usecaselist', ParameterType::STRING)),
+                $qb->expr()->eq('deleted', 0),
+                $qb->expr()->eq('hidden', 0)
             )
             ->executeQuery()
             ->fetchAllAssociative();
 
-        if (empty($contentElements)) {
+        if (empty($ces)) {
             return '';
         }
 
-        return $this->renderForRecord($contentElements[0]);
+        return $this->renderForRecord($ces[0]);
     }
 
-
     /**
      * @param array<string,mixed> $contentElement
      */
@@ -81,167 +77,36 @@ class UsecaseListJsonRenderer
             $settings = $flexFormData['settings'] ?? [];
             $debugMode = (bool)($settings['debug'] ?? false);
 
-            $usecaseQb = GeneralUtility::makeInstance(ConnectionPool::class)
-                ->getQueryBuilderForTable('tx_vitec_domain_model_usecase');
-
-            $usecases = $usecaseQb
-                ->select('u.*')
-                ->from('tx_vitec_domain_model_usecase', 'u')
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable(self::TABLE);
+            $rows = $qb
+                ->select('*')
+                ->from(self::TABLE)
                 ->where(
-                    $usecaseQb->expr()->eq('u.deleted', 0),
-                    $usecaseQb->expr()->eq('u.hidden', 0),
-                    $usecaseQb->expr()->eq('u.hideonwebsite', 0)
+                    $qb->expr()->eq('deleted', 0),
+                    $qb->expr()->eq('hidden', 0),
+                    $qb->expr()->eq('hideonwebsite', 0)
                 )
-                ->orderBy('u.title', 'ASC')
+                ->orderBy('featured', 'DESC')
+                ->addOrderBy('title', 'ASC')
                 ->executeQuery()
                 ->fetchAllAssociative();
 
-            $usecasesData = [];
-            foreach ($usecases as $usecase) {
-                $usecasesData[] = $this->serializeUsecase($usecase);
-            }
+            $serializer = GeneralUtility::makeInstance(UsecaseSerializer::class);
+            $usecases = array_map(
+                static fn (array $u): array => $serializer->serializeListItem($u),
+                $rows
+            );
 
             if ($debugMode) {
-                return json_encode([
-                    'usecases' => $usecasesData,
-                    'debug' => [
-                        'pageId' => (int)($GLOBALS['TSFE']->id ?? 0),
-                        'usecaseCount' => count($usecasesData),
-                        'settings' => $settings,
-                    ],
+                return (string)json_encode([
+                    'usecases' => $usecases,
+                    'debug'    => ['count' => count($usecases), 'settings' => $settings],
                 ]);
             }
 
-            return json_encode($usecasesData);
+            return (string)json_encode($usecases);
         } catch (\Throwable $e) {
             return '';
         }
     }
-
-    /**
-     * @param array<string,mixed> $usecase
-     * @return array<string,mixed>
-     */
-    protected function serializeUsecase(array $usecase): array
-    {
-        $uid = (int)$usecase['uid'];
-
-        return [
-            'uid' => $uid,
-            'title' => (string)($usecase['title'] ?? ''),
-            'slug' => (string)($usecase['slug'] ?? ''),
-            'subtitle' => (string)($usecase['subtitle'] ?? ''),
-            'teaser' => (string)($usecase['teaser'] ?? ''),
-            'description' => (string)($usecase['description'] ?? ''),
-            'singlepid' => (string)($usecase['singlepid'] ?? ''),
-            'hideonapp' => (bool)($usecase['hideonapp'] ?? false),
-            'hideonwebsite' => (bool)($usecase['hideonwebsite'] ?? false),
-            'categories' => $this->getUsecaseCategories($uid),
-            'caseimage' => $this->getUsecaseImage($uid, 'caseimage'),
-            'logoimage' => $this->getUsecaseImage($uid, 'logoimage'),
-        ];
-    }
-
-    /**
-     * @return array<string,mixed>|null
-     */
-    protected function getUsecaseImage(int $usecaseUid, string $fieldName): ?array
-    {
-        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
-            ->getQueryBuilderForTable('sys_file_reference');
-
-        $fileRefData = $queryBuilder
-            ->select('sfr.uid', 'sfr.title', 'sfr.description', 'sfr.alternative', 'sfr.crop')
-            ->from('sys_file_reference', 'sfr')
-            ->where(
-                $queryBuilder->expr()->eq('sfr.tablenames', $queryBuilder->createNamedParameter('tx_vitec_domain_model_usecase', ParameterType::STRING)),
-                $queryBuilder->expr()->eq('sfr.fieldname', $queryBuilder->createNamedParameter($fieldName, ParameterType::STRING)),
-                $queryBuilder->expr()->eq('sfr.uid_foreign', $queryBuilder->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
-                $queryBuilder->expr()->eq('sfr.deleted', 0),
-                $queryBuilder->expr()->eq('sfr.hidden', 0)
-            )
-            ->orderBy('sfr.sorting_foreign')
-            ->setMaxResults(1)
-            ->executeQuery()
-            ->fetchAssociative();
-
-        if (!$fileRefData) {
-            return null;
-        }
-
-        try {
-            $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
-            $imageService = GeneralUtility::makeInstance(ImageService::class);
-            $fileReference = $resourceFactory->getFileReferenceObject((int)$fileRefData['uid']);
-
-            $srcset = [];
-            foreach ([400, 800, 1200, 1600] as $width) {
-                $variant = $imageService->applyProcessingInstructions(
-                    $fileReference,
-                    ['width' => $width, 'crop' => $fileRefData['crop'] ?? null]
-                );
-                $srcset[] = [
-                    'url' => $imageService->getImageUri($variant),
-                    'width' => $width,
-                    'descriptor' => $width . 'w',
-                ];
-            }
-
-            $default = $imageService->applyProcessingInstructions(
-                $fileReference,
-                ['width' => 800, 'crop' => $fileRefData['crop'] ?? null]
-            );
-
-            return [
-                'uid' => (int)$fileRefData['uid'],
-                'url' => $imageService->getImageUri($default),
-                'title' => $fileRefData['title'] ?? '',
-                'alternative' => $fileRefData['alternative'] ?? '',
-                'description' => $fileRefData['description'] ?? '',
-                'srcset' => $srcset,
-                'properties' => [
-                    'width' => $fileReference->getProperty('width'),
-                    'height' => $fileReference->getProperty('height'),
-                    'mimeType' => $fileReference->getProperty('mime_type'),
-                ],
-            ];
-        } catch (\Exception $e) {
-            return null;
-        }
-    }
-
-    protected function getUsecaseCategories(int $usecaseUid): array
-    {
-        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
-            ->getQueryBuilderForTable('sys_category');
-
-        $categories = $queryBuilder
-            ->select('c.uid', 'c.title', 'c.description')
-            ->from('sys_category', 'c')
-            ->join(
-                'c',
-                'sys_category_record_mm',
-                'mm',
-                'mm.uid_local = c.uid AND mm.tablenames = ' .
-                $queryBuilder->createNamedParameter('tx_vitec_domain_model_usecase', ParameterType::STRING) .
-                ' AND mm.fieldname = ' .
-                $queryBuilder->createNamedParameter('categories', ParameterType::STRING)
-            )
-            ->where(
-                $queryBuilder->expr()->eq('mm.uid_foreign', $queryBuilder->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
-                $queryBuilder->expr()->eq('c.deleted', 0),
-                $queryBuilder->expr()->eq('c.hidden', 0)
-            )
-            ->orderBy('mm.sorting', 'ASC')
-            ->executeQuery()
-            ->fetchAllAssociative();
-
-        return array_map(static function ($cat) {
-            return [
-                'uid' => (int)$cat['uid'],
-                'title' => $cat['title'] ?? '',
-                'description' => $cat['description'] ?? '',
-            ];
-        }, $categories);
-    }
 }

packages/vitec/Classes/UserFunc/UsecaseShowJsonRenderer.php

@@ -4,34 +4,32 @@ declare(strict_types=1);
 
 namespace Evomedien\Vitec\UserFunc;
 
-
-use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
+use Evomedien\Vitec\Service\UsecaseSerializer;
+use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use TYPO3\CMS\Core\Database\ConnectionPool;
-use TYPO3\CMS\Core\Resource\ResourceFactory;
 use TYPO3\CMS\Core\Service\FlexFormService;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
-use TYPO3\CMS\Extbase\Service\ImageService;
 
 /**
- * UserFunc to render a single usecase as JSON for headless output.
+ * UserFunc: render a single Success Story as JSON (headless).
  *
- * `render()` = page discovery (top-level plugin). `renderForRecord()` =
- * one specific tt_content row, reused by ContainerChildrenProcessor for
- * usecase-show plugins nested in a b13 container. Exception-safe.
+ * The story is chosen from the plugin FlexForm (settings.usecase) or, when
+ * empty, from the request param tx_vitec_usecaseshow[usecase] (uid or slug).
+ * Full serialisation is delegated to UsecaseSerializer. Exception-safe.
  */
 class UsecaseShowJsonRenderer
 {
+    private const TABLE = 'tx_vitec_domain_model_usecase';
+
     #[AsAllowedCallable]
     public function render(string $content, array $conf): string
     {
-        // 1) cObj data path
         $row = is_array($this->cObj->data ?? null) ? $this->cObj->data : null;
         if ($row && (string)($row['CType'] ?? '') === 'vitec_usecaseshow') {
             return $this->renderForRecord($row);
         }
 
-        // 2) Page-id via v14 request attribute (TSFE->id is often null in JSON cObj context)
         $pageId = 0;
         $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
         if ($request !== null) {
@@ -47,243 +45,104 @@ class UsecaseShowJsonRenderer
             return '';
         }
 
-        $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
-            ->getQueryBuilderForTable('tt_content');
-
-        $contentElements = $queryBuilder
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable('tt_content');
+        $ces = $qb
             ->select('*')
             ->from('tt_content')
             ->where(
-                $queryBuilder->expr()->eq('pid', $queryBuilder->createNamedParameter($pageId, ParameterType::INTEGER)),
-                $queryBuilder->expr()->eq('CType', $queryBuilder->createNamedParameter('vitec_usecaseshow', ParameterType::STRING)),
-                $queryBuilder->expr()->eq('deleted', 0),
-                $queryBuilder->expr()->eq('hidden', 0)
+                $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
+                $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_usecaseshow', ParameterType::STRING)),
+                $qb->expr()->eq('deleted', 0),
+                $qb->expr()->eq('hidden', 0)
             )
             ->executeQuery()
             ->fetchAllAssociative();
 
-        if (empty($contentElements)) {
+        if (empty($ces)) {
             return '';
         }
 
-        return $this->renderForRecord($contentElements[0]);
+        return $this->renderForRecord($ces[0]);
     }
 
-
     /**
      * @param array<string,mixed> $contentElement
      */
     public function renderForRecord(array $contentElement): string
     {
         try {
-            $pageId = (int)($GLOBALS['TSFE']->id ?? 0);
-
             $flexFormService = GeneralUtility::makeInstance(FlexFormService::class);
             $flexFormData = $flexFormService->convertFlexFormContentToArray($contentElement['pi_flexform'] ?? '');
             $settings = $flexFormData['settings'] ?? [];
 
-            $usecaseUid = (int)($settings['usecase'] ?? 0);
-            $layout = (string)($settings['layout'] ?? 'default');
+            $layout    = (string)($settings['layout'] ?? 'default');
             $debugMode = (bool)($settings['debug'] ?? false);
+            $usecaseUid = (int)($settings['usecase'] ?? 0);
 
+            // Fallback: uid/slug from the request (React detail route).
             if (!$usecaseUid) {
-                $routeParams = $GLOBALS['TYPO3_REQUEST']->getQueryParams();
-                $usecaseParam = $routeParams['tx_vitec_usecaseshow']['usecase'] ?? null;
-
-                if ($usecaseParam) {
-                    if (!is_numeric($usecaseParam)) {
-                        $slugQb = GeneralUtility::makeInstance(ConnectionPool::class)
-                            ->getQueryBuilderForTable('tx_vitec_domain_model_usecase');
-                        $bySlug = $slugQb
-                            ->select('uid')
-                            ->from('tx_vitec_domain_model_usecase')
-                            ->where(
-                                $slugQb->expr()->eq('slug', $slugQb->createNamedParameter($usecaseParam)),
-                                $slugQb->expr()->eq('deleted', 0),
-                                $slugQb->expr()->eq('hidden', 0)
-                            )
-                            ->executeQuery()
-                            ->fetchAssociative();
-                        $usecaseUid = (int)($bySlug['uid'] ?? 0);
-                    } else {
-                        $usecaseUid = (int)$usecaseParam;
-                    }
+                $params = $GLOBALS['TYPO3_REQUEST']?->getQueryParams() ?? [];
+                $param = $params['tx_vitec_usecaseshow']['usecase'] ?? null;
+                if ($param !== null && $param !== '') {
+                    $usecaseUid = is_numeric($param) ? (int)$param : $this->resolveSlug((string)$param);
                 }
             }
 
             if (!$usecaseUid) {
                 return $debugMode
-                    ? json_encode(['error' => 'No usecase selected or found', 'debug' => ['settings' => $settings]])
+                    ? (string)json_encode(['error' => 'No usecase selected or found', 'debug' => ['settings' => $settings]])
                     : '';
             }
 
-            $usecaseQb = GeneralUtility::makeInstance(ConnectionPool::class)
-                ->getQueryBuilderForTable('tx_vitec_domain_model_usecase');
-
-            $usecase = $usecaseQb
+            $qb = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable(self::TABLE);
+            $usecase = $qb
                 ->select('*')
-                ->from('tx_vitec_domain_model_usecase')
+                ->from(self::TABLE)
                 ->where(
-                    $usecaseQb->expr()->eq('uid', $usecaseQb->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
-                    $usecaseQb->expr()->eq('deleted', 0),
-                    $usecaseQb->expr()->eq('hidden', 0)
+                    $qb->expr()->eq('uid', $qb->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
+                    $qb->expr()->eq('deleted', 0),
+                    $qb->expr()->eq('hidden', 0)
                 )
                 ->executeQuery()
                 ->fetchAssociative();
 
             if (!$usecase) {
                 return $debugMode
-                    ? json_encode(['error' => 'Usecase not found', 'debug' => ['usecaseUid' => $usecaseUid]])
+                    ? (string)json_encode(['error' => 'Usecase not found', 'debug' => ['usecaseUid' => $usecaseUid]])
                     : '';
             }
 
+            $serializer = GeneralUtility::makeInstance(UsecaseSerializer::class);
+
             $response = [
-                'usecase' => $this->serializeUsecase($usecase),
-                'layout' => $layout,
-                'settings' => [
-                    'layout' => $layout,
-                ],
+                'usecase' => $serializer->serializeDetail($usecase),
+                'layout'  => $layout,
             ];
 
             if ($debugMode) {
-                $response['debug'] = [
-                    'pageId' => $pageId,
-                    'usecaseUid' => $usecaseUid,
-                    'layout' => $layout,
-                    'settings' => $settings,
-                ];
+                $response['debug'] = ['usecaseUid' => $usecaseUid, 'layout' => $layout, 'settings' => $settings];
             }
 
-            return json_encode($response);
+            return (string)json_encode($response);
         } catch (\Throwable $e) {
             return '';
         }
     }
 
-    /**
-     * @param array<string,mixed> $usecase
-     * @return array<string,mixed>
-     */
-    protected function serializeUsecase(array $usecase): array
+    private function resolveSlug(string $slug): int
     {
-        $uid = (int)$usecase['uid'];
-
-        return [
-            'uid' => $uid,
-            'title' => (string)($usecase['title'] ?? ''),
-            'slug' => (string)($usecase['slug'] ?? ''),
-            'subtitle' => (string)($usecase['subtitle'] ?? ''),
-            'teaser' => (string)($usecase['teaser'] ?? ''),
-            'description' => (string)($usecase['description'] ?? ''),
-            'singlepid' => (string)($usecase['singlepid'] ?? ''),
-            'hideonapp' => (bool)($usecase['hideonapp'] ?? false),
-            'hideonwebsite' => (bool)($usecase['hideonwebsite'] ?? false),
-            'categories' => $this->getUsecaseCategories($uid),
-            'caseimage' => $this->getUsecaseImage($uid, 'caseimage'),
-            'logoimage' => $this->getUsecaseImage($uid, 'logoimage'),
-        ];
-    }
-
-    /**
-     * @return array<string,mixed>|null
-     */
-    protected function getUsecaseImage(int $usecaseUid, string $fieldName): ?array
-    {
-        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
-            ->getQueryBuilderForTable('sys_file_reference');
-
-        $fileRefData = $queryBuilder
-            ->select('sfr.uid', 'sfr.title', 'sfr.description', 'sfr.alternative', 'sfr.crop')
-            ->from('sys_file_reference', 'sfr')
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable(self::TABLE);
+        $row = $qb
+            ->select('uid')
+            ->from(self::TABLE)
             ->where(
-                $queryBuilder->expr()->eq('sfr.tablenames', $queryBuilder->createNamedParameter('tx_vitec_domain_model_usecase', ParameterType::STRING)),
-                $queryBuilder->expr()->eq('sfr.fieldname', $queryBuilder->createNamedParameter($fieldName, ParameterType::STRING)),
-                $queryBuilder->expr()->eq('sfr.uid_foreign', $queryBuilder->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
-                $queryBuilder->expr()->eq('sfr.deleted', 0),
-                $queryBuilder->expr()->eq('sfr.hidden', 0)
+                $qb->expr()->eq('slug', $qb->createNamedParameter($slug)),
+                $qb->expr()->eq('deleted', 0),
+                $qb->expr()->eq('hidden', 0)
             )
-            ->orderBy('sfr.sorting_foreign')
-            ->setMaxResults(1)
             ->executeQuery()
             ->fetchAssociative();
 
-        if (!$fileRefData) {
-            return null;
-        }
-
-        try {
-            $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
-            $imageService = GeneralUtility::makeInstance(ImageService::class);
-            $fileReference = $resourceFactory->getFileReferenceObject((int)$fileRefData['uid']);
-
-            $srcset = [];
-            foreach ([400, 800, 1200, 1600] as $width) {
-                $variant = $imageService->applyProcessingInstructions(
-                    $fileReference,
-                    ['width' => $width, 'crop' => $fileRefData['crop'] ?? null]
-                );
-                $srcset[] = [
-                    'url' => $imageService->getImageUri($variant),
-                    'width' => $width,
-                    'descriptor' => $width . 'w',
-                ];
-            }
-
-            $default = $imageService->applyProcessingInstructions(
-                $fileReference,
-                ['width' => 800, 'crop' => $fileRefData['crop'] ?? null]
-            );
-
-            return [
-                'uid' => (int)$fileRefData['uid'],
-                'url' => $imageService->getImageUri($default),
-                'title' => $fileRefData['title'] ?? '',
-                'alternative' => $fileRefData['alternative'] ?? '',
-                'description' => $fileRefData['description'] ?? '',
-                'srcset' => $srcset,
-                'properties' => [
-                    'width' => $fileReference->getProperty('width'),
-                    'height' => $fileReference->getProperty('height'),
-                    'mimeType' => $fileReference->getProperty('mime_type'),
-                ],
-            ];
-        } catch (\Exception $e) {
-            return null;
-        }
-    }
-
-    protected function getUsecaseCategories(int $usecaseUid): array
-    {
-        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
-            ->getQueryBuilderForTable('sys_category');
-
-        $categories = $queryBuilder
-            ->select('c.uid', 'c.title', 'c.description')
-            ->from('sys_category', 'c')
-            ->join(
-                'c',
-                'sys_category_record_mm',
-                'mm',
-                'mm.uid_local = c.uid AND mm.tablenames = ' .
-                $queryBuilder->createNamedParameter('tx_vitec_domain_model_usecase', ParameterType::STRING) .
-                ' AND mm.fieldname = ' .
-                $queryBuilder->createNamedParameter('categories', ParameterType::STRING)
-            )
-            ->where(
-                $queryBuilder->expr()->eq('mm.uid_foreign', $queryBuilder->createNamedParameter($usecaseUid, ParameterType::INTEGER)),
-                $queryBuilder->expr()->eq('c.deleted', 0),
-                $queryBuilder->expr()->eq('c.hidden', 0)
-            )
-            ->orderBy('mm.sorting', 'ASC')
-            ->executeQuery()
-            ->fetchAllAssociative();
-
-        return array_map(static function ($cat) {
-            return [
-                'uid' => (int)$cat['uid'],
-                'title' => $cat['title'] ?? '',
-                'description' => $cat['description'] ?? '',
-            ];
-        }, $categories);
+        return (int)($row['uid'] ?? 0);
     }
 }