Creating & Modifying Styles

On this page, you will find some basic as well as more advanced instructions which can help you in creating your own style for phpBB 3.2.x/3.1.x, or modifying an existing one to suit your needs.

The focus will be on creating a new style, based on an existing style. Besides the fact that this is the most likely scenario for most style authors, it also creates a better understanding of the template-engine and style-system as a whole in more diverse situations.

Note: This guide is a continuation of the Editing Styles section of the Installing & Using Styles page. Please read it before using this guide, as we will not repeat it here.
Note: A good understanding of HTML, CSS (and JS) is required. There are tons of information about web-design available on the internet, so we will only focus on things that are unique to phpBB 3.2.x/3.1.x.
Pro-Tip: The best way to learn how to create (or modify) styles is by learning from examples. Have a look at some of the popular styles in the Styles Database and the [3.1.x] and [3.2.x] Styles in Development forums and see how they work.

Quick FAQ

Can I submit a style to the phpBB.com Styles Database?
Yes, you may submit a style that you created and you'd like to share with the community. The phpBB Style Customisations Team will review your submission and if it is error-free it will be added to our database.
Are there rules I need to read before submitting a style to the Styles Database?
Yes. All submitters should read the Styles Submission Policy to see the rules for submitting styles to our database and to learn how to actually submit the files.
Why don't my changes to templates or CSS files appear on my website?
This is most likely due to caching. phpBB's template-engine has to process (compile) the style's templates before it can display them. This is resource-intensive process, so it "caches" the finished pages for quicker access. If you make changes to template files, you will need to "purge" (clear) the board's cache (or else your changes will not appear). You can do this by navigating to the board's ACP and clicking the button at "Purge the cache".
Additionally, your browser might also be loading an old cached version of the assets. Be sure to "hard-refresh" your browser, by using a command like CTRL+F5.
If a style has not been updated by the original author, can I update it myself and submit it to the database?
If the original author no longer wishes to update it themselves, they must give express permission to someone to take over their work.
If the original author is unreachable, however, then you may update the style and submit it (specifying that this is the case in the submission, in the "Message to Style Customisations Team" field). If the original author returns after this, though, then they can then reclaim the style if they wish. The original author would have the option to keep any updates done by you or to use/integrate them as they wish.

File Structure

As mentioned in the Installing & Using Styles guide, styles have a specific directory structure, which should be adhered to. We strongly advise you to follow the same structure, as this will minimize the chances of "file not found" problems.

styles/
    my_style_name/
        template/
            overall_header.html
            my_scripts.js
        theme/
            images/
                background.jpg
            stylesheet.css
            extra.css
        style.cfg

Preparation

Note: Always(!) make a backup of your board's files and database before making changes to the code. It's generally very difficult to provide support for users that mess things up by editing code themselves.

Choosing a "Base" Style

Since creating a completely new style is a massive undertaking (and requires a lot of skill, in which case you won't need this guide anyway), we need to choose an existing style to use as a "base".

As you will probably spend many hours creating your new style, choosing the right "base" style is essential. You want a solid foundation for your style. The easiest choice is obviously to use the default phpBB 3.2.x/3.1.x style (prosilver) as a base, since it includes all the new features and has been thorougly tested.

Choosing a style (like prosilver) which has all the current template events in place will also ensure that extensions will function properly. Read more on this subject in the template events section.

Create a "skeleton"

The first thing that needs to be done is creating the file structure for your new style. See the file structure section to see what a basic skeleton looks like.

When you have created all the required directories (template, theme, images) and the style.cfg and stylesheet.css files, you are ready start copying templates and theme assets that you want to use.

Note: We advise you to read the rest of this guide before proceeding.
Pro-Tip: Don't edit existing styles. Instead, create a copy of the style you want to change, and edit the new style.cfg so that it will inherit from the original style. Read the template inheritance and asset inheritance sections for more information.

Style.cfg

The most important file of any style (as far as installation goes) is the style.cfg file. It provides information to your phpBB board about how to install and process the style. It generally looks like this:

#
# phpBB Style Configuration File
#
# This file is part of the phpBB Forum Software package.
#
# @copyright (c) phpBB Limited <https://www.phpbb.com>
# @license GNU General Public License, version 2 (GPL-2.0)
#
# For full copyright and license information, please see
# the docs/CREDITS.txt file.
#
# At the left is the name, please do not change this
# At the right the value is entered
#
# Values get trimmed, if you want to add a space in front or at the end of
# the value, then enclose the value with single or double quotes.
# Single and double quotes do not need to be escaped.
#
#

# General Information about this style
name = prosilver
copyright = © phpBB Limited, 2007
style_version = 3.2.0
phpbb_version = 3.2.0

# Defining a different template bitfield
# template_bitfield = lNg=

# Parent style
# Set value to empty or to this style's name
# if this style does not have a parent style
parent = prosilver
		

Most of this is pretty self explanatory. The most important values for our purposes are the name and parent fields, which indicate template inheritance.

Let's say that we want to create a style based on prosilver. Our style.cfg would contain the following lines (the other lines have been omitted for clarity):

name = My Awesome Style
parent = prosilver

Instead of using prosilver as a "base" (parent), we could also use another popular style (which in turn inherits from prosilver). Our style.cfg would read as:

name = My Awesome Style
parent = prosilver Special Edition

After installing your new style, the style tree in your ACP would look like this:

prosilver
    prosilver Special Edition
        My Awesome Style

Mandatory Elements

The code of any website needs certain elements for it to work properly. These are defined in the HTML and CSS specifications (for more information on writing valid code, see the Code Validation section).

Besides these elements, phpBB 3.2.x/3.1.x requires styles to include certain specific pieces of code for the style to function properly.

If you are using a valid 3.2.x/3.1.x style as a base for your new style, these elements will be included already, but since they are very important, we will dedicate this section to a more detailed explenation.

Note: For more information on how these code snippets are used by styles and extensions, visit the Development Wiki page on New Template Commands in 3.1.

{$STYLESHEETS}

The phpBB 3.2.x/3.1.x extension system lets extensions add custom (external) CSS files to your page output. They do this by using the <!-- INCLUDECSS my_styling.css --> template commands.

What this command does is add the specified files to the queue of files that will be loaded in the {$STYLESHEETS} template location. So if you don't include this variable in your template, many extensions will break (since their front-end styling relies on these files).

Note: {$STYLESHEETS} should be present near the end of the <head> element in the overall_header.html template. Ideally right before the </head> tag.

{$SCRIPTS}

The {$SCRIPTS} template variable works in much the same way as {$STYLESHEETS}, but is meant for JavaScript files to be included. Extension authors use this by using the <!-- INCLUDEJS my_scripts.js --> template command. As with the stylesheets, the {$SCRIPTS} variable is necessary for your style (and extensions) to function properly.

Note: {$SCRIPTS} should be present near the end of the overall_footer.html template. Ideally right before the </body> tag.

jQuery

Since version 3.1, jQuery is included by default in the download package. Besides the fact that jQuery can be very handy for style authors, many extensions will utilize it too and depend on it being active.

Therefore you should always include the instructions that load jQuery into your template. You can do this by making sure that the following code is present in your overall_footer.html template.

<script src="{T_JQUERY_LINK}"></script>
<!-- IF S_ALLOW_CDN --><script>window.jQuery || document.write(unescape('%3Cscript src="{T_ASSETS_PATH}/javascript/jquery.min.js?assets_version={T_ASSETS_VERSION}" type="text/javascript"%3E%3C/script%3E'));</script><!-- ENDIF -->
Note: This jQuery code snippet should ideally be the first script that is loaded in the footer. In any case, it must be included before {$SCRIPTS}.

Template Syntax & Variables

phpBB 3.2.x/3.1.x has a powerful template-engine, which lets you add/modify various pieces of code for page-output.

For more information on how to use the various template tags and conditionals, we advise you to take a look at our Development Wiki. At this time, there are no dedicated entries yet specifically for 3.2.x/3.1.x Styles, but a few important pages are still applicable:


Pro-Tip: Since version 3.1, phpBB uses Twig as the base of it's template engine. You can use Twig syntax for your style, which can have numerous advantages. For more information, read the Using Twig in phpBB section.

Template Events

With the introduction of the extension system in phpBB 3.1.x, extensions are able to insert code without editing template files. This greatly simplifies the installation, updating, and removal processes of functionality for styles.

Many extensions will use these template events in order to add functionality to phpBB. They do this by using <!-- EVENT template_event_name --> template commands. If you want your style to become popular, you should definitely try to include as much of the "default" template events as possible.

Since prosilver is still the default style for phpBB 3.2.x/3.1.x, most extensions will be primarily developed for prosilver (and therefore use prosilver's template events). Including these events (in roughly the same location as prosilver) will ensure that future extensions will work with your style.

Note: A comprehensive list of all template events currently available in prosilver can be found on the Development Wiki Event List page.
Pro-Tip: Instead of trying to insert all these template events into the correct places in the templates of your style, you can use template inheritance.

Template Inheritance

Template inheritance is arguably the most useful thing about phpBB's template-engine for style authors.

If you base a new style on an existing one, but you only want to change a few templates, you don't have to copy them all. This would create a lot of identical copies of files on your server, and things would get cluttered pretty soon. It would also become very tedious to merge all the changes to the templates, if the "parent" style were to receive an update.

Enter template inheritance, requiring nothing more than a single line in your style.cfg.

By specifying a "parent" in your style.cfg, the template-engine knows how to fall back to files of a different template-set if there is anything missing in the current one. The nice thing about this is that the process is completely transparent after template compilation and comes at practically no extra costs during runtime.

Basically this means that phpBB will try to find a file in your new style's template/ directory, but if it cannot find it, it will look for the file in each of the parents' template/ directories. This process can go multiple levels deep. So you can base your own child style on a child of a child of a child of a parent, like the branches of a tree (hence the "styles tree").

Note: With the introduction of template events, template inheritance has become much more powerful. We advise you to use it whenever possible.

Example

Many styles start off by modifying existing styles (such as prosilver), because creating a completely new style from scratch is an extremely time consuming undertaking. The following example will show how easy (and useful it is).

Case: "I want to modify the header and index page of style X, how do I do it?"

Well the first thing to remember is that you only want to change these 2 parts now. You will likely want to change more and more parts as time progresses. So the best course of action would be to create a "child" style of style X (we'll called it style Y).

  1. Create the file structure (skeleton) for style Y.
  2. Create a style.cfg for style Y which specifies X as it's "parent".
  3. Copy overall_header.html and index_body.html from styles/x/template/ to styles/y/template/.
  4. Edit the files to suit your needs.
  5. Upload and install style Y in your ACP.

Is that all? Not quite. You will notice that no theme assets (CSS and images) have been loaded. We will address this issue in the asset inheritance section.


Asset "Inheritance"

The biggest obstacle for most style authors is the fact that the inheritance tree only works for templates, not CSS. So how do we use template inheritance, but also "inherit" the theme assets of the "parent"?

There are multiple ways of doing this, and it will depend on whether or not you plan to make really significant changes to the CSS files. We'll try to explain the different ways of "inheriting" theme assets from other styles, and their pros and cons.

Note: Theme assets cannot be "inherited" the same sense as templates can. There is no automated system at work here. Asset inheritance should be read as meaning: "loading theme assets from a different style, via manual instructions".

Method 1. Copy-paste all theme assets

The easiest (and probably most (ab)used method) has been to simply copy-paste all the assets (the entire theme/ directory) of the "parent" style to the "child" style's theme/ directory, and edit the various CSS files to suit your needs.

While this is the easiest method, it is strongly discouraged to use it, especially if you plan on releasing your style publicly, for the following reasons:

Pros

  • Easy editing
  • Doesn't require any template modifications

Cons

  • Poor maintainability
  • Potential merge problems when updating parent styles
  • Duplication of assets

Method 2. Relative-path @import with selective replacement

If you only want to make changes to a few of the parent's CSS files, you might not want to duplicate all the assets, since that would just clutter your new style. It is possible to only copy a few assets and make changes to them, without having identical copies scattered around the server. In your new style's stylesheet.css, you could include the following code:

@import url("../../prosilver/theme/common.css");
@import url("../../prosilver/theme/links.css");
@import url("../../prosilver/theme/content.css");
@import url("../../prosilver/theme/buttons.css");
@import url("../../prosilver/theme/cp.css");
@import url("../../prosilver/theme/forms.css");
@import url("colours.css");

This would basically load all the parent's (prosilver) CSS assets, except for colours.css, which you want to load from your new style's theme assets (which you have copied from prosilver, and subsequently edited to suit your needs).

Pros

  • Deduplication of assets
  • Doesn't require any template modifications

Cons

  • Relative path @import rules are a potential security risk! (avoid if possible)
  • Still requires a copy of all assets that aren't included in stylesheet.css (responsive.css, /en/stylesheet.css, etc.)

Method 3. Multiple overriding stylesheets.css in <head>

Instead of copying assets and editing them, you could also write new rules in the overall_header.html template of your new style that override the parent style's CSS rules.

<link href="{ROOT_PATH}styles/prosilver/theme/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">

<link href="{T_STYLESHEET_LINK}" rel="stylesheet">
Note: We use {T_ASSETS_VERSION} as rudimentary form of browser cache control.
Note: Although {T_SUPER_TEMPLATE_NAME} is still supported, it only traverses the styles tree 1 level. So it isn't suitable for use in complex inheritance situations.

What this does is load prosilver's stylesheet.css first (and load all the subsequent components via the @import method as specified in that file). After that, it will load the stylesheet.css of your custom style. You can use @import rules in your own stylesheet.css file as well of course (if you want to split up your code into multiple files), or you could simply put all your CSS rules in the stylesheet.css file itself.

Note: Using both @import rules and regular CSS rules in the same file is not advised.

This same method can be applied to load other CSS assets directly from the parent (without having to duplicate them), such as responsive.css, print.css, bidi.css, etc. If you wish to use the parent style's language assets, you could use the following snippet:

<link href="{ROOT_PATH}styles/prosilver/theme/{T_THEME_LANG_NAME}/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">

Pros

  • No relative-path @import rules
  • Possible to deduplicate everything

Cons

  • No detailed control over which parts of the parent's stylesheet.css to include/exclude.

Method 4. Detailed overriding link components in <head>

This method works the same way as Method 3, but instead of including the parent's (prosilver) stylesheet.css, we load the various CSS assets directly (without relying on @import) from the overall_header.html template of your new style. This allows for greater control of which files to include/exclude.

From a technical perspective, this is the best method to use.

<link href="{ROOT_PATH}styles/prosilver/theme/common.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
<link href="{ROOT_PATH}styles/prosilver/theme/links.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
<link href="{ROOT_PATH}styles/prosilver/theme/content.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
<link href="{ROOT_PATH}styles/prosilver/theme/buttons.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
<link href="{ROOT_PATH}styles/prosilver/theme/cp.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
<link href="{ROOT_PATH}styles/prosilver/theme/forms.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">

<link href="{T_STYLESHEET_LINK}" rel="stylesheet">

<link href="{ROOT_PATH}styles/prosilver/theme/{T_THEME_LANG_NAME}/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">

Notice that we didn't include colours.css, since we want to use our own custom rules (which we will specify inside our own stylesheet.css) instead of prosilver's.

Pros

  • Complete control over which assets to load (and in which order)
  • No use of CSS @import at all (this is preferable)
  • Possible to deduplicate everything

Cons

  • More complex header template

Which method should I use?

It depends on how big the changes are that you are planning to make. From a technical and maintainability standpoint, we would suggest Method 3 in case of relatively minor asset changes, and Method 4 for more extensive modifications.

Pro-Tip: If you wish to reduce the load of CSS data-transfer, you could compress and minify the various CSS files that your style uses into a single file, and serve that instead. But this is not easy to do well, and requires a more complex work-flow (which is beyond the scope of this guide).

Styling Extensions

This is completely optional, but if you feel that the users of your style will likely want to use particular (popular) extensions, you might want to add support for these extensions to your style.

This is particularly useful if your style has an unconventional layout, or has significantly modified CSS/image assets, which can cause extensions that use their own styling to look ugly or out of place.

Many extensions with front-end functionality will include their own stylesheet using <!-- INCLUDECSS my_extension.css --> which will add the referenced file to {$STYLESHEETS} in your <head> (as described here).

Since in many proper styles {$STYLESHEETS} is included after <link href="{T_STYLESHEET_LINK}">, this means that the extension's CSS rules will overrule your style's rules (as intended).

You will notice that this gives us a problem. We can't include any specific rules for these extensions in our new style's stylesheet.css, since they will be overruled. We could overcome this by using stronger CSS selectors or adding !important to properties, but this is not a very elegant solution.

Instead, we could simply reverse the load order for our style's extension-specific rules. The easiest way to do this is to move all your style's rules that are specifically for extensions into a new .css file (/theme/extensions.css for instance).

Now we need to include it in the <head> of our template, but after {$STYLESHEETS}.

{$STYLESHEETS}

<link href="{T_THEME_PATH}/extensions.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">

Using this method will ensure that your custom rules are loaded after the extension's own rules, thereby overriding them.

Pro-Tip: If (and only if) you have a very popular style, but a certain extension uses template files that simply don't work well with your style, you could contact the extension's author. If he/she agrees, you could contribute a special template to the code of the extension (via a GitHub pull request or other method).

Using Twig in phpBB

Since version 3.1, phpBB uses Twig as the base of it's template engine. You can use Twig syntax for your style, which can have numerous advantages.

In order to guarantee backwards-compatibility, the old phpBB syntax is still supported (and widely used), but these are translated into the Twig syntax by the backend. So <-- IF FOO -->{BAR}<-- ENDIF --> becomes {% if FOO %}{{ BAR }}{% endif %} by being translated into the native Twig syntax.

Sensiolabs provides comprehensive documentation for the Twig template engine on their website. Especially the Twig for Template Designers section will be a useful resource for style authors, so we won't be covering the contents here. Instead, we will address some of specifics of the current Twig implementation in phpBB 3.2/3.1.

Available features

phpBB 3.2.x was shipped with Twig version 1.24.2. The current version of phpBB 3.1.x uses Twig version 1.24.1. Any features of Twig implemented thereafter are currently unavailable until Twig is updated in the phpBB package to a more recent version.

Language vars

phpBB has supported multiple languages for ages, and these are traditionally output to the template using {L_FOO}. If you wish to use native Twig syntax for this, you should use {{ lang('FOO') }} instead.

Template events

Like language vars, template events can also be used in native Twig syntax. The following event: <-- EVENT event_name --> equals {% EVENT event_name %}.

Including dynamic templates

Many templates in phpBB include other templates in order to keep the code organized. This usually isn't a problem, unless the template to be included is assigned dynamically (based on a phpBB configuration or user setting).

These templates are often included using the following syntax: <-- INCLUDE {FOO_TEMPLATE_FILE} -->. Twig uses virtually the same construct (although you can choose to use the include function or tag). Using the tag syntax, the resulting code would be {% include FOO_TEMPLATE_FILE %}.

If you wish to edit the path of the included file (perhaps using a .twig extension or a different file path), you can alter the include rule without having to rewrite the template variable output by the back-end. This can be done by constructing an array and imploding (joining) it immediately.
Example: {% include ['includes/', FOO_TEMPLATE_FILE, '.twig']|join %}

Loops

Due to backwards-compatibility considerations, phpBB 3.1 implements template loops in a somewhat unconventional way. Because of the way block-vars are assigned to the template by the assign_block_vars() function (they are stored under the "loops" context), they are not available in the "root" context. Take this simple example of a template loop:

<-- BEGIN my_items -->
	{my_items.VALUE}
<-- END my_items -->

Using Twig, the following code should work.

{% for item in loops.my_items %}
	{{ item.VALUE }}
{% endfor %}
Note: The current loops implementation is temporary, undocumented, and subject to change. But you can use it if you feel comfortable with Twig.

Tips & Tricks

Mimic prosilver CSS classes

Since most extensions will be developed primarily for prosilver, they will naturally utilize prosilver's style assets whenever possible. This helps extension authors to significantly reduce the amount of CSS rules that they need to write.

If an extension author wants to add a block of rows with content, they could write all the CSS rules themselves, or they could simply rely on the rules already in place. The likely result is that they will recycle prosilver's style rules, with selectors like ul.topiclist.

If you want extensions to work on your custom style with the least amount of effort. Using the same CSS class-names on roughly the same elements can help a lot.

Use automatic template recompiling (during development)

While making changes to template files, it's often handy to be able to see the changes directly, without having to purge your forum cache every time. A neat little trick is to recompile templates automatically after every file change.

Browse to: ACP > General > Server configuration > Load settings and set:
"Recompile stale style components": Yes

Use file comparison tools

Users often forget the changes that they have made to certain styles. Or they have a hard time seeing the differences between different versions of files.

This is where file comparison tools come in handy. Some of the more advanced text-editors have built-in features that help when comparing files (or entire folders). Alternatively, you could use stand-alone applications for this. A few popular free ones are WinMerge and Meld.

Code Validation

Writing valid HTML and CSS code will greatly increase your chances of having your style working correctly in different browsers on different operating systems and devices.

Valid HTML and CSS code is also required if you hope to submit your style to the Styles Database, as mentioned in the Style Submission Policy.

Luckily, there are automated tools available that will help you in identifying problems. We suggest using Unicorn - W3C's Unified Validator.


We hope you found this guide informative and helpful. There are still many more resources to help you develop great styles that will expand the possibilities of what phpBB can do for your community and the many more communities that may adopt and benefit from your styles.

Styles Database
Styles Support
[3.2.x] Styles in Development Forum
[3.1.x] Styles in Development Forum
Wiki: Template Engine Changes in 3.1

If you have any suggestions or remarks relating to this guide, feel free to contact the Style Customisations Team.