Customize templates safely: child styles and template modifications

The safest customization is one an upgrade can't undo. XenForo gives you three tools for that: a child style to hold your changes, the extra.less template for your CSS, and template modifications for small changes to a page's markup. Use them in that order and neither XenForo updates nor add-on updates will wipe out your work.

Why direct edits get lost

XenForo and every add-on ship their own master copy of each template. When you upgrade, the master copies are replaced with the new ones. Two kinds of edit suffer:

• Edits to files on disk, such as anything under src/addons/ or js/. The next upload of that add-on overwrites them without a word.
• Edited templates in a style. Your edited copy is kept, but it is now based on an old master. XenForo lists it under Appearance > Outdated templates, and until you merge it, new features and fixes in that template never reach your forum.

The fewer whole templates you edit, the fewer outdated templates you have to merge after each upgrade. Template modification errors and outdated templates explains the merge.

Keep your changes in a child style

A child style inherits everything from its parent and stores only what you change. If you use a bought theme, you can update the theme itself without touching your own changes, because they live one level below it.

1. Go to Appearance > Styles and click Add style.
2. Set Parent style to the style your forum uses now, and give the new style a clear name, such as "My forum".
3. Make it the one visitors see: Setup > Options > Appearance > Default style.

From now on, make every change in the child style: templates, CSS and style properties alike.

Put custom CSS in extra.less

Every style has a template called extra.less. XenForo includes it on every page and ships it empty, so it never goes out of date. Open Appearance > Templates, pick your child style at the top, and search for extra.less. Anything you add there applies across the whole forum.

.p-header {
    border-bottom: 3px solid @xf-borderColorHeavy;
}

Using style property variables like @xf-borderColorHeavy keeps your CSS in step with the style's colours. For plain colour and size changes, try style properties first. Change colours and sizes with style properties.

Change markup with template modifications

When you need to add, move or remove something in a page's HTML, don't edit the whole template. Add a template modification instead: Appearance > Template modifications, then Add template modification.

• Choose the template, then what to Find and what to Replace it with.
• Use Simple replacement for exact text, or Regular expression when the text varies.
• Pick a short, distinctive piece of text to find, so the modification still matches after an upgrade.

A modification is applied on top of the current master template every time the template is compiled. That is exactly how add-ons change XenForo's pages, and why it survives upgrades: as long as the text it searches for still exists, it keeps working. Check the modification's log after each XenForo upgrade to confirm it still applies.

Leave add-on files and templates alone

If you'd like a D.C Style add-on to look or behave differently, change it from the outside: CSS in extra.less, or a template modification on the add-on's template. Never edit its PHP or JavaScript files, since each update replaces them. If what you need isn't possible that way, tell us. It may make a good option for everyone. How XenForo fits together explains where each piece lives.

Tip: Try bigger changes on a private test copy of your forum first. Your license covers test copies of the same forum. See what your license covers.

Still stuck? Open a support ticket with the change you're trying to make and the template it's in, and we'll point you to the safest way to do it.