Add-ons, styles, templates and phrases: how XenForo fits together

A XenForo forum is built from four things: add-ons, styles, templates and phrases. Add-ons change the others without editing XenForo's own files. That is why you can upgrade XenForo and keep your add-ons, and why most problems can be traced to one of these four layers. Knowing which layer does what makes every other guide easier to follow.

Add-ons: new features in their own folder

An add-on is a package of code and data with an ID in the form Vendor/Name. Ours all start with DC, for example DC/Thumbnail. Its PHP code lives in its own folder, src/addons/DC/Thumbnail, and any JavaScript lives under js/. Nothing inside XenForo's own src/XF folder is touched.

When you click Install, XenForo reads the add-on's data files and adds everything it brings: options, permissions, phrases, templates, widgets, cron entries and any database tables it needs. From then on, XenForo loads the add-on's code alongside its own through two hooks:

• Class extensions let an add-on build on one of XenForo's classes, for example to add a thumbnail to every thread.
• Code event listeners let an add-on run code when something happens, such as a page starting to load.

Because every add-on hooks in this way, XenForo can switch one off without deleting it. Disable or uninstall an add-on explains the difference.

Styles: how your forum looks

A style is a complete look for your forum: its templates plus its style properties. Styles can have children. A child style inherits everything from its parent and only stores what you change, which keeps your changes separate from XenForo's defaults. You manage them in Appearance > Styles.

Style properties are the settings of a style: colours, sizes, borders and spacing. Add-ons can add their own, such as the story ring colours in Story. Change colours and sizes with style properties.

Templates: the HTML of every page

Every page is assembled from templates. When you edit a template in a style, XenForo saves your own copy for that style and keeps using it from then on. That is useful, but it means a later update to the original template does not reach your copy. XenForo flags these copies under Appearance > Outdated templates.

Template modifications: how add-ons change pages

An add-on rarely replaces a whole template. Instead it ships template modifications: small "find this, add that" instructions that XenForo applies every time it compiles a template. That way your own template edits and the add-on's changes can live side by side.

The catch: if your style has changed the exact text a modification looks for, the modification cannot find it and silently does nothing. This is the usual reason an add-on works in the default style but not in a custom one. Appearance > Template modifications shows which modifications applied, and this guide shows how to fix the ones that did not.

Phrases: every piece of text

Almost every word on your forum is a phrase, and add-ons bring their own. To change wording, edit the phrase in Appearance > Phrases rather than the template. The change applies everywhere the phrase is used, and it survives upgrades. Each language has its own copy of every phrase.

Which layer to check when something goes wrong

• A feature is missing for everyone. It is usually an option or a permission. See Installed an add-on but nothing shows up?
• It works in the default style but not yours. Check the template modifications.
• A page shows an error. The add-on's code hit a problem, and Logs > Server error log has the details.
• The wording is wrong. Edit the phrase.

Still stuck? Open a support ticket and tell us what you expected to see and what you see instead. That alone often tells us which layer to look at.