New service: making a custom style from your style changes

In this post I detailed how you can create a custom style that encapsulates the changes you made to your style to give your bulletin board a unique look and feel.

I now offer this as a service. See my pricing summary for my current rates, which at this time are $30 noncommercial and $60 commercial.

What I will do is analyze all the changes you made to your style by comparing your changes with a referenced version of the style that you modified. Once I have done that I will create the custom style with all these changes, inheriting from the original style. And I will replace the style that you marked up with the original style. Your custom style will inherit from it.

This has some advantages:

  • When updating phpBB, your custom changes are insulated. You no longer have to reapply these changes, or be scared to update phpBB or your primary style, at least if you follow phpBB’s update procedures.
  • You can make tweaks to your custom style in one place. Stylesheet commands are all placed in the stylesheet.css file of the custom style.

If you have made changes to templates, you may want to update these in your custom style from time to time. New template events are added to templates occasionally with new releases of phpBB or your primary style. I can do this for you as a service too at my general hourly labor rate.

Using unapproved extensions is dangerous

As more phpBB extensions are developed, they are becoming more popular. Extensions add functionality to phpBB beyond what is available by default. Based on my work with clients, most have extensions installed, so I factor them in when updating or upgrading their forums. They often need to be upgraded as well when a forum is upgraded or updated.

The phpBB Group maintains a database of approved extensions. Both the phpBB Group and me recommend that if you install an extension that you only install extensions downloaded from this database. This is because approved extensions are quality checked by the phpBB Extensions Review Team. The team thoroughly inspects the extension and ensures they adhere to all coding standards as well as use best practices to minimize security issues. An extension typically goes through a number of reviews before it is accepted, if it is accepted. So you can have confidence that if you download an official extension it is of high quality and secure.

If you are not familiar with how to install extensions, the instructions are on the Manage extensions page: ACP > Customise > Manage extensions.

Unapproved extensions fall into two categories:

  • Extensions in development
  • Third-party extensions

Extensions in development

Extensions don’t appear out of nowhere. Like all software, they go through a development process. You can see a list of extensions in development on that forum. The topic title is prefixed by the state of the extension in brackets. Links to the extension for downloading are in the first post. If you have feedback on the extension, you leave it as a post on the topic.

The phpBB group has extension authors self-certify the quality of the extension they are creating. This is similar to other software. The levels from most risky to least risky are:

  • [DEV] – Development – the extension is very recent and is being issued for feedback and to refine features. It should only be used on a test board.
  • [ALPHA] – Alpha – The extension is no longer in development. The feature set is largely set and the code quality has been refined. Traditionally an alpha release has meant that it is to be used “within an organization”. Alpha release testers are expected to provide feedback and significant bugs and security issues may be experienced. “Within the organization” has no meaning with phpBB so it simply indicates it’s out of the principle early development phase. Using it on a live, production board is quite risky and definitely not recommended. A download link is usually provided.
  • [BETA] – Beta – The extension is designed to be used and tested by a larger group of people. There may be significant bugs and security issues. It should not be used on a production forum, but the code quality should be pretty high at this point and most bugs should have been addressed. A download link is required.
  • [RC] – Release candidate – Most of the bugs have been found and fixed. The release candidate could be submitted for formal review for inclusion as an extension if no more issues are discovered as a result of testing. The extension should be stable with no more features anticipated. Using it on a production forum is not recommended, but if you choose to do so anyhow it is likely to work as intended and not show any problems. Release candidates are submitted to the phpBB Group extension review team at the author’s discretion.
  • [CDB] – Customise database. You will see this in the Extensions in development forum. It means that the extension is approved. There should be a link to take you to its official page on phpbb.com. The topic is locked.
  • [ABD] – Abandoned. The extension author abandoned work on the extension. It is not approved, should not be used but some other extension author could take up working on the extension. These are placed in their own abandoned extensions forum.

There may be multiple versions of the extension in each phase. Generally extensions in development start with 0.1 and as an extension reaches Alpha or Beta stage it becomes 1.0. But there is no fixed standard for version numbers other than the PHP Composer guidelines. The extension is usually suffixed by the build quality, ex: 0.1.0-dev. The extension is usually downloaded from GitHub.

Third-party extensions

Third-party extensions are usually developed by commercial companies and typically tie into existing products outside of phpBB. Companies can submit their extensions for review by the phpBB group but usually don’t. This is because a review is time consuming. It can take months to get a review, then multiple issues must be fixed, and the extension resubmitted. This is not agile enough for many companies. In addition, the phpBB Group frowns on software that does not use an open source license. Many third-party extensions are issued with open source licenses but tie into products or services that are not.

When you use one of these extensions, you are assuming significant risk. Obviously, these companies don’t want their reputation besmirched, so generally they will take the time to write a quality extension and possibly adhere to the coding standards for extensions. But since in most cases they aren’t approved extensions, they are risky because they were not reviewed by the phpBB group to ensure their quality. They are typically downloaded from the company’s website or from their GitHub page.

Tapatalk

Tapatalk is a smartphone app that allows you to use the same user interface to access multiple forums, phpBB or otherwise. Prior to phpBB 3.1 the Tapatalk modification was widely used because styles for phpBB were not responsive, i.e. did not resize intelligently for mobile devices. Since phpBB 3.1, approved styles must be responsive, so users can use a browser on their smartphone to access the forum without the hassle of the past. Still, many people like the convenience of using one app to access multiple forums, so Tapatalk developed an extension. It creates an interface between phpBB and the Tapatalk app.

This extension is not approved and likely would never be approved by the phpBB Group. Why? When you install the extension, although an interface is seen in the /ext folder as usual, there is also a /mobiquo folder installed in your forum’s root directory. The software in the /mobiquo folder does most of the work of communicating between phpBB and the Tapatalk app. Tapatalk is available for other forum solutions too, and they use a similar architecture. The /mobiquo folder does all the data munging, so it is unique and proprietary. phpBB’s extension architecture requires that all extensions work within the /ext folder. Since Tapatalk doesn’t do this and its data munging is proprietary, it’s unlikely to ever be approved. It’s clear that Tapatalk developers don’t want to try.

More importantly, Tapatalk injects a major vulnerability in that it can bypass phpBB’s functions that do important work like posting to the database. This makes it dangerous. You should encourage your users to use a mobile browser instead of Tapatalk to access your forum. Ideally, you should disable and uninstall the extension.

Cleantalk

Cleantalk is an antispam service. Cleantalk’s extension for phpBB is approved, but it’s very old (2016 as of this writing). It may be that a newer version of the extension has been submitted for review, but the version on phpBB.com probably won’t work on phpBB 3.2. If it does, it’s missing many features. So as a practical matter, if you use Cleantalk you will want to get its most recent published version off of GitHub. Just bear in mind it’s a version that has not been approved by the phpBB Group, so using it may be risky.

Proprietary style user interfaces

Many proprietary (paid) phpBB styles come with a user interface that makes it easier to customize the style, doing things like changing background colors easily, swapping in different logos, changing fonts, etc. Because these styles are proprietary, they are not free and thus not allowed on the list of approved styles for phpBB. Consequently, extensions bundled with their styles are not approved as well. Using a proprietary style incurs some risk by itself. Using an extension used to manage the style adds additional risk.

End phpBB update styling rework with a custom style

Updated October 20, 2019.

Has this happened to you? You update phpBB to the latest version and find out that your custom logo or various style changes that you tediously made to phpBB are gone, or partially gone. It’s a common problem and one reason many forum owners defer updating phpBB.

You can end this hassle by creating and installing your own custom style. Using this approach your custom style inherits most of its styling from a primary phpBB style. You then selectively override the primary style’s CSS, HTML or Javascript with your own changes. This way when the primary style you use is changed, you don’t lose your custom changes. This also ensures that your styles and templates use the most current and approved code, which often includes security patches.

In this tutorial I will show how you can do this. I will keep my example simple by using my custom style to swap out the default phpBB logo with my own logo, sized to the new logo’s dimensions. In principle though you can go way beyond this simple use. For example, your custom style can overwrite the inherited style’s colors, padding and margins, or container widths and heights. You can also overwrite HTML and Javascript files.

Note: I now offer this as a service. See my pricing summary for my current rates.

Overview of steps required

The basic approach is:

  1. Make a note of all the changes you made to your style
  2. Reload your preferred style
  3. Create a custom style that inherits from your preferred style
  4. Override the preferred style’s stylesheet directives. This is best done by creating a stylesheet.css file for your custom style and placing your style customizations there.
  5. If you changed some templates, place the custom version of these templates in your custom style’s template directory. Frequently, forum owners will make changes to overall_header.html and overall_footer.html.
  6. Install the custom style
  7. Make the custom style the primary style
  8. Test and refine

Let’s delve into each step to see how this is done.

Make a note of all the changes you made to your style

You probably know what these changes are, but if you have any questions you can use a file comparison tool like WinMerge (for Windows) or kdiff3 (for pretty much any operating system) to compare your files with a reference version.

  1. Download your current style folder where you made all your custom changes, such as /styles/prosilver
  2. Download a reference version of your style for your current release of phpBB. phpBB keeps a list of its releases here. If your styles are based on prosilver then you would use the reference /styles/prosilver folder for your current release of phpBB. (You can see what version of phpBB you are using when you go into the Administration Control Panel. Look for Board version.) If using a non-prosilver style, find the style version you are using. You can see the version by selecting the Details link for the style in ACP > Customise > Style management > Styles. You can also find it by reading the style.cfg file in the root folder of the style. If it’s one of the free styles, you can find it on the styles demo page. Find the style, then click on the Details button. On the Revisions tab, click on the link for the version for your style to download that version. If a proprietary style, if you don’t have it already, you may have to download it from the style author’s website.
  3. Run the file comparison tool and note the changes you made so they can be reapplied in the custom style.

Reload your preferred style

  1. Make certain you have documented all the changes you made to your style. Once they are overwritten, you may not be able to recover them.
  2. If you need to update phpBB, you might want to do this first. Bear in mind if you do this, the default prosilver style will be updated
  3. You might also want to load the latest version of the style you are using, which will become the parent style. Otherwise, since you made changes to your preferred style, it’s a good time to undo them. The simplest way is to upload the reference version of your style, replacing anything that’s there. Purge the cache. If you don’t see the style changes afterward, clear your browser’s cache and reload the page.

Create a custom style that inherits from your preferred style

  1. First review phpBB’s Creating & Modifying Styles page.
  2. Create a folder in the styles folder for the name of your style. In this example I keep it simple and call the folder “custom”, i.e. /styles/custom. Keep the folder name simple. Don’t use any spaces in the folder name. It’s easier if you keep the name all in lowercase.
  3. Create a style.cfg file in this folder. Copy the style.cfg contents from your parent style’s style.cfg file. Below is the code in /styles/prosilver/style.cfg for phpBB 3.2, which I used because my “custom” style inherits from prosilver.
#
# 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
  1. In my example I changed “name = prosilver” to “name = custom”. Since I want to inherit from prosilver I left the “parent = prosilver” line unchanged. If you are changing a style other than prosilver as the primary style, you need to change the parent style to the correct style name. It must match the parent folder name in the styles folder. You might also want to edit the copyright, style_version and phpbb_version lines. If it’s only for your own use, this is not necessary. Here are my changes:
# General Information about this style
name = custom
copyright = © Mark D. Hamill
style_version = 1.0.0
phpbb_version = 3.2.2

# 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
  1. Save the file, making sure it is in the root folder for the custom style, e.g.: /styles/custom/style.cfg.

Override the preferred style’s stylesheet directives

  1. Create a theme folder for your style. In my example, this would be /styles/custom/theme.
  2. Create an images folder inside the theme folder. In my example, this would be /styles/custom/theme/images.
  3. If changing the logo, upload the logo you will use to /styles/custom/theme/images. Make a note of the image’s height and width as you will need this later.
  4. Create a file called stylesheet.css in the theme folder.
  5. To inherit styles from your parent style, you need an @import statement at the top of this file. For example, if prosilver is the preferred style, this line would be at the top of the file. Generally you just need to reference the stylesheet.css file in the parent style. You will have to amend the path so it finds the parent style’s stylesheet files. In my case for the @import line, I added “../../prosilver/theme/”. The ?v=3.2 indicates the version of phpBB expected, so it may have to be changed.
@import url("../../prosilver/theme/stylesheet.css?v=3.2");
  1. Any style changes that you want to override should now be appended to the end of this file. In the example of replacing the logo, in the prosilver style you would normally edit the .site_logo class in colours.css and common.css. In my case I added these lines at the end of my /styles/custom/theme/stylesheet.css file, which provides the correct image to use for the logo and its proper dimensions:
.site_logo {
    background-image: url("./images/mark.jpg");
    width: 181px;
    height: 229px;
}
  1. I then saved the file stylesheet.css with my changes.

Changing templates

In my example, since I am only replacing the logo, no template changes were needed. The only viable approach is to copy the template, for example, /styles/prosilver/template/overall_header.html to /styles/custom/template/overall_header.html. Then make the changes that you need to make and save the file. This has a downside: if there are changes made to the parent’s template with an update, your version won’t have them unless you manually inspect for any changes and apply them to your custom version.

Install the custom style

  1. ACP > Customise > Style management > Install Styles
  2. Select the new style you created (“custom” in my example) by pressing the corresponding Install style link.

Make the custom style the primary style

ACP > General > Board configuration > Board settings. Generally you set the default style to your new custom style, the guest style to your new custom style and you may optionally want to set the override user style option to Yes. Submit the form.

Test and refine

You should not need to purge the cache if you make any stylesheet changes. However, if you make subsequent changes to any templates first purge the cache then test. If you don’t see the style changes, try deleting your browser’s cache, then reload the page. On desktop and laptop computers, sometimes holding the SHIFT key down while pressing the RELOAD button will work.

Approach when upgrading

This approach is unlikely to work correctly when upgrading. An upgrade is when you go from one minor release of phpBB to another, such as from 3.2 to 3.3. You can of course go through the process of creating a new custom style again. As for updates, this should work.

Enjoy!

Compiling and tweaking styles in phpBB

Many fancier phpBB styles are now written to be “compiled”. This means that if you need to make changes to a stylesheet, you actually need to find the right .sccs stylesheet and edit that instead of the traditional approach of editing a .css file. If your style uses this approach, you will find these .sccs files in the theme folder of your style.

Unfortunately, after editing these files no changes are automatically affected on your website. You must “compile” these .sccs files into a stylesheet that the browser will recognize, i.e. with a .css suffix. In the phpBB world this generally means compiling all these .sccs files into one file, stylesheet.css. Once that file is rewritten the changes will be applied by the browser.

Using Chrome's developer tools to inspect the CSS for a page object
Using Chrome’s developer tools to inspect the CSS for a page object

How do you know what .sccs file to edit? It’s hard to know when a stylesheet is compiled since all the styling is in stylesheet.css. It helps to “snoop around”. There’s a simple way to do this: use the Inspector built into all the browsers. While the look varies a bit from browser to browser, you just right mouse click and find the Inspect option. You can save some time if you have your mouse pointer focused on the area you want to inspect first then doing the right mouse click.

In the example shown, I used the Inspector built into the browser to look at the <div> object containing the search box. This gives a clue to how I might change the background color of the search box. In this example I used the default prosilver style, which does not use .sccs files. However, it does say that I need to change the .search_header style to change its background color. In this case I know it’s in colours.css, but in a theme using .sccs files you’d have to hunt for the file containing the style. It’s often not too hard based on what you are looking at, its intended purpose and the .sccs file names.

The nice thing about both these tools is that you can test changes in the tool on the styles tab of the tool. Once you have it looking right, you can apply the change to the appropriate .sccs file.

How do you compile these .sccs files? If running phpBB 3.1 or 3.2, there’s a little known extension that allows you to do it. (It is little known because it is not considered an official phpBB extension, so you have to get it off the Artodia website instead.) Install it as you would any other extension then find it on the customise tab in the ACP under “Compile Themes”. Once compiled, go test it. There should be no reason to purge the cache, but if you don’t see the changes you may need to clear your browser’s cache.

If you have a phpBB 3.0 style that uses .sccs styles, look for documentation with the style on how to compile it.

Many of these styles have a control file used to easily change colors, fonts, common object widths and heights, etc. It is probably called _style_config.sccs.

If curious, SCCS means “Sassy CSS” files which are described in more detail on the SASS website.