Master Xen

One of the most powerful aspects of developing a custom XenForo skin is the ability to modify its underlying templates. Understanding how to effectively customize templates is crucial for achieving the exact look and functionality you desire, while also ensuring your modifications are robust and update-friendly.

What are XenForo Templates?

At its core, XenForo renders your forum pages using a system of interconnected templates. These are essentially HTML blueprints, often mixed with XenForo's own template syntax, CSS definitions (LESS), and JavaScript. When you browse your forum, XenForo assembles these templates to generate the final page.

Accessing and Understanding Templates

You can access and manage templates via your Admin Control Panel (ACP) under Appearance > Styles > [Your Style] > Templates. Here, you'll see a long list of templates, categorized for easier navigation (e.g., forum_list, thread_view, PAGE_CONTAINER).

Key templates to be aware of include:

• PAGE_CONTAINER: This is the master template that wraps almost every page. It defines the overall HTML structure, includes global CSS and JS, and contains the header, footer, and main content area.
• extra.less: Not a template in the traditional sense, but a crucial stylesheet where you can add custom CSS without modifying core LESS files. Any CSS you add here will be applied globally to your style.
• _header.less, _footer.less: These are often used for style definitions specific to the header and footer regions, respectively.

The Golden Rule: Template Modifications (TMs)

NEVER directly edit a core XenForo template unless you absolutely understand the implications and are prepared for potential issues during upgrades.
Direct edits will be overwritten during XenForo updates, causing you to lose your changes and potentially break your style.

Instead, always use Template Modifications (TMs). TMs allow you to find specific sections of a template and replace them, add content before/after them, or remove them, all without touching the original template file. This means when XenForo updates, your modifications are automatically reapplied to the new version of the template (as long as the target code still exists).

To create a Template Modification:
1. Navigate to Appearance > Styles > [Your Style] > Template modifications.
2. Click "Add template modification".
3. Template: Select the template you want to modify (e.g., PAGE_CONTAINER).
4. Modification key: A unique identifier for your modification (e.g., my_custom_footer_link).
5. Description: Explain what the modification does.
6. Find: The exact piece of code you want to target within the template.
7. Replace: The new code, or the code you want to add/modify. You can use variables like {$0} to represent the original "Find" content.

Example: Adding a custom link to the footer
You might find the existing footer navigation (<xf:macro template="extra_macros" name="navigation" arg-type="footer" />) in PAGE_CONTAINER and add your link after it.

Understanding XenForo Template Syntax

XenForo uses a powerful, Twig-like template syntax. Here are some common constructs:

• Variables: {$variable_name} – Used to output dynamic data from the server (e.g., {$xf.options.boardTitle}).
• Phrases: {{ phrase('phrase_key') }} – Used for translatable text strings. Always use phrases for any user-facing text.
• Conditionals: <xf:if is="{$xf.visitor.user_id}">...</xf:if> – Renders content based on a condition.
• Loops: <xf:foreach loop="{$items}" value="{$item}">...</xf:foreach> – Iterates over arrays or objects.
• Includes: <xf:include template="other_template_name" /> – Includes content from another template.
• Macros: <xf:macro template="macro_library" name="macro_name" arg-param="value" /> – Reusable blocks of code, often found in templates like extra_macros or member_macros.
• CSS/LESS: <xf:css src="my_custom_style.less" /> – Includes a LESS file. Often used in PAGE_CONTAINER to load custom stylesheets.
• JavaScript: <xf:js src="my_custom_script.js" /> – Includes a JavaScript file.

Practical Customization Examples

1. Adding Custom CSS:
* For small, global style tweaks, use extra.less. Go to Appearance > Styles > [Your Style] > Style properties > Basic options and click "Edit extra.less".
* For larger, more organized CSS, create a new LESS template (e.g., my_custom_styles.less) under your style's templates, then include it in PAGE_CONTAINER using an <xf:css src="my_custom_styles.less" /> Template Modification.

2. Modifying the Header/Footer:
* Locate the relevant sections in PAGE_CONTAINER. For instance, the header often contains <xf:include template="header" /> or direct markup.
* Use Template Modifications to add/remove elements, or wrap existing elements with your own custom HTML.
* Consider using the xf:if conditional to display content only for guests or logged-in users.

3. Inserting Custom JavaScript:
* For small inline scripts, you can add <xf:js>alert('Hello!');</xf:js> directly into a template via a TM, preferably at the end of PAGE_CONTAINER before the closing </body> tag.
* For larger scripts, create a .js template (e.g., my_custom_script.js) and include it with <xf:js src="my_custom_script.js" /> via a TM in PAGE_CONTAINER.

Best Practices for Template Customization

• Create a Child Style: Always create a child style of the default XenForo style (or the style you're basing your skin on) before making any modifications. This isolates your changes and makes updates far easier.
• Use Browser Developer Tools: Inspect elements to find the exact CSS classes, IDs, and HTML structure you need to target. This is invaluable for finding the "Find" string for your TMs.
• Comment Your Code: Add comments to your Template Modifications and custom LESS/JS files to explain what you're doing and why.
• Test Thoroughly: After any template change, clear your XenForo caches (Tools > Rebuild caches) and refresh your browser (Ctrl+F5 or Cmd+R) to ensure changes are visible and haven't introduced errors.
• Backup: Regularly back up your XenForo files and database, especially before major changes or updates.

By mastering Template Modifications and understanding XenForo's template syntax, you gain incredible control over your forum's appearance and functionality, ensuring your custom skin stands out while remaining maintainable.