Installing & Using Styles

Styles are downloadable packages which can be installed on a phpBB board to change the look and feel of the board. In this guide, we will walk you through the process of installing and using styles on your phpBB board. For a quick introduction into styles, please visit our User Guide.


Anatomy of a Style

Inside your phpBB board's directory is a styles/ folder. This is the location where all styles are stored, and where we will be uploading any future styles as well. Every style follows the same folder structure.

phpBB 3.2.x and 3.3.x styles have three main parts: templates, theme assets, and a config file.

Templates
Templates are the HTML files responsible for the layout of the style. All template and JavaScript files (which can provide additional functionality) for a particular style are located in:

phpBB/styles/my_style_name/template/

Theme assets
Theme assets are a combination of colour schemes and images that define the basic look of your forum. This generally includes CSS files (of which stylesheet.css is the most important) and any other audio-visual assets. These files are located in:

phpBB/styles/my_style_name/theme/

Config file
A config file (style.cfg) contains the meta-information about a style, as well as machine-instructions for your phpBB board. This file is required, or else your phpBB board will not recognize the style. You can find it at:

phpBB/styles/my_style_name/style.cfg

Installing a Style

Note: This guide assumes that you have correctly set up phpBB 3.2.x or 3.3.x and have it operational. Direct write-access to your server's files (via FTP or other) is also required.

1. Choosing a Style

It is recommended to only download styles from phpBB's Customisation Database as this is a trusted source where all styles have been validated by the Style Customisations Team. All styles downloaded from the Customisation Database should be ready to be uploaded to your board's styles/ folder.

Additionally, you could try your luck with styles that haven't been validated yet (and therefor not included in the database). There are numerous styles availble in the [3.2.x] and [3.3.x] Styles in Development section of the community forums.

Note: Styles created for phpBB 3.3.x are not compatible with previous versions. Make absolutely sure that the style you downloaded is for the phpBB version you have installed.!

2. Download and unzip

Once you have downloaded a style, you will need to unpackage it on your computer, as styles are typically available in the compressed "zip" file format.

In Windows, to unzip the style, simply double click it from the Windows Explorer view (for instance, if you downloaded the style to My Documents, you would open My Documents and double click the file). Proceed to click "Extract all files" under the address bar (Windows Vista, 7 and 8) or under the Folder Tasks menu (Windows XP) from within the Explorer window and follow the prompts.

On Mac, zipped files are automatically unzipped upon download by Safari (this setting can be disabled by unticking "Open safe files" in Safari's preferences) and can be accessed through the downloads list.

Make sure that your style includes all the required parts as described in the Anatomy of a Style section (templates, theme assets, and style.cfg).

3. Upload to your board

To upload files, open your favourite FTP client (such as FileZilla, CuteFTP, SmartFTP, etc - even some internet web browsers have this capability) and log in to your hosting account. Generally your publicly accessible files will be in an area named "public_html", "www" or similar.

Upload your style files (the entire folder) to the styles/ directory inside your phpBB root directory. You can check if you have uploaded it correctly by looking at the location of the style.cfg file. It should be located at:

phpBB/styles/my_style_name/style.cfg

4. Install

Once the style has been uploaded, navigate in the board's ACP to Customise -> Install Styles. You should see your recently uploaded styles listed (assuming you uploaded it to the correct location and the style is valid), with an option to "Install style". Simply click it and the installation is complete!

Note: If your new style uses "template inheritance" (a method that style authors use to build styles "on top of" existing styles), make sure that you have the "parent" style installed first. phpBB will refuse to install a style if it cannot detect the parent.

Managing Styles

The Styles Tree (style inheritance)

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. Template inheritance has been part of phpBB 3 for a while now, and you will likely encounter it.

You can easily see the hierarchy (parent/child relations) of your installed styles by looking at the "Style Management" page in your ACP. It might look like this:

prosilver
    prosilver Special Edition
        prosilver SE Red Edition
        prosilver SE Gold Edition
newstyle pro
    newstyle ultra
        newstyle ultra-black
    newstyle mono

While it is theoretically possible to edit the inheritance hierarchy, this will most likely create all kinds of problems. Most styles will detect automatically which other style they should use as "parent". So it's best to leave it alone.

Default Style Settings

In general, users of your board will be able to switch between different styles (via the UCP) to suit their preference. There are a few methods however, which can give board admins greater control over the use of styles by their users. These settings can be changed by navigating in the board's ACP to General -> Board Configuration -> Board settings.

  • Default style: the selected style will be the default style for registered users (until they choose to change their board preferences in the UCP).
  • Guest style: the selected style will be the default style for unregistered visitors (guests).
  • Override user style: this option will force all users (and guests) to use the default style, regardless of what their personal settings are.


Editing Styles

Note: Editing a style is no trivial matter. Unless you have at least some knowledge of HTML and CSS and know what you are doing, we advise against the editing of styles.
Note: Always check to see if there are extensions available which provide the changes you need. Editing styles should be a last resort.

As mentioned in the Anatomy of a Style section, a style consists of multiple parts. Depending on what exactly you want to change, you will either have to edit the template or theme asset files.

Since it is usually not possible to edit files directly on your server, you will need to make all your edits on a "local" copy (on your own PC). It's generally good practice to have a local copy of your entire board, so you can test your changes before uploading them to a "live" board.

In any case: you will need to get a local copy of your style, either by downloading the style's files from your own board (via FTP), or edit the files from the style's download package (which you downloaded from the Styles Database).

Note: We will only cover a few basics here (for inexperienced users). For more detailed information, please visit the Creating & Modifying Styles page.
Pro-Tip: If you want to make many changes to your style, we suggest creating a "child" style based on your current style. Read the Creating & Modifying Styles page for more information.

Preparation

In order to edit web-files, you will need a text-editor. You can use any text-editor you want, but some are smarter than others. Notepad++ is a very good free text-editor, which has numerous options that can make your life easier when it comes to editing web-files.

Another "must-have" are the developer tools of your browser. If you have a modern browser (doesn't matter which vendor), you already have these tools. Simply pressing F12 on your keyboard (while browsing) will activate the developer tools in most browsers. These are absolutely essential if you want to edit and test your changes (and inspect the page in case something isn't working as expected).

Template Editing

Templates hold the greatest power when it comes to styles. You can basically add anything you want (as long as you have the skills). Covering all the different aspects of the template system would be beyond the scope of this guide. So instead, we will provide pointers to the most commonly edited files.

The list provided below refers to the files as they are in prosilver, but many styles adhere to the same general structure.

  • template/overall_header.html: arguably the most important template. Controls the "top" of every page, as well as the <head> element.
  • template/overall_footer.html: controls the "bottom" of every page.
  • template/navbar_header.html: controls the main navigation elements in the header.
  • template/navbar_footer.html: controls the main navigation elements in the footer.
  • template/index_body.html: controls the structure of the forum index page.
  • template/viewforum_body.html: controls the structure of the forum view.
  • template/viewtopic_body.html: controls the structure of the topic view..

For more information on how to use the various template tags and conditionals, we advise you to take a look at our Development Documentation. 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:


Note: 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".

Theme Editing

Themes are where the creativity comes into play. Editing the CSS files inside the theme/ directory can have a wide range of effects. Most users however, simply want to change a few colours, images, fonts, or text-size. This is where a good text-editor can really save time (since it will warn you about syntax and other errors).

Users often know what they would like to change, but they simply don't know which files to edit (and which lines in particular). This is where the (F12) develop tools are your best friend. The specifics for each browser might differ slightly, but this inspection guide for Google Chrome will tell you everything you need to know.

Once you have identified the CSS rules or classes which control the element you want to change, simply lookup the class name inside your style's .css files. Once you have made the changes you desire, upload your style's files.

Note: Old theme assets will sometimes remain in your browser's cache, which will prevent you from seeing the changes to your website. A "hard-refresh" usually solves this problem. This is usually done with the CTRL+F5 keyboard shortcut.

Updating a Style

Styles can be updated without any prior steps. All you need to do is simply upload the style's files to the same location as the old style, and let the files be overwritten.

Finally, simply navigate to your board's ACP index, and click the button at "Purge the cache".

Warning: If you have made changes to the style you are about to update, you will lose all your changes! So be sure to make a backup of your style's files before updating. After updating your style, you can reapply your changes.

Removing a Style

Sometimes it is necessary to remove a style. phpBB allows you to deactivate a style or to permanently uninstall it from your board.

1. Deactivate

Deactivating a style will effectively turn it off, hiding it from your board. However, all the style's files will remain on your server as well as entries in your database. So you can re-enable the style without your users losing their original style preference. To deactivate a style, simply click its "Deactivate" link in the Style Management page.

2. Uninstall

To uninstall a style, click the "Uninstall" link in the Style Management page. This will effectively remove the style from your board, as well as all database settings relating to it. You will get an option to also delete the actual files from your server.

Warning: Be careful when using the "Delete from filesystem" option! It is permanent and cannot be undone. You will have to upload the style's files again before you can use it again.

We hope you found this guide informative and helpful. Feel free to browse some of our other resources:

Styles Database
Styles Support
Creating & Modifying Styles
Styles Forum

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