Styling

While XenForo ships with a stylish and modern appearance, there will always be sites that need their forum to match the style of their existing material and theme, and will need to modify XenForo to fit in.

XenForo is equipped with a range of tools to allow you to re-style your forum in as subtle or radical a fashion as you wish.

You may want to simply adjust some colors, or you might want to dramatically change the way everything looks by making completely custom HTML templates.

The tools available for style adjustment and modification range from simple, easy-to-use controls to adjust things like colors, fonts and sizes, right through to code editors for experts, that allow you to edit the CSS and HTML upon which the entire system is built.

Styles

All stylistic tools in XenForo are bundled into collections of data called Styles, which are sometimes referred to as Skins or Themes.

Styles consist of HTML templates, CSS/LESS templates and Style properties, which are collections of values that are used to inject stylistic choices into templates. More on style properties later...

When you first install it, XenForo comes with a single default style, called Default style. You are free to edit any aspect of this style, but you could also make use of another of XenForo's abilities, namely the ability to have multiple styles available.

By adding a second style, you can freely switch your view between your new style and the default style to ensure that everything is going to plan.

Pre-built styles

There are a host of designers and programmers producing styles for the XenForo system, so you may be able to find a professionally-designed, pre-built style that meets your needs.

Applying a pre-built style to your own XenForo installation takes only a few minutes and is easy enough for most site administrators to manage.

A wide variety of pre-built styles are available in the XenForo Resource Manager.

Setting the default style

When your site has multiple styles installed, you can specify which of the installed styles will be served to visitors who have not specified their own preference.

To do this, visit the Appearance section of the main XenForo options system, and select the style you want to act as the default using the Default style option.

Note

The default style for your site need not be the style called Default style - this is just the name applied to the style that is created with your intial XenForo installation, which you can rename if you wish.

You can also specify the default style for HTML email in the same place.

Style inheritance

When you add a new style, you will need to choose whether or not your new style will be a child of an existing style.

If you choose not to have a parent style, your new style will automatically inherit all of its data from the invisible Master style, which is normally hidden from view.

Alternatively, if you create a new style as a child of the Default style, it will automatically inherit all of the data from the Default style, which in turn inherits its data from the Master style. Any changes made at any time to the Default style will instantly be inherited by your new child style, unless the child style has itself made modifications to the data item(s) that were changed in the parent style.

Confused yet?

Don't worry, it's much more simple than it sounds.

Let's look at an example, in which we are going to work with a style called 'My style', which was created as a child of Default style.

  • (1) Default style
    • (2) My style

We are going to imagine that we are changing the value of a Style property called textColor, which controls the color of most of the text seen within XenForo.

Before we change anything at all, the value of textColor is @xf-paletteNeutral3, which is itself a reference to a color in the XenForo palette that is a very, very dark grey. It's basically black.

This value is set in the Master style, is inherited by the Default style, and is therefore also inherited by My style.

Now let's imagine that we change the value of textColor in Default style to blue. As soon as we do this, the effective value of textColor in My style will also become blue, because the change is inherited from Default style.

Changing inheritance

In the example above, My style inherited a customized blue value for the textColor style property from its parent style, Default style.

However, this blue value was only ever inherited, so if we went back to the style manager and changed My style to have no parent, the blue customization would disappear from My style.

Overriding inheritance

With My style inheriting blue as the value of textColor from its parent, Default style, it is possible to override this inheritance by customizing the value within My style itself.

If we edit the value of textColor in My style and set it to red, the blue value will no longer be inherited from Default style, because My style has its own customized value, which overrides the inherited value.

Inheritance summary

XenForo's style inheritance abilities allow you to build collections of styles that inherit from one another, so you only need to make minor changes in child styles, which inherit customizations from their parents.

Consider the following tree of styles, where each style's name describes a customization made to that style.

  • (1) Default style
    • (2) Custom header
      • (3) Big footer
        • (5) Red background
        • (6) Blue background
      • (4) Small text
        • (7) Red background
        • (8) Blue background

In this example, (2) Custom header is a style that customizes the appearance of the main site header in order to fit in stylistically with the rest of the site.

Both (3) Big footer and (4) Small text inherit this custom header from their parent style. Each of these styles has two child styles, which customize the color of the background to red or blue. All of these styles inherit the custom header from the top-level custom style.

Style properties

Style properties allow administrators to quickly and easily adjust things like colors, sizes and fonts for their styles.

The values for all properties in a style are inherited from its parent style(s), unless they are specifically customized within the current style.

All properties are arranged into logical groupings on the Style properties manager page. Clicking on a group name will open the editor for that group of style properties.

Style properties can be any of a number of property types, depending on the data they are designed to control.

Some properties are designed to hold a single value, including the following types:

  • Colors
  • Text values
  • Numbers with units (like 10px)
  • Numbers without units
  • On/off switches
  • Multiple-choice options

Other properties are designed to hold a collection of values which are grouped together to define styling rules for particular interface elements. These CSS type properties can include values for any of the following:

  • Text color, size, font and style
  • Background style
  • Border size, style, color and radius
  • Padding and margin
  • Extra CSS rules

Colors

Let's look at a simple group of properties, which are viewable under the Color palette group in the style property manager.

Here, we have a number of colors defined, which are used to define the complete color palette used by XenForo to build its interface. Changing any of these colors will replace all instances of that color throughout the system.

Additionally, there is a switch to set the style type as Light or Dark. This switch is used to define how colors are modified when the system wants to mix, intensify or diminish a color. For example, if the style type is set to Light and the system wants to intensify a color, the color will be darkened, while the color would be lightened if the style type were set to Dark.

The colors set in the palette are referenced throughout the XenForo system, most importantly in the second group of properties in the style property manager, Basic colors.

In the Basic colors group, colors from the Color palette are assigned to roles, such as Text color and Content background color. Style properties are referenced using the prefix @xf- followed by the unique ID of the style property to be referenced, so to reference the style property Neutral 3 from the Color palette, whose unique ID is paletteNeutral3, we to refer to @xf-paletteNeutral3. You can see that in the Default style, the Text color style property (textColor) uses the value from this property.

More advanced properties

From the style property manager, open the Header and navigation group.

Here, you will find style properties that control the appearance of the top of all your XenForo pages, including the header and the public navigation.

Some of the properties here are single-value properties, such as the Header adjustment color, which defines a color for the background of the inbox and alerts area in the header.

Further down the page, you will find some advanced properties, which are arranged into logical groups.

Opening up the Header/logo row group, you will find a collection of properties that are used to style the main section of the header. In the Default style, we only make use of two values here, namely the color for any text in the header, which we set to use Color 2 from the palette, or @xf-paletteColor2, and the main background color, which we set to use Color 5 from the palette, or @xf-paletteColor5.

Clicking on the color chip next to the name of the color in use will open a popup, in which you can select a different color from either the basic colors range or the color palette, or you can use the Picker to choose a completely new color. Once you have selected the color you want, click the Update button, and the control will be updated. Hit the Save button and you will see the change you have made when you next load a page on the public-facing area of your XenForo installation.

By building a collection of customized style properties in this way, you can dramatically change the appearance of your XenForo site.

Templates

The final output of all XenForo pages is controlled by Templates. Templates contain either HTML or CSS/LESS, along with special language enhancements for XenForo called template syntax, which allow data to be manipulated directly within the templates rather than having to write PHP code to do the job.

Templates containing CSS/LESS styling rules have a .less or .css file extension and do not contain HTML. They serve as containers for rules that include style properties, and define how the HTML in the remaining templates should be displayed. The values of style properties within LESS/CSS templates are referred to using the @xf-stylePropertyName system.

The HTML templates contain the markup that presents your XenForo data to the world, and can contain PHP variables {$variableName}, special XenForo tags <xf:tagname ...> and XenForo template functions {{ functionName($arg1, $arg2, ...) }}.

All templates can be customized using the template editor, but you should be aware that careless edits can break important site functionality if you don't know what you're doing.

Template inheritance

As with style properties, templates are inherited from parent styles unless they have been customized in the current style.

Upgrading with customized templates

When you customize a template, the changes are saved and will not be overwritten unless you specifically instruct the system to do so.

While this can prevent unwanted changes, it also means that your customized templates may become outdated when it comes time to upgrade XenForo to a newer version, if that newer version contains an updated version of the template you have customized.

There are two tools available to help you avoid this.

Outdated templates

After you run a XenForo upgrade, the system will alert you to any templates that you have customized that have become outdated.

A list of these templates will be displayed, along with a Merge option, which will compare your customized template to the new version and attempt to merge your customizations into the newly updated version of the template.

However, if you made custom changes to a section that also changed in the new version of the template, this creates a conflict that you will have to manually resolve. You need to choose which version of the conflicting section to use (or both versions).

When you select the Merge link for a template that is listed as being outdated, you will see what the final, merged version of the template will be. Successfully merged sections will be highlighted in blue. Conflicting sections will be highlighted in yellow with buttons to help you resolve the conflict. Once you have resolved any conflict, you may click on the text to edit it to fit your exact needs.

Note

After running a XenForo upgrade, you should check immediately to ensure that your templates are not outdated, because important or new functionality may be broken or missing if an outdated template remains unmanaged.

Template modifications

As an alternative to customizing templates directly, XenForo also offers a system called Template modifications, which works by allowing you to pick a template, specify a section of the template to find, and a way to insert new template code to modify the specified section.

In the template modification manager, you will find a list of all template modifications currently in use, grouped by the add-on which has defined them. You may quickly disable and re-enable any template modification by using the toggle gadget in the list.

Clicking on one of these modifications, or clicking the Add template modification button, will load the template modification editor.

Within the editor, the controls available, along with the name of the template to be modified, are as follows:

Modification key

Use this to define a unique identifier for your modification. Letters, numbers and underscores are allowed.

Description

Should contain a short description of the functionality of your modification, like Adds a new tab to the member profile page.

Template contents

This box is for reference only, and contains the full text of the template to be modified.

Search type

In many cases, you will want to use a Simple replacement here, whereby the system will search for some text and then replace it in its entirety.

You may also use a regular expression if you want to do more complex matching, or if you want to maintain some or all of the matched text in your modification.

Advanced users may specify a PHP callback to have full control over the way the modification operates.

Find

Enter the text here that the modification is going to replace, the type of text you specify should match the requirements of the Search type.

Many XenForo templates include special <!--[XF:name_goes_here]--> place holders in useful locations, which allow you to quickly and easily enter the token code as the Find text for your modification.

Replace

Here, you should enter the HTML code that will replace the text you specified in Find.

As this HTML will be inserted into a template, you may make full use of XenForo template syntax within your code.

If you would like to include the text that was found along with your new HTML, you can include by using the token $0 in your HTML.

If your Find text was a regular expression, any additional matches from that expression can be inserted using $1, $2 etc.

Execution order

Several template modifications may attach to the same template. The Execution order value is used to determine the order in which these modifications will be applied. Modifications with lower execution order numbers will run before those with higher values.

Note

Even though template modifications are the safest way to customize XenForo templates, it is still wise to double-check that your modifications have not blocked or broken any new or altered functionality if the templates to which they attach have been modified following a XenForo upgrade.