---
title: "Custom Feature Cards"
manual: "AI Foundation"
version: "1.2"
permalink: "https://docs.typo3.org/permalink/nitsan/ns-t3af:custom-ai-features@1.2"
source: "DeveloperGuide/CustomFeatureCards/Index.rst"
modified: "2026-09-15T06:30:06+00:00"
---

# Custom Feature Cards

Use custom AI Features when your extension needs settings cards inside **AI Foundation > AI Features**. These cards are used for extension-specific AI configuration such as feature toggles, defaults, API-related options, and provider choices.

## Purpose

AI Features are not prompt templates and not MCP tools. They are configuration surfaces for extensions that use AI Foundation.

AI Foundation renders the card, drawer, AJAX save/load flow, and per-site storage. Your extension provides the card metadata, allowed settings scope, and field schema.

## Architecture

-   **Settings schema**

    `Configuration/ExtensionSettings/schema.php` points to the field definition file.

-   **Field definitions**

    `Configuration/ExtensionSettings/fields.typoscript` defines the fields shown in the drawer.

-   **Card provider**

    `AiFeatureCardProviderInterface` returns one or more cards for the AI Features overview.

-   **Scope provider**

    `ExtensionSettingsScopeProviderInterface` declares which settings scopes your extension accepts.

-   **Storage**

    Values are stored by AI Foundation in `tx_nst3af_extension_setting` for the selected site context.

## Implementation steps

1.  Add `schema.php` and `fields.typoscript` to your extension.
1.  Implement `AiFeatureCardProviderInterface`.
1.  Implement `ExtensionSettingsScopeProviderInterface`.
1.  Tag both services in your extension.
1.  Read saved values at runtime through the AI Foundation settings service.
1.  Flush caches and verify the card in **AI Foundation > AI Features**.

## Schema example

```php
<?php

declare(strict_types=1);

return [
    'fieldsTemplate' => __DIR__ . '/fields.typoscript',
];
```

## Field example

The category in `# cat=` must match the card’s `settingsScope`.

```typoscript
# cat=my ext settings//01; type=boolean; label=Enable AI-assisted generation
enableAiFeature = 0

# cat=my ext settings//02; type=int+; label=Default number of suggestions
defaultSuggestionCount = 3
```

## Service registration

```yaml
services:
  _defaults:
    autowire: true
    autoconfigure: true

  _instanceof:
    NITSAN\NsT3AF\Contract\AiFeatureCardProviderInterface:
      tags: ['t3af.ai_feature_card_provider']
    NITSAN\NsT3AF\Contract\ExtensionSettingsScopeProviderInterface:
      tags: ['t3af.extension_settings_scope']

  MyVendor\MyExt\Feature\:
    resource: '../Classes/Feature/'
```

## Runtime usage

Read settings through the AI Foundation settings API instead of parsing extension configuration manually. The saved values are merged with schema defaults.

```php
$settings = $this->extensionSettingsService->getAll('my_ext', $storagePid);
$enabled = ($settings['enableAiFeature'] ?? '0') === '1';
```

## Best practices

-   Keep `settingsScope` stable.
-   Use clear labels because editors see them in the backend drawer.
-   Do not overload one card with unrelated feature groups.
-   Use [Feature Provider Overrides](https://docs.typo3.org/permalink/nitsan/ns-t3af:feature-provider-overrides@1.2) when a feature needs its own provider dropdown.
-   Flush caches after changing schema or DI definitions.

## Verification

1.  Select a site in AI Foundation.
1.  Open **AI Foundation > AI Features**.
1.  Confirm your card appears.
1.  Open the drawer and verify fields from `fields.typoscript`.
1.  Save settings and reopen the drawer.
1.  Confirm your runtime service reads the saved value.

## Troubleshooting

**Card is missing**

-   Confirm the card provider is tagged with `t3af.ai_feature_card_provider`.
-   Confirm `isAvailable()` returns `true`.
-   Flush TYPO3 caches.

**Drawer says the scope is invalid**

-   Confirm the card `settingsScope` is listed by your scope provider.
-   Confirm the `# cat=` category matches the same scope.

## Related documentation

-   [Feature Provider Overrides](https://docs.typo3.org/permalink/nitsan/ns-t3af:feature-provider-overrides@1.2)
-   [Custom AI Prompts](https://docs.typo3.org/permalink/nitsan/ns-t3af:custom-ai-prompts@1.2)
-   [AI Features](https://docs.typo3.org/permalink/nitsan/ns-t3af:ai-features@1.2)