---
title: "Configuration"
manual: "Netresearch TextDB"
version: "main"
source: "Configuration/Index.rst"
rendered: "2026-09-30T23:05:19+00:00"
---

# Configuration {#configuration}

## Extension Configuration {#extension-configuration}

Configure the extension via **Admin Tools > Settings > Extension Configuration > nr_textdb**

### Available Settings {#available-settings}

-   **textDbPid**

    -   *type:* string (integer)
    -   *Default:* (empty)
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['EXTENSIONS'\]\['nr_textdb'\]\['textDbPid'\]

    The Page ID (PID) where TextDB translations should be stored.

    This should point to a dedicated storage folder in your page tree.

    > [!IMPORTANT]
    > This setting is required for the extension to function properly.

    Example

    Configure in **Admin Tools > Settings > Extension Configuration > nr_textdb**:

    ```none
    textDbPid = 123
    ```

-   **createIfMissing**

    -   *type:* boolean
    -   *Default:* true
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['EXTENSIONS'\]\['nr_textdb'\]\['createIfMissing'\]

    Automatically create translation records if they don't exist when requested
    via ViewHelpers.

    When enabled, missing translations will be auto-created with placeholder text.
    When disabled, only existing translations will be displayed.

    > [!TIP]
    > Enable this during development to quickly identify missing translations.
    > Disable in production if you want strict translation management.

    Example

    **config/system/additional.php**

    ```php
    // Development: auto-create missing translations
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb']['createIfMissing'] = true;

    // Production: strict mode
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb']['createIfMissing'] = false;
    ```

## TypoScript Configuration {#typoscript-configuration}

The extension includes default TypoScript configuration that is automatically loaded.

### Constants {#constants}

The extension provides the following TypoScript constants:

```typoscript
# File: Configuration/TypoScript/constants.typoscript
module.tx_nrtextdb {
    persistence {
        # Default storage PID
        storagePid =
    }
}
```

### Setup {#setup}

The extension setup configures the backend module with pagination:

```typoscript
# File: Configuration/TypoScript/setup.typoscript
module.tx_nrtextdb {
    settings {
        pagination {
            enablePagination = 1
            itemsPerPage = 15
        }
    }
}
```

## Backend Module Configuration {#backend-module-configuration}

### Access Control {#access-control}

The TextDB backend module requires appropriate permissions:

**Module Access:**

1.  Navigate to **System > Backend Users > \[User Group\]**
1.  Go to tab **Access Lists**
1.  Under **Modules**, check:
     *Netresearch*
     Netresearch TextDB

**Record Permissions:**

Grant access to TextDB tables:

-   `tx_nrtextdb_domain_model_translation`
-   `tx_nrtextdb_domain_model_component`
-   `tx_nrtextdb_domain_model_type`
-   `tx_nrtextdb_domain_model_environment`

### Module Customization {#module-customization}

The backend module is configured in `Configuration/Backend/Modules.php`:

```php
// Parent module (Netresearch)
'netresearch_module' => [
    'labels' => 'LLL:EXT:nr_textdb/Resources/Private/Language/locallang_mod.xlf',
    'iconIdentifier' => 'extension-netresearch-module',
    'position' => ['after' => 'web'],
],

// TextDB submodule
'netresearch_textdb' => [
    'parent' => 'netresearch_module',
    'access' => 'user',
    'iconIdentifier' => 'extension-netresearch-textdb',
    'path' => '/module/netresearch/textdb',
    'labels' => 'LLL:EXT:nr_textdb/Resources/Private/Language/locallang_mod_textdb.xlf',
    'extensionName' => 'NrTextdb',
    'controllerActions' => [
        TranslationController::class => [
            'list', 'translated', 'translateRecord',
            'import', 'export',
        ],
    ],
],
```

## Service Configuration {#service-configuration}

### Dependency Injection {#dependency-injection}

Services are configured in `Configuration/Services.yaml`:

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

    Netresearch\NrTextdb\:
        resource: '../Classes/*'
        exclude: '../Classes/Domain/Model/*'

    # Public services
    Netresearch\NrTextdb\Service\TranslationService:
        public: true

    # Console commands
    Netresearch\NrTextdb\Command\ImportCommand:
        tags:
            - name: 'console.command'
              command: 'nr_textdb:import'
              description: 'Imports textdb records from language files'
              schedulable: false
```

## Database Configuration {#database-configuration}

### Table Configuration (TCA) {#table-configuration-tca}

The extension defines TCA for four tables:

#### Translation Records {#translation-records}

```php
// Configuration/TCA/tx_nrtextdb_domain_model_translation.php
return [
    'ctrl' => [
        'title' => 'LLL:EXT:nr_textdb/Resources/Private/Language/locallang_db.xlf:tx_nrtextdb_domain_model_translation',
        'label' => 'placeholder',
        'languageField' => 'sys_language_uid',
        'transOrigPointerField' => 'l10n_parent',
        'searchFields' => 'value,placeholder',
        // ... additional configuration
    ],
    'columns' => [
        'value' => [
            'label' => 'Translation Value',
            'config' => [
                'type' => 'text',
                'required' => true,
            ],
        ],
        // ... additional fields
    ],
];
```

### Storage Configuration {#storage-configuration}

**Recommended Setup:**

1.  Create a dedicated storage folder at root level
1.  Set folder type to "Folder"
1.  Configure folder PID in extension configuration
1.  Create language overlays for this folder

```none
Page Tree:
└── [Root]
    └── TextDB Translations (Folder, PID: 123)
        ├── [Default Language]
        └── [Language Overlays]
```

## Icon Configuration {#icon-configuration}

Icons are registered in `Configuration/Icons.php`:

```php
return [
    'extension-netresearch-module' => [
        'provider' => SvgIconProvider::class,
        'source' => 'EXT:nr_textdb/Resources/Public/Icons/ModuleGroup.svg',
    ],
    'extension-netresearch-textdb' => [
        'provider' => SvgIconProvider::class,
        'source' => 'EXT:nr_textdb/Resources/Public/Icons/Module.svg',
    ],
    'nr-textdb-record-component' => [
        'provider' => SvgSpriteIconProvider::class,
        'sprite' => 'EXT:nr_textdb/Resources/Public/Icons/tx_nrtextdb_domain_model_component.svg#tx_nrtextdb_domain_model_component',
    ],
    // nr-textdb-record-environment, -translation and -type follow the same pattern
];
```

The glyphs use `currentColor`, so they follow the backend colour scheme.
The group icon is rendered inline in the module menu. The record icons are
sprite icons, referenced from the TCA through `ctrl.typeicon_classes`, so
TYPO3 renders them as `<svg><use>` instead of `<img>`.
`Extension.svg` stays the extension logo shown in the Extension Manager.

## Language Files {#language-configuration}

The extension uses XLIFF files for localization:

```none
Resources/Private/Language/
├── locallang.xlf                  # General labels
├── locallang_db.xlf               # Database field labels
├── locallang_mod.xlf              # Main module labels
├── locallang_mod_textdb.xlf       # TextDB module labels
├── de.locallang.xlf               # German translations
├── de.locallang_db.xlf
├── de.locallang_mod.xlf
└── de.locallang_mod_textdb.xlf
```

### Adding Custom Translations {#adding-custom-translations}

To add support for additional languages:

1.  Copy `locallang.xlf` to `[lang-key].locallang.xlf`
1.  Update the `target-language` attribute
1.  Translate all `<target>` elements

## Advanced Configuration {#advanced-configuration}

### Custom ViewHelper Configuration {#custom-viewhelper-configuration}

When using the TextDB ViewHelper in your templates:

```html
{namespace textdb=Netresearch\NrTextdb\ViewHelpers}

<textdb:textdb
    component="my-component"
    type="label"
    placeholder="welcome.message"
/>
```

### JavaScript Module Configuration {#javascript-module-configuration}

The extension provides JavaScript modules via `Configuration/JavaScriptModules.php`:

```php
return [
    'dependencies' => ['core', 'backend'],
    'imports' => [
        '@netresearch/nr-textdb/' => 'EXT:nr_textdb/Resources/Public/JavaScript/',
    ],
];
```

## Environment-Specific Configuration {#environment-specific}

### Development Environment {#development-environment}

```php
// config/system/additional.php (Development)
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb'] = [
    'textDbPid' => 123,
    'createIfMissing' => true,
];
```

### Production Environment {#production-environment}

```php
// config/system/additional.php (Production)
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb'] = [
    'textDbPid' => 456,
    'createIfMissing' => false, // Strict mode
];
```