Back to overview

Custom Pages

Developer Tutorials Published on 06.11.2025

Tutorial: Custom Pages

This guide explains how to create a completely custom PHP page within a setup folder and integrate it into the application using a custom button and the new navigate action.

1. Creating the Custom PHP Page

First, create your new PHP file inside your specific setup folder (e.g., setup_adressen/). For this example, we'll create a file named tutorial.php.

File: setup_adressen/tutorial.php

This file will contain the full HTML and PHP logic for your custom page. There are two critical points to consider for it to work correctly within the application's structure.

  1. Adjusting the `init.php` Path: Since the file is in a subdirectory, you must adjust the path to include the core init.php file. Use ../init.php.
  2. Setting the Base Path: To ensure all relative links to CSS, JavaScript, and images work correctly, you must add a <base> tag in the <head> of your HTML, pointing to the application's root directory.
Why is the <base> tag so important?
When you access /setup_adressen/tutorial.php, the browser thinks all relative links (like style.css) are in the same folder. The <base href="../"> tag tells the browser to resolve all relative URLs from the parent directory (the application root), ensuring that all assets are loaded correctly.

Example Code for setup_adressen/tutorial.php

<?php
// Define this page as publicly accessible before loading init.php.
define('IS_PUBLIC_PAGE', true);
require_once '../init.php'; // 1. Adjusted path

// Set a page title
$page_title = lang('tutorial_page_title');
?>
<!doctype html>
<html lang="<?= $current_lang ?>">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- 2. Set the base path for all relative URLs -->
    <base href="../">

    <!-- Bootstrap CSS, FontAwesome, etc. -->
    <link href="node_modules/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
    <link rel="stylesheet" href="node_modules/@fortawesome/fontawesome-free/css/all.min.css">
    <link rel="stylesheet" href="style.css">

    <?php include '../theme.php'; ?>
    <title><?= $page_title ?> - <?= lang('my_website') ?></title>
</head>
<body>
    <div class="d-flex flex-column h-100">
        <?php include '../menu.php'; ?>
        <div class="main-content d-flex flex-column flex-grow-1">
            <?php include '../header.php'; ?>
            <main class="container-fluid flex-grow-1 py-4">
                <!-- Your custom page content goes here -->
                <h1><?= $page_title ?></h1>
                <p><?= lang('tutorial_page_text') ?></p>
            </main>
            <?php include '../footer.php'; ?>
        </div>
    </div>
    <script src="node_modules/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
    <script src="js/app.js"></script>
</body>
</html>

2. Integrating with a Custom Button

To make your new page accessible, you can create a custom button. Instead of linking directly, we'll use a small PHP action script that returns a special JSON response. This allows for more flexibility and security, such as checking permissions before navigating.

Step 2.1: The PHP Action Script

Create a new PHP file in your setup folder that will handle the button's action. This script will not produce any HTML. Its only job is to return a JSON object telling the frontend to navigate to a new URL.

New File: setup_adressen/navigate_to_tutorial.php

<?php
require_once '../init.php';

// Set the content type to JSON
header('Content-Type: application/json');

// Optional: Perform a security or permission check here
if (!isset($_SESSION['user'])) {
    echo json_encode(['action' => 'navigate', 'url' => 'login.php']);
    exit();
}

// The URL of the custom page we want to navigate to
$tutorial_page_url = 'setup_adressen/tutorial.php';

// Respond with the 'navigate' action and the target URL
echo json_encode([
    'action' => 'navigate',
    'url' => $tutorial_page_url
]);
?>

Step 2.2: Create the Custom Button

Now, go to Settings → Custom Buttons in the application and create a new button with these settings:

  • Button Display Name: Show Tutorial
  • URL / Script Path: setup_adressen/navigate_to_tutorial.php
  • Display Context: On Homepage (global)
  • Icon: fa-graduation-cap
  • Color: btn-info

How It Works: The `navigate` Action

When you click the "Show Tutorial" button, the application's JavaScript handler (in index.php or custom_table_record_edit.php) performs the following steps:

  1. It sends an AJAX request to the URL specified in the button: setup_adressen/navigate_to_tutorial.php.
  2. The PHP script runs, checks permissions, and returns a JSON response: {"action": "navigate", "url": "setup_adressen/tutorial.php"}.
  3. The JavaScript handler receives this JSON. It sees action: "navigate" and immediately redirects the browser to the provided URL using window.location.href.

This approach is clean, secure, and allows for server-side logic before any redirection happens.

3. Possibilities and Use Cases

This feature of creating custom, integrated pages opens up a wide range of possibilities beyond simple content display. You can build:

  • Interactive Wizards: Guide users through complex data entry processes step-by-step, with custom validation and logic on each page.
  • Advanced Help & Tutorials: Create rich, interactive help pages with videos, diagrams, and specific examples that are deeply integrated into your application's look and feel.
  • Custom Dashboards: Build specialized dashboards that are not possible with the standard chart system. You could use PHP to fetch data from multiple tables, perform complex calculations, and then use a JavaScript library like Chart.js to render unique visualizations.
  • Data Aggregation Displays: Imagine a page that uses cURL to fetch data from an external REST API, combines it with data from your local database, and presents a unified view to the user. For example, you could display a customer's order history from your database alongside their support tickets from an external helpdesk system.

Example: Displaying Data from a Lookup Table

You could create a custom page that displays all entries from a "Countries" lookup table. The PHP script would:

  1. Use DBGet('data_team_..._countries', null, ['*']) to fetch all country records.
  2. Loop through the results and render them in a Bootstrap table.
  3. This provides a quick and easy way to create a view-only page for reference data without needing to configure a full "Custom View".