The XenForo 2 template syntax is a powerful tool for both developers and forum administrators, giving you complete control over the layout of your XenForo pages.
- XenForo tags, by convention, are
- All XenForo tags are prefixed with the
Commenting up your templates#
If you want to comment out some template code (or an inspirational message) that you don't want viewable in the final page source, you can use the
Including another template in a template#
xf:include tag allows you to include a different template in your current template.
Simply set the
template attribute to the name of the template you want to include.
Template macros are a very powerful aspect of the XenForo template syntax.
You should generally use a macro any place you would use a function or subroutine in a programming language. For non-programmers, I'd summarize this as: either use a macro any place you want to produce the same thing multiple times in multiple different files or to produce something different under different circumstances (this would probably make more sense if you check the guide on defining a macro).
For readability reasons, you should not use a macro tag as a variable. You should instead use the Set tag and treat the variable as you would any template variable.
Defining a macro#
At its simplest, a macro can be defined with a
name attribute and the content you want repeated inside the macro tag.
When you're using a macro in multiple files, it's best practice to put the macro in it's own template.
In this example, a macro is defined with a default value for
My amazing macro message!).
This value would be overridden if the macro was called with the message argument.
Sometimes it's necessary to mark an argument as required. This can be done by setting the argument value to
! in the macro definition.
Including & using macros#
At it's simplest, you include a macro by setting the
name attribute and leaving the tag empty.
When using a macro tag, you should use the self-closing form of the tag to allow someone to more easily distinguish the difference between a definition and usage of a macro.
You can also provide arguments to the macro:
argName is the name of the macro argument.
You should use
lowerCamelCase for your macro argument names.
Template control structures#
The XenForo 2 template syntax supports certain control structures to make certain tasks easier to achieve.
The if template tag can be used to conditionally display some HTML or a part of a template.
The if tag takes the following attributes:
is- The condition which, when met, the tags contents should be shown.
is attribute supports a few logical operators:
OR- Used to link alternative conditions. (Alternatives:
AND- Used to link additional conditions. (Alternatives:
!- Place before a condition to invert it. (Known as: 'not')
XOR- Returns true if only one of two conditions is true. (Known as: Exclusive OR)
The else and else-if tags are used in conjunction with the if tag to conditionally display HTML in the way that the name suggests.
Example usage of else:
Example usage of else-if:
<xf:if is="$xf.visitor.is_admin"> <!-- Content here will only be shown to Administrators... --> <xf:elseif is="$xf.visitor.is_moderator" /> <!-- Content here will only be shown to Moderators (excluding users who are also Administrators). --> <xf:else /> <!-- Content here will be shown to anyone who is not an Administrator, or a Moderator. --> </xf:if>
As you can see, once a condition has been met, the rest of the if statement is ignored. (So, in this case, if the user is an Administrator, the top
xf:if section is run but then the rest of the if statement is ignored.)
The for-each tag allows you to loop over an array of items, printing a block of HTML for each item.
The for-each tag takes the following attributes:
loop- The array to loop over.
key- A variable name to use in the loop to get current element's array key. Can be integer (ordinary array) or string (associative array).
value- A variable name to use within the loop, containing the current array item.
i- A variable name to use in the loop for the current index.
Hello there, Patrick. This is name number 1. Array key of this element: 0
Hello there, Theresa. This is name number 2. Array key of this element: 1
Hello there, Kimball. This is name number 3. Array key of this element: 2
Hello there, Wayne. This is name number 4. Array key of this element: 3
Hello there, Grace. This is name number 5. Array key of this element: 4
Inserts a user's avatar in the page.
The avatar tag takes the following attributes:
user- The XenForo User object to generate the avatar for.
size- The size of the image to generate. (See image sizes)
canonical- Whether to use the full SEO-friendly URL. This value is only respected for
notooltip- Whether the tool-tip displayed when hovering over the avatar should be disabled.
forcetype- Can be used to force getting the
customavatars by setting the value to either of those.
defaultname- The username to use if the
userattribute contains an invalid user.
If an avatar of invalid size is provided, the code will fallback to size '
Modifies the page breadcrumb.
The breadcrumb tag takes the following attributes:
href- The link to set for the final element in the breadcrumb.
The value of the tag can be used to set the name of the final element in the breadcrumb.
You can also define your own breadcrumb programmatically by calling your function in the
source attribute of the breadcrumb tag.
source parameter essentially takes an array of objects with
value attributes (multidimensional array), where each object is a breadcrumb element.
If you want to change the root breadcrumb, you can change the "Root breadcrumb" option in the "Basic board information" options section.
Adds a button element with the appropriate classes and optionally an icon.
The button tag takes the following attributes:
icon- The icon class to apply to the button. (See button icons)
By default, XenForo buttons support the following icons (created with CSS):
Executes a PHP Callback method.
The callback tag takes the following attributes:
class- The class (from the root namespace) containing the method to run.
method- The method to run. (See callback methods)
params- An array of parameters to provide to the method.
For a method to be considered a callback method, it must be named appropriately or it will throw an error '
callback_method_x_does_not_appear_to_indicate_read_only'. For it to be considered read-only, the method name must begin with one of the following prefixes:
Includes a CSS or LESS template file.
The CSS tag takes the following attributes:
src- The CSS or LESS template file to include.
If the CSS tag is not empty, anything in the tag will be converted into inline CSS.
For [CSS], forget about calling them as files. Copy and paste them into new templates.
Chris D, XenForo developer Source: https://xenforo.com/community/threads/including-external-library-js-and-css.136153/post-1185631
The JS tag takes the following attributes:
src- The JS file to include in the template.
prod- The JS file to include in the template, only for production mode.
dev- The JS file to include in the template, only for development mode.
min- Whether or not to include the minified version of the file. (Replaces
.min.js) - Respected only in production mode.
addon- Whether or not the development JS URL should be used. - Respected only in development mode.
src tag cannot be used in conjunction with either the
If the JS tag is not empty, anything in the tag will be converted to inline JS.
/js directory. Although not recommended, you can also include external resources with this tag.
A good example of this tag is in the
The set tag allows you to create a reference to another variable or create a new variable. You should use the set tag anywhere you would use a variable in a programming language.
Do not use the Set tag for a group of elements you wish to use in multiple templates, you should instead use the Macro Tag.
The variable name (
var attribute) must begin with a
The set tag takes the following attributes:
var- The name of the variable you wish to define (essentially, the alias).
value- A variable to reference to or a variable value.
value attribute is not provided, and the tag is not empty, the variable value will be set to the contents of the tag.
When you use the Set tag in this form, the value will be escaped and the resulting value will be a string.
value attribute, whilst not supporting HTML or HTML-like tags does not have this limitation.
Displays the number of likes on a post and a few of the users who've liked the post.
The likes tag takes the following attributes:
XF\Entity\ProfilePostentity to display the 'likes' text for.
url- The URL to display when the 'likes' text is clicked.
You, tlisbon, kcho and 2 others
The format is [
abc and x others] (where the 'thumbs up' emoji represents the 'likes' icon and
abc represents the usernames of the last three users who liked the post.)
See Sectioned Tags.
See Sectioned Tags.
Sets the page's title, both on the page in the
h1 tag and in the browser tab.
Whilst the title can, of course, be hardcoded, it is highly recommended that you use a phrase, both for internationalization and for the added customizability on the site administrator's end.
Includes a widget in the page, or adds a widget to a widget position.
The widget tag takes the following attributes:
key- The widget key, as defined in the widget settings.
position- If set, changes the position that the widget will be rendered.
class- Not to be confused with HTML class, this is the PHP class containing the widget definition.
title- When the
classattribute is used, you can use the
titleattribute to set the widget title.
- You can also provide widget-specific options as attributes when the
classattribute is used.
class tag cannot be used in conjunction with the
Displays the status of a user, in terms of their last action and when that action occurred.
The UserActivity tag takes the following attributes:
user- The user to display the status of.
Viewing page Latest Case Files · 4 minutes ago
The format is [Activity Name] · [Time]
Displays the user's banners in a horizontal list.
The UserBanners tag takes the following attributes:
user- The user to display the user banners of.
An example result of the UserBanners tag.
Displays a one-line summary of a user's profile.
The UserBlurb tag takes the following attributes:
user- The XenForo User Object to display the blurb of.
FBI Consultant · 43 · From United States of America
The format is [Role / Custom Title] · Age · Location
Displays the user's username, optionally with a tool-tip.
The Username tag takes the following attributes:
user- The XenForo User Object to display the name of.
notooltip- Whether or not the tool-tip should be disabled.
href- The link to navigate to when the username is clicked.
The tool-tip will not be displayed if an
href is set, as it won't work and might be misleading to users.
Displays the user's title.
The UserTitle tag takes the following attributes:
user- The XenForo User Object to display the user title of.
Sectioned Tags all call the function
The HTML element that they change is simply the tag name. So the
sidebar tag will modify the sidebar HTML, etc.
mode- The mode of the modification. (See Modification modes)
By default, the modification mode is
replace. (i.e. if the attribute is not specified.)
prepend- Places the contents of the tag at the beginning of the element's HTML.
append- Places the contents of the tag at the end of the element's HTML.
replace- Replaces the element's HTML with the contents of the tag.