Custom Code Snippets

Introduction to Snippets

Snippets are PHP and CSS 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 four types of snippets available:

1. Index Snippet: For the main homepage (index.php).
2. Table Snippet: For the list view of a specific table (custom_table_view.php).
3. Form Snippet: For the record creation/editing form of a specific table (custom_table_record_edit.php).
4. CSS Snippet: For adding custom styles to any of the pages above.

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.

• PHP File Name: index_snippet.php
• CSS File Name (optional): index_snippet.css
• Location: Place the file(s) in the root of your setup_folder.
  • Example: setup_adressen/index_snippet.php
  • 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

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.

• PHP File Name: table_{table_name}_snippet.php
  • Replace {table_name} with the technical name of your table (e.g., adressen).
• CSS File Name (optional): table_{table_name}_snippet.css
• Location: Place the file(s) in the root of your setup_folder.
  • Example: setup_adressen/table_kassenbuch_snippet.php
  • 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.
    $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 and expenses
        $stmt = $pdo->prepare("SELECT SUM(CASE WHEN betrag > 0 THEN betrag ELSE 0 END) as income, SUM(CASE WHEN betrag < 0 THEN betrag ELSE 0 END) as expenses FROM `{$buchungen_physical_table}` WHERE kassenbuch_id = ?");
        $stmt->execute([$kassenbuch_id]);
        $totals = $stmt->fetch();
        $total_income = (float)($totals['income'] ?? 0);
        $total_expenses = (float)($totals['expenses'] ?? 0);
        $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

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.

• PHP File Name: form_{table_name}_snippet.php
  • Replace {table_name} with the technical name of your table.
• CSS File Name (optional): form_{table_name}_snippet.css
• Location: Place the file(s) in the root of your setup_folder.
  • Example: setup_adressen/form_adressen_snippet.php
  • 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.
 */

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. CSS Snippets

For every PHP snippet, you can create a corresponding .css file with the exact same name (just with a different extension). This CSS file will be automatically included in the <head> of the page where the snippet is displayed. This allows you to add custom styles for your snippet's content or even override the application's default styles for that specific page.

Example: Styling the Cashbook Summary

To style the cards from the "Cashbook Summary" example above, you could create a file named table_kassenbuch_snippet.css:

/*
 * Custom styles for the cashbook snippet.
 * File: setup_adressen/table_kassenbuch_snippet.css
 */
.card-title {
    font-size: 0.9rem;
    text-transform: uppercase;
    letter-spacing: 0.5px;
}

.card-text.fs-4 {
    margin-bottom: 0;
}

Practical Example: Replacing the "New Record" Button

Sometimes, the standard "New Record" button isn't sufficient. You might want to change its text, add an icon, or pre-fill the new record form with specific data. This can be achieved by combining a CSS snippet with a Custom Button.

Let's assume we want to replace the standard button in our "Projects" table (technical name: projekte) with a custom one.

Step 1: Hide the Standard Button with a CSS Snippet

First, we need to hide the default "New Record" button. We do this by creating a CSS snippet specifically for our projekte table.

• Create File: setup_adressen/table_projekte_snippet.css

Add the following content to the file. This CSS rule targets the "New Record" button and hides it.

/**
 * CSS Snippet for the "projekte" table view.
 * Hides the default "New Record" button.
 */

/* 
 * This selector targets the link that leads to the "add new record" page.
 * The ID #new-record-button is assigned to this button in the application.
 */
#new-record-button {
    display: none !important;
}

After saving this file, the standard "New Record" button will no longer be visible on the "Projects" table view.

Step 2: Create a Custom Button

Now, we create a new button to replace the one we just hid.

1. Navigate to Settings Custom Buttons.
2. Click "New Button".
3. Fill out the form with the following details:
   • Button Display Name: New Project...
   • Table: Projects
   • URL / Script Path: custom_table_record_edit.php?table_id={table_id}
   • Display Context: List View (global action)
   • Icon: fa-plus-circle (or any other icon you prefer)
   • Color: btn-primary
4. Save the button.

Now, when you go to the "Projects" table view, you will see your new, custom-styled button instead of the standard one.