Back to overview

Introduction to Snippets

Help & Basics Published on 03.02.2026

Developer Feature: Custom Code Snippets

This guide explains how to inject custom PHP and HTML code into specific pages of the application using the setup_folder. This allows for deep customization and the integration of application-specific logic.

Snippets are PHP files that you can place in your application's setup_folder (e.g., setup_adressen/). The application automatically detects these files and renders their content at predefined locations. This allows you to display dynamic information, add custom UI elements, or run specific PHP logic on certain pages without modifying the core application files.

There are several types of snippets available:

Index Snippet: For the main homepage (index.php).
Table Snippet (Display): For the list view of a specific table (custom_table_view.php).
Form Snippet (Display): For the record creation/editing form (custom_table_record_edit.php).
Filter Snippet (Data Filtering): To filter the displayed data in the list view on the server-side.
Validation Snippet (Save Validation): To execute complex validation rules before saving a record.
Calendar Snippet: To extend the calendar view.
Kanban Snippet: To extend the Kanban view.
User List Snippet: To extend the user management functionality.
Associated CSS: For each display snippet, you can also create a corresponding .css file with the same name, which will be automatically included in the page's <head>.

1. Index Snippet

This snippet is rendered on the homepage, directly below the main hero banner and above the custom action buttons. It's ideal for welcome messages, version announcements, or global alerts.

File Name: index_snippet.php
Location: Place it in the root of your setup_folder.
- Example: setup_adressen/index_snippet.php
Associated CSS (optional): index_snippet.css
- Example: setup_adressen/index_snippet.css

Example: Version Announcement

This code displays a dismissible Bootstrap alert to inform users about a new version.

<?php
/**
 * Homepage Snippet (index.php)
 * This snippet is rendered below the main banner on the homepage.
 */
?>
<div class="container-fluid">
    <div class="alert alert-info alert-dismissible fade show" role="alert">
        <h4 class="alert-heading">New Version Available!</h4>
        <p>We've updated the application to bring you new features and improved performance. Feel free to look around!</p>
        <hr>
        <p class="mb-0">If you have any questions, our support team is here to help.</p>
        <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
    </div>
</div>

2. Table Snippet (Display)

This snippet is rendered on the list view of a specific table, right below the page header and above the action buttons ("New Record", etc.). It's perfect for displaying table-specific statistics, instructions, or aggregated data.

File Name: table_{table_name}_snippet.php
- Replace {table_name} with the technical name of your table (e.g., adressen).
Location: Place it in the root of your setup_folder.
- Example: setup_adressen/table_kassenbuch_snippet.php
Associated CSS (optional): table_{table_name}_snippet.css
- Example: setup_adressen/table_kassenbuch_snippet.css

Example: Cashbook Summary

Imagine you have a "Cashbook" table (kassenbuch) and a related "Bookings" table (buchungen) linked via a lookup field. This snippet calculates and displays the total income and expenses from the buchungen table directly on the kassenbuch list view.

<?php
/**
 * Table Snippet for the "kassenbuch" table.
 *
 * This snippet has access to the current table's definition via the $table_definition variable.
 * We can use this to perform related database queries.
 */

// Get the ID of the currently viewed cashbook record (if filtered)
$kassenbuch_id = (int)($_GET['filter']['id'] ?? 0);

if ($kassenbuch_id > 0) {
    // Find the physical table name for the "buchungen" table.
    // This requires knowing the table ID and owner team of the "buchungen" table.
    $buchungen_table_def = DBGet('custom_tables', null, ['id', 'team'], "table_name = 'buchungen' AND (team = ? OR team = 'ADMININTEX')", [$_SESSION['user']['team']])[0] ?? null;

    if ($buchungen_table_def) {
        $buchungen_physical_table = "data_team_{$buchungen_table_def['team']}_{$buchungen_table_def['id']}";
        $pdo = DBOpen();

        // Calculate total income (where 'betrag' > 0)
        $stmt_income = $pdo->prepare("SELECT SUM(betrag) FROM `{$buchungen_physical_table}` WHERE kassenbuch_id = ? AND betrag > 0");
        $stmt_income->execute([$kassenbuch_id]);
        $total_income = (float)$stmt_income->fetchColumn();

        // Calculate total expenses (where 'betrag' < 0)
        $stmt_expenses = $pdo->prepare("SELECT SUM(betrag) FROM `{$buchungen_physical_table}` WHERE kassenbuch_id = ? AND betrag < 0");
        $stmt_expenses->execute([$kassenbuch_id]);
        $total_expenses = (float)$stmt_expenses->fetchColumn();

        $balance = $total_income + $total_expenses;
?>
        <div class="row mb-3">
            <div class="col-md-4">
                <div class="card text-white bg-success"><div class="card-body">
                    <h5 class="card-title">Total Income</h5>
                    <p class="card-text fs-4 fw-bold"><?= number_format($total_income, 2, ',', '.') ?> €</p>
                </div></div>
            </div>
            <div class="col-md-4">
                <div class="card text-white bg-danger"><div class="card-body">
                    <h5 class="card-title">Total Expenses</h5>
                    <p class="card-text fs-4 fw-bold"><?= number_format(abs($total_expenses), 2, ',', '.') ?> €</p>
                </div></div>
            </div>
            <div class="col-md-4">
                <div class="card text-white <?= $balance >= 0 ? 'bg-primary' : 'bg-warning' ?>"><div class="card-body">
                    <h5 class="card-title">Current Balance</h5>
                    <p class="card-text fs-4 fw-bold"><?= number_format($balance, 2, ',', '.') ?> €</p>
                </div></div>
            </div>
        </div>
<?php
    }
}
?>

3. Form Snippet (Display)

This snippet is rendered inside the record creation or editing form, directly below the page header and above the form fields. It's perfect for showing contextual warnings, instructions, or related data that helps with data entry.

File Name: form_{table_name}_snippet.php
- Replace {table_name} with the technical name of your table.
Location: Place it in the root of your setup_folder.
- Example: setup_adressen/form_adressen_snippet.php
Associated CSS (optional): form_{table_name}_snippet.css
- Example: setup_adressen/form_adressen_snippet.css

Example: Contextual Warning

This code displays a warning message only when an existing record is being edited. It has access to the record's data.

<?php
/**
 * Form Snippet for the "adressen" table.
 *
 * This snippet has access to the following variables:
 * - $is_edit_mode (bool): True if editing an existing record, false if creating a new one.
 * - $record_data (array): The data of the current record being edited.
 */

// Example: Show a message only when editing an existing record.
if ($is_edit_mode) {
    $record_id = $record_data['id'] ?? 'unknown';
    $customer_status = $record_data['status'] ?? '';

    if ($customer_status === 'Inactive') {
?>
    <div class="alert alert-danger" role="alert">
        <i class="fa-solid fa-triangle-exclamation me-2"></i>
        <strong>Warning:</strong> You are editing an <strong>inactive</strong> customer (ID #<?= htmlspecialchars($record_id) ?>). Please verify if this is intended.
    </div>
<?php
    }
}
?>

4. Filter Snippet (Data Filtering)

This snippet is executed in the list view (custom_table_view.php) before the database query for the records takes place. It is ideal for restricting the displayed data based on the logged-in user or other complex rules (Row-Level Security).

File Name: filter_{table_name}_snippet.php
- Replace {table_name} with the technical name of your table.
Location: Place it in the root of your setup_folder.
- Example: setup_rental/filter_meter_readings_snippet.php

Example: Show Only Own Records

This code ensures that regular users only see the records they have created themselves. Administrators are exempt and continue to see all records.

<?php
/**
 * Filter Snippet for any table.
 *
 * This snippet has access to the following variables and can modify them:
 * - $where_clauses (array): The array of SQL WHERE conditions.
 * - $params (array): The array of SQL parameters for the prepared statements.
 * - $table_definition (array): The definition of the current table.
 */

// Example: Regular users only see their own records. Admins see everything.
// Prerequisite: The table has a field 'created_by_user_id' that stores the creator's ID.
if (empty($_SESSION['user']['admin'])) {
    $where_clauses[] = "`created_by_user_id` = ?";
    $params[] = $_SESSION['user']['id'];
}
?>

5. Validation Snippet (Save Validation)

This snippet is executed during the form's save process (custom_table_record_edit.php), after the standard validations (e.g., required fields) have passed, but before the record is written to the database. It is perfect for complex, application-specific validation rules that go beyond simple field options.

File Name: validate_{table_name}_snippet.php
- Replace {table_name} with the technical name of your table.
Location: Place it in the root of your setup_folder.
- Example: setup_adressen/validate_addresses_snippet.php

Example: Check Address Completeness

This code checks if the zip and city fields have been filled out when an address is entered in address1. If not, it generates an error message and prevents the record from being saved.

<?php
/**
 * Validation Snippet for the "addresses" table.
 *
 * This snippet has access to the following variables:
 * - $submitted_data (array): The user-submitted and already sanitized form data.
 * - $errors (array): The error array. If this array is not empty at the end, saving is aborted.
 * - $is_edit_mode (bool): True if editing an existing record.
 * - $record_id (int): The ID of the record being edited (only in edit mode).
 */

// Rule: If 'address1' is filled, 'zip' and 'city' must also be filled.
if (!empty($submitted_data['address1'])) {
    if (empty($submitted_data['zip'])) {
        $errors['zip'] = 'If an address is provided, the ZIP code must also be filled in.';
    }
    if (empty($submitted_data['city'])) {
        $errors['city'] = 'If an address is provided, the city must also be filled in.';
    }
}
?>