Gamma Generator TYPO3

1. 1Prompt Objective: Scaffolding and implementing the TYPO3 extension gamma_generator to turn content elements into PDF and PPTX slide decks via the Gamma.app API.
2. 2Technical Architecture: Extends the pages table via SQL and TCA, implements a dedicated backend module, and persists generated files via FAL.
3. 3API Integration: Configures asynchronous requests against Gamma API v0.2 using polling, including specific page-break markup and content delimiters.
4. 4Security and Configuration: Secrets management handled through environment variables (.env) with fallback to Extension Manager settings.

Markdown

# TYPO3 Extension Prompt: Gamma AI Document Generator

You are an expert TYPO3 developer. Your task is to create a new TYPO3 extension named `gamma_generator`. This extension must be compatible with **TYPO3 v12.4 LTS and v13.x**.

The purpose of this extension is to allow a backend user to select a page, choose its content elements, add a custom prompt, and then use the **Gamma.app API** to generate educational materials ("Lernunterlage") as a PDF and a PPT file.

---

## 1. Core Requirements

* **Extension Scaffolding**: Create a standard, modern TYPO3 extension with a unique vendor name (e.g., `MyVendor`). Include a `composer.json` file and a basic `ext_emconf.php`.
* **Backend Module**: Create a new backend module named **"Gamma Generator"** with the module signature `gamma_generator`. It should have a clean and intuitive user interface using TYPO3's backend styling.
* **Database Fields**: Add four new fields to the `pages` database table to store the generation prompt, the selected content elements, and the final generated files.
* **Gamma API Integration**: Implement a service class to handle all communication with the Gamma.app API, including authentication, sending content, and retrieving the generated files.
* **Configuration**: The Gamma API key must be configurable in a secure way.
* **Frontend Output**: Use TypoScript to display links to the generated PDF and PPT files on the corresponding page in the frontend if they exist.

---

## 2. Technical Implementation Details

### 2.1. Database and TCA Configuration

First, modify the `pages` table. Create the file `ext_tables.sql` to add the following fields:

```sql
CREATE TABLE pages (
    tx_gammagenerator_prompt text,
    tx_gammagenerator_content_elements text,
    tx_gammagenerator_pdf int(11) unsigned DEFAULT '0' NOT NULL,
    tx_gammagenerator_ppt int(11) unsigned DEFAULT '0' NOT NULL
);
Next, create Configuration/TCA/Overrides/pages.php to add the TCA configuration for these new fields. Do not display these fields directly in the page properties. We will manage them exclusively through our new backend module. This is just to make them available to the DataHandler.

The crucial field here is tx_gammagenerator_content_elements. It should be configured as an inline relation (type='inline') to select and sort tt_content records.

PHP

// Configuration/TCA/Overrides/pages.php

defined('TYPO3') or die();

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns('pages', [
    'tx_gammagenerator_prompt' => [
        'label' => 'Gamma Prompt',
        'config' => [
            'type' => 'text',
            'rows' => 5,
        ],
    ],
    'tx_gammagenerator_content_elements' => [
        'label' => 'Selected Content Elements for Gamma',
        'config' => [
            'type' => 'inline',
            'foreign_table' => 'tt_content',
            'foreign_field' => 'pid', // This is a placeholder; logic will be handled in the module
            'foreign_sortby' => 'sorting',
            'maxitems' => 999,
            'appearance' => [
                'useSortable' => true,
                'showPossibleLocalizationRecords' => false,
                'showRemovedLocalizationRecords' => false,
                'showAllLocalizationLink' => false,
                'showSynchronizationLink' => false,
            ],
        ],
    ],
    'tx_gammagenerator_pdf' => [
        'label' => 'Generated PDF (Lernunterlage)',
        'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
            'tx_gammagenerator_pdf',
            [
                'maxitems' => 1,
                'overrideChildTca' => [
                    'types' => [
                        \TYPO3\CMS\Core\Resource\File::FILETYPE_APPLICATION => [
                            'showitem' => ' --palette--;;filePalette'
                        ],
                    ],
                ],
                'allowed' => 'common-files',
                'disallowed' => 'php,html',
            ]
        ),
    ],
    'tx_gammagenerator_ppt' => [
        'label' => 'Generated PPT',
        'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
            'tx_gammagenerator_ppt',
            [
                'maxitems' => 1,
                'overrideChildTca' => [
                    'types' => [
                         \TYPO3\CMS\Core\Resource\File::FILETYPE_APPLICATION => [
                            'showitem' => ' --palette--;;filePalette'
                        ],
                    ],
                ],
                'allowed' => 'common-files',
                'disallowed' => 'php,html',
            ]
        ),
    ],
]);
2.2. Backend Module
Create the backend module registration file: Configuration/Backend/Modules.php.

PHP

// Configuration/Backend/Modules.php

return [
    'gamma_generator' => [
        'parent' => 'web',
        'position' => ['after' => 'web_info'],
        'access' => 'user,group',
        'icon' => 'EXT:gamma_generator/Resources/Public/Icons/gamma-icon.svg',
        'labels' => 'LLL:EXT:gamma_generator/Resources/Private/Language/locallang_mod.xlf',
        'extensionName' => 'GammaGenerator',
        'controllerActions' => [
            \MyVendor\GammaGenerator\Controller\GeneratorController::class => [
                'index', 'generate',
            ],
        ],
    ],
];
The module should have a simple user interface:

Page Tree: On the left, display the TYPO3 page tree so the user can select a page.

Main Area:

Once a page is selected, use AJAX to load its content elements (tt_content) into a list. The list items should be sortable via drag-and-drop.

Display a textarea field for the user to add an additional prompt (tx_gammagenerator_prompt).

A primary "Generate" submit button.

Create the GeneratorController.php. The indexAction will render the main view. The generateAction will handle the form submission.

2.3. Gamma API Service
Create a service class, MyVendor\GammaGenerator\Service\GammaApiService, to handle all API logic.

Authentication: It should read the API key from the extension configuration.

Content Preparation:

It will receive the list of sorted tt_content UIDs and the custom prompt.

It must fetch the rendered content of each tt_content element.

Crucially for PDF page breaks, it should combine the content into a single string. It should insert a --- separator between each content element. This separator will be used by the Gamma API to create card/slide breaks. Also, wrap content elements in divs with a CSS class like page-break (<div style="page-break-after: always;">...</div>) to provide hints for page breaks in the PDF.

API Call Logic:

Send a POST request to https://public-api.gamma.app/v0.2/generations.

The POST body should be JSON:

JSON

{
  "inputText": "Your combined and prepared content here...",
  "textMode": "preserve",
  "cardBreaks": "inputTextBreaks",
  "theme": "Default",
  "exportFormats": ["pdf", "pptx"]
}
The API will respond with a generationId.

Implement a polling mechanism: make GET requests to https://public-api.gamma.app/v0.2/generations/{generationId} until the status is completed.

Once completed, the GET response will contain the public URLs for the generated pdf and pptx files.

File Handling: Download these files and attach them to the correct page record using FAL, storing them in the tx_gammagenerator_pdf and tx_gammagenerator_ppt fields respectively.

2.4. Configuration and Security
Create a file .env.example in the extension root with the following content:

# .env.example
# Gamma API Configuration
TYPO3__GAMMA_GENERATOR__API_KEY="your_gamma_api_key_goes_here"
Instruct the user to copy this to .env and add their key.

Create Configuration/Extconf/ext_conf_template.txt to allow setting the API key via Extension Manager settings as a fallback.

# cat=basic; type=string; label=Gamma API Key
apiKey =
In your GammaApiService, use \TYPO3\CMS\Core\Configuration\ExtensionConfiguration::get('gamma_generator', 'apiKey') to securely retrieve the key.

3. Frontend Output (TypoScript)
Add the following TypoScript setup in Configuration/TypoScript/setup.typoscript. This will render links to the generated files on the page if they exist.

Code-Snippet

page.22222 = COA
page.22222 {
    wrap = <div class="generated-files">|</div>

    // Link to the PDF file
    10 = FILES
    10 {
        references {
            table = pages
            uid.data = page:uid
            fieldName = tx_gammagenerator_pdf
        }
        renderObj = COA
        renderObj {
            10 = TEXT
            10.data = file:current:name
            10.typolink.parameter.data = file:current:publicUrl
            10.typolink.ATagParams = class="pdf-download"
            10.wrap = <p>Lernunterlage (PDF): |</p>
        }
        // Only render if a file exists
        if.isTrue.field = tx_gammagenerator_pdf
    }

    // Link to the PPT file
    20 = FILES
    20 {
        references {
            table = pages
            uid.data = page:uid
            fieldName = tx_gammagenerator_ppt
        }
        renderObj = COA
        renderObj {
            10 = TEXT
            10.data = file:current:name
            10.typolink.parameter.data = file:current:publicUrl
            10.typolink.ATagParams = class="ppt-download"
            10.wrap = <p>Präsentation (PPT): |</p>
        }
        // Only render if a file exists
        if.isTrue.field = tx_gammagenerator_ppt
    }
}
4. Expected Final File Structure
gamma_generator/
├── .env.example
├── composer.json
├── ext_emconf.php
├── ext_tables.sql
├── Configuration/
│   ├── Backend/
│   │   └── Modules.php
│   ├── Extconf/
│   │   └── ext_conf_template.txt
│   ├── TCA/
│   │   └── Overrides/
│   │       └── pages.php
│   └── TypoScript/
│       └── setup.typoscript
├── Classes/
│   ├── Controller/
│   │   └── GeneratorController.php
│   └── Service/
│       └── GammaApiService.php
└── Resources/
    ├── Private/
    │   ├── Language/
    │   │   └── locallang_mod.xlf
    │   └── Templates/
    │       └── Generator/
    │           └── Index.html
    └── Public/
        └── Icons/
            └── gamma-icon.svg
Please generate the complete code for this TYPO3 extension.

• Gamma Public API Generations Endpointpublic-api.gamma.app/v0.2/generations