-
- Joined
- Mar 22, 2026
-
- Messages
- 434
-
- Reaction score
- 10
-
- Points
- 0
Developing an add-on for XenForo 2 allows you to extend its functionality, customize its appearance, or integrate with external services. This guide will walk you through the fundamental steps of creating a basic "Hello World" add-on, establishing the core structure and demonstrating a simple modification.
1. Understanding the Add-on Structure
Every XenForo 2 add-on resides within the
Let's assume your Vendor ID is
Inside this directory, you'll find (or create) several key files and subdirectories:
2. The
This file is crucial. It tells XenForo about your add-on. Create
Key fields explained:
3. Enabling Development Mode
For any add-on development, ensure XenForo's development mode is enabled. Open
The
4. Installing Your Add-on
With
1. Navigate to your XenForo ACP.
2. Go to Add-ons.
3. You should see "My First Add-on" listed with an "Install" button. Click it.
After installation, XenForo creates the
5. Creating a "Hello World" Listener
Let's make a simple modification: displaying "Hello from My First Add-on!" at the top of every page. We'll use an event listener and a template modification.
a. Create the Listener Class:
Create a file
b. Register the Event Listener:
Now, tell XenForo about this listener:
1. In the ACP, go to Development -> Event Listeners.
2. Click Add listener.
3. Fill in the details:
* Event hint:
* Add-on:
* Callback class:
* Callback method:
* Execute order: Leave as default (10).
* Description:
4. Save the listener.
6. Testing Your Add-on
Now, visit any page on your XenForo forum. You should see "Hello from My First Add-on!" displayed prominently at the top of the page.
7. Exporting for Distribution
Once your add-on is complete and you want to share it, you'll need to export it.
1. In the ACP, go to Add-ons.
2. Find your add-on and click the "Export" button.
3. XenForo will generate a
Congratulations! You've successfully built, installed, and tested your first XenForo 2 add-on. This foundation will serve you well as you explore more complex functionalities like custom routes, controllers, entities, and database interactions.
1. Understanding the Add-on Structure
Every XenForo 2 add-on resides within the
src/addons/ directory. It follows a consistent naming convention: src/addons/[VendorID]/[AddOnID]/.- Vendor ID: This is typically your unique identifier (e.g., your company name, forum handle). It should be a short, alphanumeric string.
- Add-on ID: This is the unique identifier for your specific add-on.
Let's assume your Vendor ID is
MyVendor and your Add-on ID is MyAddon. Your add-on's root directory will be src/addons/MyVendor/MyAddon/.Inside this directory, you'll find (or create) several key files and subdirectories:
addon.json: The manifest file that describes your add-on._output/: (Development only) Contains automatically generated development files like phrases, templates, and listeners.Setup.php: (Optional) For database schema changes or initial data.Listener.php: (Optional) Contains event listeners for modifying core behavior.Pub/: (Optional) For public-facing controllers, entities, and templates._data/: (Optional) For custom data that needs to be exported/imported.
2. The
addon.json Manifest FileThis file is crucial. It tells XenForo about your add-on. Create
src/addons/MyVendor/MyAddon/addon.json with the following content:
JSON:
{
"legacy_addon_id": null,
"title": "My First Add-on",
"description": "A simple 'Hello World' add-on for XenForo 2.",
"version_id": 1000010,
"version_string": "1.0.0 Alpha",
"developer": "MyVendor",
"developer_url": "https://example.com",
"run_through_shell": true,
"require": [],
"extra_field_groups": []
}Key fields explained:
legacy_addon_id: Used for upgrading XenForo 1 add-ons; leavenullfor new XF2 add-ons.title: The display name of your add-on in the Admin Control Panel (ACP).description: A brief explanation of your add-on.version_id: An integer representing the add-on's version (e.g.,1000010for 1.0.0 Alpha). This must always increase with new versions.version_string: The human-readable version (e.g.,1.0.0 Alpha).developer: Your name or company name.developer_url: An optional URL for your website.run_through_shell: Set totruefor development. Allows command-line tools to interact with your add-on.require: An array of add-on IDs and their minimum versions if your add-on depends on others.extra_field_groups: For custom fields.
3. Enabling Development Mode
For any add-on development, ensure XenForo's development mode is enabled. Open
src/config.php and add:
PHP:
$config['development']['enabled'] = true;
$config['development']['defaultAddOn'] = 'MyVendor/MyAddon'; // Your add-on IDThe
defaultAddOn setting is convenient as it automatically associates new phrases, templates, and other development output with your add-on.4. Installing Your Add-on
With
addon.json in place and development mode enabled:1. Navigate to your XenForo ACP.
2. Go to Add-ons.
3. You should see "My First Add-on" listed with an "Install" button. Click it.
After installation, XenForo creates the
_output directory within your add-on's folder, which will store development assets.5. Creating a "Hello World" Listener
Let's make a simple modification: displaying "Hello from My First Add-on!" at the top of every page. We'll use an event listener and a template modification.
a. Create the Listener Class:
Create a file
src/addons/MyVendor/MyAddon/Listener.php:
PHP:
<?php
namespace MyVendor\MyAddon;
class Listener
{
/**
* Called when the templater is about to render a template.
* Use this to modify template output.
*
* @param \XF\Template\Templater $templater
* @param string $type
* @param string $templateName
* @param string &$output
* @param array &$containerData
*/
public static function templaterTemplatePostRender(
\XF\Template\Templater $templater,
$type,
$templateName,
&$output,
array &$containerData
) {
// We only want to modify the 'PAGE_CONTAINER' template.
if ($templateName == 'PAGE_CONTAINER') {
// Find a suitable place to insert our message, e.g., after the body tag.
// For this example, we'll prepend it to the content.
$output = '<div style="background-color: #e0ffe0; padding: 10px; border: 1px solid #c0ffc0; margin-bottom: 15px;">Hello from My First Add-on!</div>' . $output;
}
}
}b. Register the Event Listener:
Now, tell XenForo about this listener:
1. In the ACP, go to Development -> Event Listeners.
2. Click Add listener.
3. Fill in the details:
* Event hint:
templater_template_post_render (This is the name of the event XenForo dispatches after a template is rendered).* Add-on:
My First Add-on (MyVendor/MyAddon)* Callback class:
MyVendor\MyAddon\Listener* Callback method:
templaterTemplatePostRender* Execute order: Leave as default (10).
* Description:
Inserts 'Hello World' message into PAGE_CONTAINER4. Save the listener.
6. Testing Your Add-on
Now, visit any page on your XenForo forum. You should see "Hello from My First Add-on!" displayed prominently at the top of the page.
7. Exporting for Distribution
Once your add-on is complete and you want to share it, you'll need to export it.
1. In the ACP, go to Add-ons.
2. Find your add-on and click the "Export" button.
3. XenForo will generate a
.zip file containing your addon.json, _output directory, and any custom code files. This .zip is what you distribute.Congratulations! You've successfully built, installed, and tested your first XenForo 2 add-on. This foundation will serve you well as you explore more complex functionalities like custom routes, controllers, entities, and database interactions.