Extending System Preferences

Overview

The CMS allows you to define custom setting keys that appear in the Admin > Preferences area. Instead of modifying the core PHP code, you can define these keys in a JSON file. This ensures that your custom settings (like API keys, specific text blocks, or bank details) are easily manageable via the UI.

1. File Location

The system looks for a file named preferences.json inside your active setup folder.

Path: [ROOT]/setup_[APP_NAME]/preferences.json

Example: If you are working on the "Auftrag" app, the file is located at:
c:\Users\marti\Documents\xampp\htdocs\bt5test\setup_auftrag\preferences.json

2. JSON Structure

The file must contain a valid JSON Array. Inside this array, you define Groups, and within each group, a list of Choices (the actual preferences).

Schema:

[
  {
    "label": "Group Name (displayed in dropdown)",
    "choices": [
      { 
        "value": "database_key_name", 
        "label": "Human Readable Label", 
        "type": "input_type (optional)" 
      }
    ]
  }
]

3. Supported Input Types

You can control how the input field renders in the Admin UI by setting the type property.

Type Value	Renders As	Description
`(omitted)`	`<input type="text">`	Standard single-line text input. Default if no type is specified.
`"textarea"`	`<textarea>`	Multi-line text area. Useful for addresses, notes, or simple scripts.
`"richtext"`	WYSIWYG Editor	Rich text editor (Trumbowyg). Useful for email templates, document headers, or content containing HTML formatting.

4. Complete Example

Here is a real-world example configuration for an invoicing module.

[
  {
    "label": "Invoicing Texts",
    "choices": [
      { 
        "value": "invoice_intro_text", 
        "label": "Invoice Intro (Top)", 
        "type": "richtext" 
      },
      { 
        "value": "invoice_footer_terms", 
        "label": "Terms & Conditions (Bottom)", 
        "type": "textarea" 
      }
    ]
  },
  {
    "label": "Bank Details (Girocode)",
    "choices": [
      { "value": "girocode_name", "label": "Account Holder" },
      { "value": "girocode_iban", "label": "IBAN" },
      { "value": "girocode_bic", "label": "BIC" }
    ]
  }
]

5. Using Preferences in PHP

Once you have saved values for these keys in the Admin panel, you can retrieve them in your PHP scripts (e.g., in rechnung_pdf.php).

// 1. Get the current user's team context
$user_team = $_SESSION['user']['team'];

// 2. Fetch all preferences for this team from the database
// We select 'name' and 'value' columns where the team matches.
$prefs_raw = DBGet('preferences', null, ['name', 'value'], 'team = ?', [$user_team]);

// 3. Convert to an associative array (Key => Value) for easy access
$team_preferences = [];
if ($prefs_raw) {
    $team_preferences = array_column($prefs_raw, 'value', 'name');
}

// 4. Access your custom variables
// Use the null coalescing operator (??) to handle missing values gracefully.
$iban = $team_preferences['girocode_iban'] ?? '';
$intro_html = $team_preferences['invoice_intro_text'] ?? '<p>Dear Customer,</p>';

// Example Output
if (!empty($iban)) {
    echo "Please transfer to IBAN: " . htmlspecialchars($iban);
}