Features 

• AI-generated FAQ -- sends all page content to the ZAK-AI faq endpoint and returns structured question-answer pairs.
• Accordion presentation -- the generated FAQ is displayed using Bootstrap accordion component.
• Preview functionality -- editors can preview the generated FAQ before saving it to the content element.
• Schema.org markup -- includes structured data markup for FAQ pages to improve SEO.
• Part of the Ai3 Suite -- integrates with wegewerk/ai3_core for API client and capability infrastructure.

How it works 

1. An editor adds the Page FAQ content element (CType: ai3_faq) to a page.
2. The custom FormEngine widget displays a language selector and a "Generate FAQ" button.
3. On click, a backend AJAX request fetches all content records on the current page and sends them to the ZAK-AI faq API.
4. The API response contains question-answer pairs that are displayed in a preview table.
5. The editor can review the generated FAQ and click "Use FAQ Elements" to save the data to the content element.
6. On the frontend, the element renders the FAQ as a Bootstrap accordion with proper schema.org markup for SEO benefits.

Use cases 

• SEO optimization -- generate schema.org compliant FAQ markup to enhance search engine visibility and rich snippets.

Requirements 

• TYPO3 CMS 13.4 or 14.x
• wegewerk/ai3_core (installed automatically as a dependency)
• typo3/cms-fluid-styled-content 13.4 or 14.x
• bk2k/bootstrap-package (for accordion functionality)
• brotkrueml/schema 4.x (for schema.org markup)
• A valid ZAK-AI API key (see Configuration)

Installation via Composer 

Ai3 FAQ is installed exclusively via Composer. Run the following command in your TYPO3 project root:

composer require wegewerk/ai3_faq

This will automatically install all required dependencies, including wegewerk/ai3_core , bk2k/bootstrap-package , and brotkrueml/schema .

Activate the extension 

After installation, activate the extension using the TYPO3 CLI:

vendor/bin/typo3 extension:activate ai3_faq

Verify installation 

To verify the installation was successful:

1. Log in to the TYPO3 backend
2. Navigate to any page
3. Create a new content element
4. Look for the Page FAQ element in the "AI3" group
5. The element should be available with an AI3 FAQ icon

Ai3 Core Dependency 

Ai3 FAQ relies on the configuration of Ai3 Core. Ensure that wegewerk/ai3_core is properly installed and configured with valid API credentials for the ZAK-AI service.

API Credentials 

The API credentials for the ZAK-AI service are provided via environment variables consumed by Wegewerk\Ai3Core\Api\ZakAiClient:

• ZAKAI_API_KEY -- your ZAK-AI API key.
• ZAKAI_SECRET -- your ZAK-AI secret.

Set these environment variables in your system or in your .env file:

export ZAKAI_API_KEY=your-api-key-here
export ZAKAI_SECRET=your-secret-here

Bootstrap Package Integration 

The extension requires bk2k/bootstrap-package for accordion functionality. The FAQ content element uses the Bootstrap Package accordion configuration and FlexForm settings.

The accordion configuration is automatically applied via TCA:

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPiFlexFormValue(
    '*',
    'FILE:EXT:bootstrap_package/Configuration/FlexForms/Accordion.xml',
    'ai3_faq'
);

Schema.org Configuration 

The extension uses brotkrueml/schema to generate structured data markup for FAQ pages. This improves SEO and enables rich snippets in search results.

The schema markup is automatically generated when the FAQ is rendered on the frontend, using the FAQPage schema type.

TypoScript 

The extension automatically loads its TypoScript configuration. The setup includes:

# Content element registration
tt_content.ai3_faq < lib.contentElement
tt_content.ai3_faq {
    templateName = Accordion
    # Uses Bootstrap Package accordion template
}

Backend AJAX Routes 

The extension registers AJAX routes for backend communication:

return [
    'ai3_faq_generate' => [
        'path' => '/ai3/faq/generate',
        'target' => \Wegewerk\Ai3Faq\Controller\Ajax\ArticlefaqController::class . '::getFaq'
    ],
];

Language Support 

The extension currently supports German (de) language output from the ZAK-AI API. Additional languages can be configured by modifying the language options in the JavaScript module:

getLanguageOptions() {
     return [
         {
             value: 'de',
             label: 'Deutsch'
         }
         // Add more languages here
     ]
}

Customization Options 

.accordion-item {
    /* Custom FAQ accordion styling */
}

EXT:your_sitepackage/Resources/Private/Templates/ContentElements/Accordion.html

'tx_ai3_faq_generator' => [
    'exclude' => true,
    'label'   => 'LLL:EXT:ai3_faq/Resources/Private/Language/locallang.xlf:tx_ai3.faq.generator',
    'config'  => [
        'type'       => 'user',
        'renderType' => 'ai3FaqGeneratorElement',
    ],
]

Scenario 

Imagine you have a product page with detailed information about a software tool, including features, pricing, system requirements, and support options. You want to create a FAQ section that addresses common visitor questions automatically based on this content.

Step 1: Prepare your page content 

Before generating the FAQ, ensure your page has comprehensive content:

1. Create or edit a page in the TYPO3 backend

2. Add content elements with detailed information:

   • Header element - Page title and introduction
   • Text elements - Detailed descriptions of features, benefits, processes
   • Text & Media elements - Product images with descriptions
   • Additional content - Any other relevant information
3. Make sure all content is saved and published

Step 2: Add the Page FAQ element 

1. In the Page module, navigate to your content page
2. Click + Content to add a new content element
3. In the content element wizard, look for the AI3 group
4. Select Page FAQ from the available elements
5. Click Next or Save

The content element editor opens with the FAQ generator interface.

Step 3: Generate your FAQ 

1. In the FAQ generator section, you'll see:

   • A language dropdown (currently supports Deutsch)
   • A Generate FAQ button
2. Select your preferred language (Deutsch)
3. Click Generate FAQ
4. Wait for the generation process (usually 10-30 seconds)

The system will:

• Extract all content from the current page
• Send it to the ZAK-AI service
• Receive question-answer pairs
• Display them in a preview table

Step 4: Review the generated FAQ 

Once generation is complete, you'll see a preview table with:

• Question column - AI-generated questions about your content
• Answer column - Corresponding answers based on page content

Example output might include:

Step 5: Save and customize 

1. If you're satisfied with the generated FAQ, click Use FAQ Elements
2. The FAQ data is saved to the content element
3. Click Save to store the content element

4. Navigate to the Accordion tab to customize the presentation:

   • Flush - Remove borders for seamless appearance
   • Always open - Keep all items expanded by default
   • Behavior - Allow single or multiple open items

Step 6: View the result 

Navigate to your page on the frontend to see the FAQ in action:

• Questions appear as clickable accordion headers
• Clicking a question expands the answer
• The interface is responsive and accessible
• Schema.org markup is automatically included for SEO

SEO Benefits 

The generated FAQ automatically includes schema.org markup:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Was kostet das Produkt?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Das Produkt ist in drei Preispaketen verfügbar..."
      }
    }
  ]
}

This markup enables:

• Rich snippets in Google search results
• FAQ rich results with expandable questions
• Improved click-through rates from search engines
• Enhanced local SEO for location-based questions

Tips for better results 

Troubleshooting 

Next Steps 

Once you're comfortable with basic FAQ generation, consider:

• Customizing templates - Override the accordion template for custom styling
• Adding multiple languages - Configure additional language options
• Integrating with analytics - Track FAQ interaction and user engagement
• Creating FAQ collections - Use FAQ on multiple related pages for comprehensive coverage

For advanced customization and development, see the Developer Documentation.

Add the Page FAQ element 

1. Open the Page module and navigate to the page where you want to add a FAQ section.
2. Click + Content to open the content element wizard.
3. Select the Page FAQ element from the AI3 group.
4. The content element editor will open with the FAQ generator interface.

Generate FAQ 

1. In the FAQ generator field, you'll see:

   • A language selector (currently supports Deutsch)
   • A Generate FAQ button
2. Select the desired language from the dropdown menu.
3. Click the Generate FAQ button.
4. Wait while the FAQ is being generated (Generating FAQ... is shown during processing).

5. The generated FAQ appears in a preview table with:

   • Question column showing the generated questions
   • Answer column showing the corresponding answers

Review and save FAQ 

1. Review the generated question-answer pairs in the preview table.
2. If you're satisfied with the generated FAQ, click Use FAQ Elements.
3. The FAQ data is saved to the content element and the accordion configuration is automatically applied.
4. Save the content element to store all changes.

Accordion configuration 

After saving the FAQ data, you can configure the accordion presentation using the standard Bootstrap Package accordion settings:

1. Navigate to the Accordion tab in the content element

2. Configure accordion behavior options:

   • Flush - Remove borders for seamless appearance
   • Always open - Keep all accordion items expanded
   • Behavior - Single or multiple items can be open
3. Each FAQ question becomes an accordion header, with the answer as content.

Frontend output 

Once saved, the Page FAQ content element renders as a Bootstrap accordion on the frontend with the following features:

• Interactive accordion - Users can click questions to expand/collapse answers
• SEO-optimized markup - Includes schema.org FAQPage structured data
• Responsive design - Works seamlessly on all device sizes
• Accessible - Follows WCAG guidelines for keyboard navigation and screen readers

Best practices 

Architecture 

Ai3 FAQ follows the Ai3 Suite capability pattern provided by wegewerk/ai3_core :

• A Capability class registers the feature under a unique key.
• An Endpoint class implements the ZAK-AI API call.
• A FormEngine element renders the backend widget.
• A backend AJAX controller handles the generation request.
• Bootstrap Package integration provides accordion functionality.

PHP API 

FormEngine integration 

The custom FormEngine node ai3FaqGeneratorElement is registered in TCA configuration:

$GLOBALS['TCA']['tt_content']['columns']['tx_ai3_faq_generator'] = [
    'exclude' => true,
    'label'   => 'LLL:EXT:ai3_faq/Resources/Private/Language/locallang.xlf:tx_ai3.faq.generator',
    'config'  => [
        'type'       => 'user',
        'renderType' => 'ai3FaqGeneratorElement',
    ],
];

class Ai3FaqGeneratorElement

Fully qualified name

\Wegewerk\Ai3Faq\FormEngine\Ai3FaqGeneratorElement

Extends TYPO3\CMS\Backend\Form\Element\AbstractFormElement. Renders a <div data-ai3="ai3-faq-container"> with data-page-id and data-record-uid attributes. The Lit-HTML FaqApp mounts into the inner <div data-ai3="ai3-faq-app">.

TCA Configuration 

ExtensionManagementUtility::addTcaSelectItem('tt_content',
    'CType',
    [
        'label'       => 'LLL:EXT:ai3_faq/Resources/Private/Language/locallang.xlf:tx_ai3.faq.label_ctype',
        'value'       => 'ai3_faq',
        'icon'        => 'ai3-faq-icon',
        'description' => 'LLL:EXT:ai3_faq/Resources/Private/Language/locallang.xlf:tx_ai3.faq.label_description',
        'group'       => 'AI3',
    ],
    'textmedia',
    'after',
);

$GLOBALS['TCA']['tt_content']['types']['ai3_faq'] = $GLOBALS['TCA']['tt_content']['types']['accordion'];

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPiFlexFormValue(
    '*',
    'FILE:EXT:bootstrap_package/Configuration/FlexForms/Accordion.xml',
    'ai3_faq'
);

AJAX route 

The backend AJAX route is registered in Configuration/Backend/AjaxRoutes.php:

Request (POST, JSON body):

{
    "page_id": 42,
    "language": "de"
}

Response (success):

{
    "success": true,
    "faqData": [
        {
            "question": "What is this page about?",
            "answer": "This page describes..."
        },
        {
            "question": "How do I use this feature?",
            "answer": "To use this feature, you need to..."
        }
    ],
    "source": "Page content extracted from...",
    "type": "faq"
}

Response (error):

{
    "success": false,
    "error": "Error message describing what went wrong"
}

JavaScript modules 

JavaScript modules are registered via Configuration/JavaScriptModules.php under the @wegewerk/Ai3Faq/ import map prefix.

• ``@wegewerk/Ai3Faq/ai3api.js`` -- Ai3Api class with generateFaq(pageId, recordUid, language) that POSTs to the AJAX route via TYPO3's AjaxRequest.
• ``@wegewerk/Ai3Faq/faq.js`` -- Lit-HTML FaqApp that renders the backend widget, handles button clicks, calls Ai3Api, displays FAQ preview, and manages the accordion data.

Services Configuration 

The extension's services are configured in Configuration/Services.yaml:

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  Wegewerk\Ai3Faq\:
    resource: '../Classes/*'

  Wegewerk\Ai3Faq\Domain\Capabilities\ArticlefaqCapability:
    arguments:
      $key: 'articlefaq'
      $title: 'Article FAQ'
      $endpoint: '@Wegewerk\Ai3Faq\Api\ZakAiFaq'
    tags:
      - { name: 'ai3.capability' }

Event listener 

class AfterFormEnginePageInitializedEventListener

Fully qualified name

\Wegewerk\Ai3Faq\EventListener\AfterFormEnginePageInitializedEventListener

Listens to AfterFormEnginePageInitializedEvent (#[AsEventListener]). Adds the extension's locallang.xlf as an inline language label file to the PageRenderer, making all translation keys available to JavaScript.

Schema.org Integration 

The extension automatically generates schema.org markup for FAQ pages when using the brotkrueml/schema extension. This provides structured data for search engines and enables rich snippets.

The schema markup uses the FAQPage type and includes:

• Main entity as FAQPage
• Individual Question entities for each FAQ item
• Proper acceptedAnswer markup for each answer

Customization and Extension 

getLanguageOptions() {
     return [
         {
             value: 'de',
             label: 'Deutsch'
         },
         {
             value: 'en',
             label: 'English'
         },
         {
             value: 'fr',
             label: 'Français'
         }
     ];
}

class CustomZakAiFaq extends ZakAiFaq
{
    public function generate(string $imagePath, string $description, string $language): string
    {
        $result = parent::generate($imagePath, $description, $language);
        
        // Custom processing of FAQ data
        $faqData = json_decode($result, true);
        $processedData = $this->customProcessing($faqData);
        
        return json_encode($processedData);
    }

    private function customProcessing(array $faqData): array
    {
        // Your custom logic here
        return $faqData;
    }
}

<!-- EXT:your_sitepackage/Resources/Private/Templates/ContentElements/Accordion.html -->
<div class="accordion faq-accordion" id="accordion_{data.uid}">
    <f:for each="{accordionItems}" as="item" iteration="iteration">
        <div class="accordion-item">
            <h2 class="accordion-header">
                <button class="accordion-button faq-question" type="button"
                        data-bs-toggle="collapse"
                        data-bs-target="#collapse_{data.uid}_{iteration.cycle}">
                    {item.question}
                </button>
            </h2>
            <div id="collapse_{data.uid}_{iteration.cycle}" 
                 class="accordion-collapse collapse">
                <div class="accordion-body faq-answer">
                    <f:format.html>{item.answer}</f:format.html>
                </div>
            </div>
        </div>
    </f:for>
</div>