How To ...

When implementing custom styling, it's not always possible to achieve the desired result just using Style Properties or CSS.
Sometimes it is necessary to edit the template.


The simplest way of applying a custom class is by editing the element and adding it like so:

Rich (BB code):

<div class="section threadList myCustomClass">

The myCustomClass class would then be defined in the EXTRA.css template, or any other applicable CSS template.


Using conditional statements, it is possible to apply different styling based on whether a condition is met or not.
See this resource for more information on using conditional statements: https://xenforo.com/community/resources/conditional-statements.1604/

This example shows how that can be achieved by duplicating the existing line of code and adding a class (myCustomClass) if the condition ($something) evaluates to true:

Rich (BB code):

<xen:if is="{$something}">
    <div class="section threadList myCustomClass">
<xen:else />
    <div class="section threadList">
</xen:if>

Expanding the statement to add more conditions can be done using xen:elseif:

Rich (BB code):

<xen:if is="{$something}">
    <div class="section threadList myCustomClass">
<xen:elseif is="{$somethingElse}" />
    <div class="section threadList myOtherCustomClass">
<xen:else />
    <div class="section threadList">
</xen:if>

An alternative method is to use inline conditional statements.

The simplest version of that adds a custom class (myCustomClass) if the condition ($something) is met:

Rich (BB code):

<div class="section threadList {xen:if '{$something}', 'myCustomClass'}">

Note that for simple cases such as the one above, the quotes are not required and it can be written like so:

Rich (BB code):

<div class="section threadList {xen:if $something, myCustomClass}">

This syntax won't work for all cases however, such as any complex condition, non-alphanumeric characters, etc.


That can be expanded to add a class if the condition is true (myCustomClass) and a different class if it is false (myOtherCustomClass).

Rich (BB code):

<div class="section threadList {xen:if '{$something}', 'myCustomClass', 'myOtherCustomClass'}">

Conditions can also be evaluated against variables or values, like so:

Rich (BB code):

<div class="section threadList {xen:if "{$something} == {$thing}", 'myCustomClass'}">

Conditions can be nested:

Rich (BB code):

<div class="section threadList {xen:if '{$something}', {xen:if '{$somethingElse}', 'myCustomClass', 'myOtherCustomClass'}}">

Arrays can be utilised:

Rich (BB code):

<div class="section threadList {xen:if "in_array({$something}, array({$thing}, {$anotherThing}, {$oneMoreThing}))", 'myCustomClass'}">

The following real use case will apply a custom class (premiumUserGroup) to the message user info block if the member is in a specific user group (5).
Edit the message_user_info template and change this:

Rich (BB code):

<div class="messageUserBlock {xen:if $user.isOnline, online}">

To this:

Rich (BB code):

<div class="messageUserBlock {xen:if $user.isOnline, online} {xen:if "{xen:helper ismemberof, $user, 5}", 'premiumUserGroup'}">

Then add the relevant class to the EXTRA.css template, for example:

Rich (BB code):

.premiumUserGroup
{
    background-color: orange !important;
}

In addition to editing templates and phrases, changes can also be made to the styling and layout, utilising CSS or even editing the HTML.

Working with CSS and HTML requires some knowledge. If you're not familiar with it then one of the many tutorial sites is a good place to start, for example: W3Schools Online Web Tutorials

Once you have identified the component you wish to change, there are multiple ways of doing so, depending on the element.

Once again for this example we're going to use the Staff Online Now block in the forum index sidebar.
In particular we're going to change the styling of the block heading.
Note that if you have multiple styles installed you will need to perform the same changes in each parent style.


The easiest method is to use Style Properties, if one exists for the element you wish to change.
To access the Style Properties, navigate to the ACP -> Appearance -> Style Properties

There is a way of identifying whether an element has a style property, which we will come on to later, but in this instance we can see that there is a Sidebar group, which is more than likely the group we need, so click on it:

As we are interested in the block title, click on the Block Heading item in the list:

Any changes made here will be applied to the block on the forum index, so let's change the text colour to red to see it in action.
Click on the small blue square under Text -> Color

There are multiple ways of entering the color but for this example, type red in the field at the bottom then click the Okay button:

Then click the Update Style Properties button:

When viewing the forum index we can see that the block title color has now changed to red:

However, so have all of the other block titles, which may not be the desired result. Later in this guide we will look at targeting a specific block only.


There are several other ways to achieve the same result, which will be explained in the next steps, but first we need to reset the Style Property to its default state.
Navigate back to the Block Heading style property page and check the Reset box then click the Update Style Properties button:

One other method of changing the styling is to use the EXTRA.css template.
In order to do that you need to know the CSS classes used, which typically requires the use of a browser inspector.
See the guide on identifying templates for how to do that.

In this case the template code (left pane)and CSS classes (right pane) are available by inspecting the specific element:

We can see that the parent div in the left pane has a class of sidebar and the styling applied to the element in the right pane has combined selectors of .sidebar .section .primaryContent h3 a:

To change it we need to load the EXTRA.css template by navigating to the ACP -> Appearance -> Templates
Once the template is loaded, we add our custom CSS to it like so and click the Save All Changes button:

Once again we can see that when viewing the forum index, the block title color has changed:

However, only some have and that is due to using specific selectors in the CSS, in this case the a after the h3, which is specifically for links; the top two block titles are links, the bottom two are not.
This example highlights how using EXTRA.css is better in some cases as it makes it possible to target specific elements, offering more granular control than that which may be available using Style Properties.


If we wanted to just target the Staff Online Now block for example, we would add this to EXTRA.css template instead:

Note the addition of the .staffOnline selector, which is a unique class just for that block.


The result is this:

The final method involves editing the CSS template directly.
Again it is necessary to know the CSS classes in order to do that.
As we already know the classes used from using the browser inspector, it's simply a matter of searching the templates for the class name.
The previous guide relating to identifying templates explains how to do that.

In this case we search for the main class which is .sidebar, resulting in the following list of templates:

It's not always obvious which CSS template you may need to edit, but in this case it is so click on the sidebar.css template.
Once it is loaded we use the browser search function (CTRL+F) to search for the specific classes, in this case .sidebar .section .primaryContent h3 a, which gives:

Now we can edit the CSS directly simply by adding a new rule or overwriting an existing one.
Although this is for the most part standard CSS, there is an additional element in the form of @property tags.
Anything added or changed between these tags will update the corresponding Style Property.

So once again let's change the color to red:

When we now view the corresponding Style Property we can see that it has updated to reflect the change applied in the CSS template:

It was mentioned earlier that not all elements have a Style Property.
In order to identify whether a Style Property exists, search for the CSS in the template using the methods explained previously and look for the presence of @property tags.
If the tags exist you can use the ACP Search feature to locate the Style Property, by entering all or part of the tag name like so:

Clicking on the correct result - the Block Heading in this case - will load the Style Property page.
Hovering over the name in the list will also show the property tag name.

Other options for styling include adding your own custom class to the template, then defining that in the corresponding CSS template, in the EXTRA.css template, or even by calling your own custom CSS template.

There are pros and cons to each approach when it comes to styling. It largely depends on preference, the nature of the element being styled and the extent of the changes.
There is no right or wrong way so experiment and choose whichever you prefer.

Adding custom content can sometimes require the use of a new template.
This can make it easier to keep track of customisations and limit the amount of code added to the default templates.

For example, to add a custom sidebar block you could add your code directly to the forum_list template, as explained in the template editing guide.
However, depending on the amount of code and the nature of it, it may be better to add it to a new template and include that template instead.


To create a new template, navigate to the ACP -> Appearance -> Templates

Select the style in which you want to create the new template. Note that if you have multiple styles installed you will need to create the template in each parent style:

Click on the + Create New Template button:

Enter a template name and the content. It's a good idea to prefix any templates you create, using something unique, to avoid conflicts with the core software and add-ons. In this case the template name is comprised of a prefix (myuniqueprefix_) and a general description of the template use (sidebar_block):

Once saved, the template will then appear in the list:

You can then call the template in any template using this syntax:

Code:

<xen:include template="myuniqueprefix_sidebar_block" />

For this example, we want it to appear in the sidebar on the forum index, so we're going to add it to the forum_list template:

Once saved, we can now see that the new template appears in the row of tabs above the template content:

The content also appears in the sidebar:

Obviously styling can be applied to make it match the existing content and a title can be added:

Which gives a much better result:

To delete the template, either click on the red X in the template list, or click on the template and click the Revert Template... button:

Ensure that all references to it in the templates are removed.

Following on from the previous guide relating to locating a specific template, this tutorial will deal with editing a template.

Once again the examples we're going to use will involve the Staff Online Now block in the forum index sidebar.

We already know that the template we need to edit is the sidebar_online_users template so navigate to the ACP -> Appearance -> Templates and load the template:

Locate the specific block of code you want to edit, in this case it is actually denoted via comment lines:

To remove the block completely, it can be done one of two ways. The first is simply to remove the code:

The other option is to use <xen:comment> tags, which will prevent the content from being rendered:

To move the block to below the Members Online Now block for example, it's simply a case of moving the code:

Conditional statements can be used, for example to prevent unregistered visitors from viewing the block:

You can of course make any other changes as required, such as adding a new class to an element, adding additional elements or removing them (assuming it doesn't result in invalid code), changing phrase names, etc.
Note that if you have multiple styles installed you will need to perform the same edits in each parent style.


Edited templates are denoted as such in the template list via a red X:

To restore it to its original state, either click on the red X, or click on the template and click the Revert Template... button.

If you wish to change the position of certain elements, add something specific, or create a unique style, it may be necessary to edit the templates.

There are several ways of determining which template to edit.
In this guide we're interested in the main forum index, which is the forum_list template and in particular we want to locate the Staff Online Now block in the sidebar.


The first method involves using a browser inspection tool, so typically this requires a desktop computer.

Navigate to the page you wish to identify and load the browser inspector; in Chrome and Firefox pressing the F12 key will do that:

Now click on the [+] to the left of the <body> tag in the inspector window, then do the same for the <headerMover> tag until you locate the <div id="content" class="..."> tag:

The name of the template is the class, so as you can see in this example, it is the forum_list template.


Another way of doing it is by viewing the page source. Again this typically requires a desktop computer.

Navigate to the page you wish to identify and view the page source by either right clicking on the mouse and selecting the option, or by using a keyboard shortcut; in Chrome and Firefox it's CTRL+U. That will produce a browser page like this:

Then just look for the same <div id="content" class="..."> tag or use the browser search function to locate it; CTRL+F in Chrome and Firefox;

Once we have the template name, navigate to the ACP -> Appearance -> Templates

Use the Filter items field to narrow down the list:

Then click on the template name to view it:

However, although we have located the main template, that is not necessarily the template which contains the code we are looking for.
Searching through the forum_list template, there are no references to the Staff Online Now block.
This is because templates often include other templates and frequently the main template acts as a skeleton for all of the content which is present on that page.
You can see where templates are called in the code:

Referring to the image above, note the row of tabs above the template content. Those are all of the templates included in this template.
As we are interested in a block in the sidebar, it's safe to assume that the code we are looking for is in one of those.

So, clicking on the sidebar_online_users tab, we can see that is indeed the correct template:

Another alternative way of identifying a template involves using the phrases. This doesn't require a desktop computer so is an option if you don't have access to one. It is also quite often quicker and more direct than doing it via one of the methods above.

Look for a unique phrase on the page, in this case we are going to use the Staff Online Now phrase.

The next step is to identify the actual phrase; see this guide for how to do that: Locating And Editing Phrases


In our case, the phrase is staff_online_now:

Once we have the phrase name, we can do a search in the templates for it. Navigate to the ACP -> Appearance -> Search Templates

Enter the name of the phrase in the Template Contains field, like so:

Which returns the following results:

As you can see, the end result is the same, which is the sidebar_online_users template, but by using the phrase approach, we located it directly, rather than via the main template which calls it.

That is something to bear in mind when working with templates.

Rather than editing an existing phrase, or inserting text directly into a template, sometimes it's better to create a new phrase.

This is especially true if the text is going to be used in multiple locations, making it quicker and easier to update and less prone to errors.


To create a new phrase, navigate to the ACP -> Appearance -> Phrases

Select the language in which you want to create the new phrase. Note that if you have multiple languages installed you will need to create the phrase in each parent language:

Click on the + Create New Phrase button:

Enter a title and the phrase text. It's a good idea to prefix any phrases you create, using something unique, to avoid conflicts with the core software and add-ons. In this case the phrase title is comprised of a prefix (myuniqueprefix_) and the phrase text (this_is_my_phrase):

Once saved, the phrase will then appear in the list:

You can then call the phrase in any template using this syntax:

Code:

{xen:phrase myuniqueprefix_this_is_my_phrase}

To delete the phrase, either click on the red X, or click on the phrase and click the Revert Phrase... button:

Ensure that all references to it in the templates are removed.

There are several ways of searching for phrases.

The easiest method of identifying a particular phrase, is by following these steps.


Access the phrase search page by navigating to the ACP -> Appearance -> Search Phrases

Enter a snippet of the text you wish to find, like so:

That will return a list of matching phrases - the more specific you are, the fewer the matches will be. If there are no matches, be less specific:

The other way requires knowing the phrase name, or making an educated guess as to what it may be.


Access the main phrase list by navigating to the ACP -> Appearance -> Phrases

Enter a portion of the phrase name in the Filter items field. Again it will return a list of matching phrases, like so:

In this example we are interested in the first phrase in the list of results, so click on it:

Then edit the phrase text (not the title) and save. Note that if you have multiple languages installed you will need to edit the phrase in each parent language:

The new phrase text will now be displayed in place of the original text.


When viewing the phrase list, the edited phrase will have a red X to denote that it has been edited.

To restore it to its original text, either click on the red X, or click on the phrase and click the Revert Phrase... button.