-
- Joined
- Mar 22, 2026
-
- Messages
- 434
-
- Reaction score
- 10
-
- Points
- 0
XenForo offers robust tools for forum management, but its underlying framework also provides extensive flexibility for building custom pages and routes. This guide details the process of creating a standalone custom page within your XenForo installation, complete with its own URL, controller logic, and template. This is invaluable for adding static content, custom data displays, or unique application features directly into your forum's structure.
Prerequisites
To follow this guide effectively, a basic understanding of PHP, XenForo's add-on development structure, and template syntax is beneficial. We'll be working with files within an add-on, which is the recommended way to extend XenForo.
Step 1: Define Your Route
A route maps a specific URL path to a controller and an action within that controller. For a custom page, you'll typically define a public route. While routes can be added via the Admin Control Panel, defining them within your add-on's
File:
Explanation:
* The second (
* The third (
* The fourth (
After modifying
Step 2: Create Your Controller
The controller is the PHP class that receives the request for your custom page's route, processes any necessary data, and then decides which template to render.
File:
Explanation:
*
*
Step 3: Craft Your Template
The template is the HTML structure that defines how your custom page will look. It will receive the data prepared by your controller.
File:
Explanation:
Step 4: Add to Navigation (Optional)
Once your custom page is functional, you'll likely want to add a link to it in your site's navigation.
1. Go to your Admin Control Panel.
2. Navigate to Appearance > Navigation.
3. Click Add navigation entry.
4. Entry type: Select "Basic".
5.
Prerequisites
To follow this guide effectively, a basic understanding of PHP, XenForo's add-on development structure, and template syntax is beneficial. We'll be working with files within an add-on, which is the recommended way to extend XenForo.
Step 1: Define Your Route
A route maps a specific URL path to a controller and an action within that controller. For a custom page, you'll typically define a public route. While routes can be added via the Admin Control Panel, defining them within your add-on's
Setup.php file ensures they are properly installed and uninstalled with your add-on.File:
src/addons/YourVendor/YourAddonId/Setup.php
PHP:
<?php
namespace YourVendor\YourAddonId;
use XF\AddOn\AbstractSetup;
use XF\AddOn\StepRunnerInstallTrait;
use XF\AddOn\StepRunnerUninstallTrait;
use XF\AddOn\StepRunnerUpgradeTrait;
class Setup extends AbstractSetup
{
use StepRunnerInstallTrait;
use StepRunnerUninstallTrait;
use StepRunnerUpgradeTrait;
public function installStep1()
{
$this->app->routeManager()->addRoute(
'your-custom-page', // Unique route name
'your-page/', // The URL path (e.g., yourdomain.com/your-page/)
'YourAddonId:YourController', // Controller class in format AddonId:ControllerName
'your-custom-page' // Route prefix (optional, but good for organization)
);
}
public function uninstallStep1()
{
$this->app->routeManager()->deleteRoute('your-custom-page');
}
}Explanation:
addRoute(): Registers a new route.
your-custom-page) is a unique identifier for this route.* The second (
your-page/) is the actual URL path users will access.* The third (
YourAddonId:YourController) specifies which controller and which add-on will handle this route. YourAddonId refers to your add-on's ID (e.g., Demo), and YourController is the name of your controller class.* The fourth (
your-custom-page) is an optional route prefix.deleteRoute(): Removes the route during uninstallation.
After modifying
Setup.php, you'll need to rebuild your add-on (or disable/enable it) for the route changes to take effect.Step 2: Create Your Controller
The controller is the PHP class that receives the request for your custom page's route, processes any necessary data, and then decides which template to render.
File:
src/addons/YourVendor/YourAddonId/Pub/Controller/YourController.php
PHP:
<?php
namespace YourVendor\YourAddonId\Pub\Controller;
use XF\Mvc\ParameterBag;
use XF\Pub\Controller\AbstractController;
class YourController extends AbstractController
{
/**
* Action handler for the route 'your-page/'.
* By default, if no specific action is specified in the route, actionIndex() is called.
*
* @param ParameterBag $params
* @return \XF\Mvc\Reply\View
*/
public function actionIndex(ParameterBag $params)
{
$visitor = \XF::visitor(); // Get current visitor object
// Define a title for your page. Using phrases is good practice.
// Ensure 'your_custom_page_title' is defined in your add-on's phrases.
$pageTitle = \XF::phrase('your_custom_page_title');
// Example: Fetch some data or perform logic here
// $someData = $this->finder('YourAddonId:YourEntity')->fetch();
// Prepare data to be passed to the template
$viewParams = [
'pageTitle' => $pageTitle,
'message' => 'Welcome to your custom XenForo page!',
'visitor' => $visitor, // Pass visitor object to template
// 'someData' => $someData,
];
// Return a View reply, specifying the template to render
return $this->view('YourAddonId:YourPage', 'your_addon_your_page_template', $viewParams);
}
// You can add more actions, e.g., public function actionView(ParameterBag $params)
// This would handle routes like your-page/view/
}Explanation:
namespace YourVendor\YourAddonId\Pub\Controller;: Defines the namespace for your controller.class YourController extends AbstractController: Your controller must extend\XF\Pub\Controller\AbstractController.actionIndex(ParameterBag $params): This method is automatically called when the base route (your-page/) is accessed. TheParameterBagcontains any dynamic parameters from the URL.$this->view('YourAddonId:YourPage', 'your_addon_your_page_template', $viewParams): This is crucial.
YourAddonId:YourPage: This is the canonical name for your view, used for caching and internal references.*
your_addon_your_page_template: This is the actual name of the template file (without .html extension) that will be rendered.*
$viewParams: An array of data that will be available as variables within your template.Step 3: Craft Your Template
The template is the HTML structure that defines how your custom page will look. It will receive the data prepared by your controller.
File:
src/addons/YourVendor/YourAddonId/templates/public/your_addon_your_page_template.html
HTML:
<xf:title>{{ $pageTitle }}</xf:title>
<xf:h1>{{ $pageTitle }}</xf:h1>
<div class="block">
<div class="block-container">
<div class="block-body">
<p>{{ $message }}</p>
<p>This content is rendered from your custom template located at `src/addons/YourVendor/YourAddonId/templates/public/your_addon_your_page_template.html`.</p>
<xf:if is="$visitor.user_id">
<p>Hello, {$visitor.username}!</p>
<xf:else />
<p>You are currently browsing as a guest.</p>
</xf:if>
<p><a href="{{ link('forums/') }}" class="button--link">Back to forums</a></p>
</div>
</div>
</div>Explanation:
<xf:title>{{ $pageTitle }}</xf:title>: Sets the page title displayed in the browser tab.<xf:h1>{{ $pageTitle }}</xf:h1>: Displays a prominent heading on the page.{{ $message }}and{{ $visitor.username }}: These are template variables, populated by the$viewParamsarray from your controller.<xf:if is="$visitor.user_id">: XenForo's template syntax for conditional logic.{{ link('forums/') }}: Generates a URL to the forums index, demonstrating how to link to other XenForo routes.
Step 4: Add to Navigation (Optional)
Once your custom page is functional, you'll likely want to add a link to it in your site's navigation.
1. Go to your Admin Control Panel.
2. Navigate to Appearance > Navigation.
3. Click Add navigation entry.
4. Entry type: Select "Basic".
5.
