Now that you have installed phpBB and gained some experience with the Administration Control Panel, you are ready to begin altering some more advanced aspects of the forum's appearance and features. Changing these areas of phpBB will be essential for giving your forum a unique identity that stands out among online forums. The appearance of a forum is mainly controlled by phpBB's styling system, which manages the colors, images, and visual layout of the forum. Features can be added, removed, or altered by installing modification scripts downloaded from phpBB-related websites.

By the end of this chapter, you will have learned about:

·       The basics of a phpBB 2.0 style

·       Correct methods of editing phpBB files

·       How to add and remove styles

·       Common style installation problems

·       Ways to customize a style

·       The benefits of creating and altering styles

·       Methods of changing forum images

·       How to add new forum features

phpBB Styles

If you look at several different phpBB forums, you may notice several differences in each forum. They may use different colors and images, display features in a different order, or omit some features entirely. This multitude of effects can be accomplished by using different phpBB styles. A phpBB style is the appearance of a forum, created by a combination of a layout, colors, and images. When you installed phpBB, the default style, called subSilver, was also installed. subSilver is the most commonly used style on phpBB forums, but there are well over two hundred different styles that have been publicly released. It is common for forums to have multiple styles available for user selection.

Structure of a Style

In order to effectively customize a style, you must first understand the parts that compose the design of that style. Styles, like houses, are built from smaller components that work together to create a frame. That frame, like the walls of the house, provides a structure for displaying the internal contents of a forum. These frames can be very complex creations so let us look at how the basic pieces are put together and stored, before we get into the actual customization of a style.

Style Elements

Styles are composed of three primary style elements, or smaller portions that work together to create the overall visual appearance of the style. These are the template, theme, and image set elements. Each style is self-contained and includes all the style elements needed to operate correctly.

The first and most important part of a style is the template element. The template element is a set of text files containing the entire markup that is used to generate the visual layout of a forum. The markup consists mainly of a markup language such as Hypertext Markup Language (HTML) and phpBB's own special template features, but can also include client-side scripting languages such as JavaScript. Template files are used to arrange most of the information displayed by your forum. You can identify template files by looking at the name of a file; all template files have names ending with tpl. Some examples are index_body.tpl, viewtopic_body.tpl, and message_body.tpl. Although this is rare, it is possible for multiple styles to use one set of template files with different themes and/or image sets.

The theme element of a forum style is a grouping of formatting rules used to define the visual decoration of a forum. The most common uses of the theme are specifying the font face, colors, background colors, and borders of page elements. Theme elements can be difficult to locate because they can be stored in three different locations. Most styles store theme data in one or more Cascading Style Sheet (CSS) files, such as subSilver.css and formIE.css. The name of the CSS files will vary with each forum style, but many times, there will be at least one CSS file named after the forum style. Some styles will place their CSS formatting rules in the overall_header.tpl template file instead of a separate CSS file. Others may use a combination of the overall_header.tpl technique
and database storage of some values. The subSilver style uses the combination method, but also includes a CSS file that can be used after a manual change.

An image set element includes all the images that are part of a style. Some examples are the folder images, voting result bar graphics, and language-specific buttons such as "Reply" and "New Topic." There are also images that may be used mainly for decorative purposes, such as background or header images. Decorative images are sometimes considered part of the theme, instead of the image set.

In addition to the template files already discussed, the template element can also contain two special configuration files related to the theme and image set elements. The theme configuration file, theme_info.cfg, is used for saving theme database data associated with a template. The saved data can then be imported into another forum's database later. For the most part, you will only rarely need to edit this file. It is usually automatically generated or provided as needed. The second configuration file holds template configuration data. In most cases, that will merely be a list of graphic files in the image set of a style. These template configuration files have a name based on their matching template, such as subSilver.cfg.

Style Storage

Details of all of the styles available on a forum are stored in the forum's SQL database. The database only holds a list of installed styles, the name of an associated template element for each style, and some limited theme data. No image set data is stored in
your database.

On the other hand, style elements are stored in the templates directory of the forum file system. The templates directory contains subdirectories that are named uniquely and after each individual set of template files. Each subdirectory of templates will contain template, theme, image set, and configuration files for one or more styles. Until new styles are installed or created, the only subdirectory in templates will be subSilver.

In most cases, a templates directory will contain two other subdirectories: admin and images. The admin subdirectory will contain template files used to display the Administration Control Panel. The images subdirectory will hold the image set used in the style, and may have language-named subdirectories, such as lang_english or lang_dutch, for images that display typed text in different languages. Some more advanced styles may include directories other than admin and images.

Editing phpBB Files

Throughout this chapter, you will be learning about and using a new skill that will be very useful to you as the administrator of a phpBB forum. You have already learned about some of the powerful configurations and features available through the Administration Control Panel, but there are many more that are not found there. These features can only be accessed (or in some cases, added) by editing phpBB's files yourself.
You must be careful to follow proper procedures when altering the files because phpBB is a delicate and complicated set of scripts. Doing so can save you a lot of headaches later, as many have learned first hand.

Before editing any file, the most important thing you should do is create a backup of that file. This simply means creating a copy of the file in its current condition. If you encounter problems due to your editing later, you can replace the edited file with the backup. That will effectively revert your forum to the pre-edited state of the file. At some point in your phpBB experience, you will definitely need to use a backup of a file. Everyone makes mistakes at some point, and it is nothing to be ashamed about. At other times, things simply do not work. Regardless of the cause, very few mistakes can be permanently fatal to a phpBB forum if you make backups before doing anything.

When you do edit a phpBB file, it is important to use the correct type of program. phpBB uses three types of files: graphics, text files containing program code, and text files containing display code. Graphics are standard image files you would see on any website and should be edited in programs such as Jasc Paint Shop Pro, Adobe Photoshop, or any other program capable of handling them. The text files, however, are special. Making a mistake in a graphic file will not damage your forum, but making one in a display code file or program code can easily cripple your forum.

All of phpBB's program code files contain the essential scripting needed to operate and display all aspects of a phpBB-powered forum and website. They are the backbone of phpBB. These files may have filename extensions of .php, .inc, or .cfg, and are plain text files created in a Unix text file format. This mainly means that when editing the files, you need to use a program capable of understanding the Unix text format. The majority of simple text-editing software will have no problems with this. Microsoft Notepad, perhaps the most commonly used text editor of the Microsoft Windows operating system, cannot understand the Unix format fully. It displays all the contents of a Unix text file on one long line, so Notepad is not the best choice for phpBB administrators. WordPad editor, also included with Microsoft Windows, is able to read Unix files without any problems. Most dedicated phpBB coders use more advanced text-editing programs with special features related to the PHP programming language. Some popular examples are EditPlus, TextPad, and PHPEdit, but there are many more available. You should, however, not need anything more complex than WordPad for the examples here.

The display code files are the .tpl files of the template element and the .css files of the theme element we learned about earlier. Like the program code files, these are plain text files saved in a Unix text file format. WordPad will again be our choice for editing these
files for the examples in this chapter. There are special HTML editing programs, such as Dreamweaver MX, that can be used to edit template files. Those programs tend to cause as many problems as they solve, so you may want to avoid them for now unless you are very familiar with the program you choose.

Finally, there is one more note about editing both program and display code files. When saving these files, you need to make certain to save them in the proper file format. These are supposed to be plain text files, so you must save them as that. To save an edited phpBB file in WordPad, just click the Save toolbar icon or select Save from the File menu. WordPad should automatically save the file correctly. If you must select Save As, make certain to choose Text Document in the Saves as type selection list.

Installing a New Style

One of the easiest ways to customize the appearance of your forum is to download and install a new phpBB style. Hundreds of different styles have been created based on topics like color schemes, popular movies, television shows, hobbies, sports, etc. The majority of these styles are free to download and use, although there are also some commercial styles and style designers available. Some websites that offer style downloads also provide demonstration forums in which you can preview any of the styles without downloading anything. Two of the best websites for downloading phpBB styles are:

·       The phpBB Styles Database:
http://www.phpbb.com/styles/.

·       The phpBBHacks Templates Database:
http://www.phpbbhacks.com/templates.php.
 

Be certain to select a style that is compatible with the version of phpBB that you are using. The two sites above will list the compatible phpBB versions for each style, but other sites may not. Also keep in mind that some other sites carry styles for special ported versions of phpBB that are used with content management systems like PHP-Nuke. Those styles will not be compatible with an original flavor phpBB forum and vice versa.

Once you have selected and downloaded a new style, you will need to install the style to your forum. The installation is not a hard process if everything is prepared properly.
You will however find it a bit daunting if the process or the creation of the style has been handled incorrectly.

Most downloads will come in a ZIP file format. Before you can install a downloaded style, you need to decompress the ZIP file. There are various software programs you can use to accomplish this task. If you downloaded phpBB in a ZIP file, you are most probably already familiar with decompressing a file. Even if you are not, there are many decompression software programs you can download. Some of the more famous names include WinZip, WinAce, and WinRAR. Some, like ZipGenius (http://www.zipgenius.it/) or XAce, are free. WinZip has a Wizard mode that is very easy to use, so we will not look at decompression in great detail here.

Creating a Copy Style

For the purposes of illustration, this chapter will discuss the usage of a sample style called subBook. Instead of downloading and uncompressing this style, it was created as a quickly renamed copy of the subSilver style. If you would like to create your own subBook style so you can follow along, follow these simple instructions.
 

Time For Action—Creating a Copy Style

1.      Make a copy of the templates/subSilver directory. The copy should contain all the same files found under subSilver.

2.      Change the name of the copy directory to subBook.

3.      Rename the subSilver.cfg and subSilver.css files to subBook.cfg and subBook.css, respectively.

4.      Open the theme_info.cfg file for editing. In this file, you will see subSilver used several times. Change each of these instances to subBook. Take care that you do not delete or change anything else in the file. Remember to follow the proper editing procedures you learned earlier.

5.      The name of the subSilver style is referenced in around forty to fifty lines inside template files in your subBook directory. The exact files and number of times vary depending on the version of phpBB 2.0 you are using. When creating a new style from subSilver as we are doing, you need to change all these references to the name of the new style (subBook in our case). Clearly, this step will take some time. This will not affect our installation or uninstallation examples, so you may skip most of this for now. Some advanced text editors have special search and replace features that can help you do this more quickly. At the very least, do these steps on the overall_header.tpl file.

6.      Save and close all open files.

What Just Happened?

Every style available for phpBB is based around a set of files stored in the templates directory. The easiest way to create a new style is to copy the files of another and make a few changes to some of the copied files. These files are the configuration files, such as subSilver.cfg and theme_info.cfg, which phpBB uses for installing and managing styles. The Cascading Style Sheet file, subSilver.css in this case, was also renamed. As a result, references to subSilver.css in overall_header.tpl also had to be changed to the new name of that file. Completing these steps gives you a new style, which you can edit as much as you like without affecting your forums' other styles.

Installing One Element at a Time

Once you have a new style to install, either from downloading or copying subSilver, you need to place that style's directories and files into the templates directory of your forum. phpBB's Administration Control Panel can automatically detect all styles placed into this directory. If your forum is on a remote server, as most forums and websites tend to be, then you will have to upload the directories and files to that server via one of the methods supported by your web hosting company. This is usually through File Transfer Protocol (FTP), SSH, or some other setup. Once you have copied or placed the files into templates, you have completed two thirds of the style installation already:

With the new style's files placed in your forum file system, you are now ready to install the style through phpBB's Administration Control Panel. Log in to your forum using an administrator account and enter the Control Panel. In the navigation menu frame, scroll down to the Styles Admin section. There are several options here; we are only interested in the Add link for the moment. Click this link to enter the Styles Administration page.

The Styles Administration page lists all the uninstalled styles phpBB has detected in your templates directory. You may notice that this page uses both theme and style to refer to the styles. This confusion stems from the fact that we have already installed the image set
and template style elements simply by placing them into the templates directory. All that remains is to install the theme element, and thereby complete the style's installation. To install a theme, just click the Install link next to the entry in the list. phpBB will now show the style in the drop-down selection list found in user profiles and the phpBB configuration page:

Troubleshooting

phpBB is a complicated set of scripts, so even something that should be simple, like installing a style, can cause you problems. There are many causes of these problems, ranging from designer mistakes to errors in the copying of the files, but all of them are easy to fix. Let us examine some of the more common troubles encountered by forum administrators in the past.

Style Does Not Appear in Administration

If a style does not appear in the Styles Administration page after you have copied it to the templates directory, there is usually a problem with the theme_info.cfg file that should be in the style's directory. Make sure this file has been copied and that the name of the file has not been changed. If the file is present and named correctly, then there is a problem inside the file itself. Some styles have been distributed with errors in this file.

Open theme_info.cfg for editing. It should resemble the subSilver file shown in the figure that follows. Note that each line begins with $subSilver[0], followed by other characters. The subSilver part is extremely important, and must be spelled in exactly the same manner as the name of the style's templates directory and cannot contain any spaces. The name will be different for each template, of course. phpBB will consider all of these to be completely different things:

·       subSilver

·       sub Silver

·       Subsilver

·       SubSilver

·       subsilver

This screenshot shows a portion of an unaltered subSilver theme_info.cfg. Only our first option, subSilver, would be correct in this instance. Check each line of theme_info.cfg and make any corrections needed to the file or, if necessary, rename the style's templates directory. In certain cases, the latter will be an easier method of correcting the problem. Other styles will have different names for their directory and in theme_info.cfg, but the name must be the same in both places.

Configuration File Cannot Be Opened

Sometimes phpBB may have trouble finding the configuration file for a template element. When this happens, either during installation or normal forum operations, the forum will present the user with a Critical Error message, as shown in the following figure, mentioning the name of the template. That name is a very important part of this error message, because it is telling you what name phpBB has used to look for the
configuration file. When the name of the template is shown as subSilver, phpBB could not find a file called subSilver.cfg in the templates/subSilver directory. Similarly, the name subBook means phpBB looked for subBook.cfg in the templates/subBook directory. The pattern here should be clear:

To repair this error, you need to ensure that phpBB can find the file in question. As with the error when the style does not appear in Styles Administration, the names of the actual file and directory must be exactly the same as that in the error message. Subbook is not the same as subBook. First, look in the templates directory and ensure that there is a subdirectory with the template name. Next, look inside that subdirectory for the template configuration file. If either the directory or file is named incorrectly, renaming them to the correct spelling should fix the error.

If there is no templates subdirectory that comes even close to having the correct name, there are two ways to fix the error temporarily. The first method is to rename another subdirectory (and the template configuration file inside it) to the name phpBB is trying to find. When doing this, be sure to write down the original name for a quick change-back later. The second and better method is to copy another template and rename it. The steps for this are the same as those in the Creating a Copy Style section earlier in this chapter, except you will not need to edit theme_info.cfg. With the problem repaired for the moment, you can try to uninstall the problem style or work out a more lasting solution like replacing the templates files of the style.

Removing an Installed Style

At some point, you may decide that you want to remove a style you have added to your phpBB forum. This is a much simpler process than installing styles. There are two steps to removing a style: deleting the style and theme information from the database and deleting the templates directory of the style.

In the Administration Control Panel, scroll the navigation menu down to the Styles Admin section. Clicking the Management link will load a Styles Administration page, listing the styles currently installed on your forum. It looks very similar to the installation page you have already seen. By clicking the Delete link next to a style, you will remove all information related to that style in your forum's SQL database. You will be asked to confirm the deletion before it actually happens. Any users that have selected a style in their profiles will automatically have their selection changed when that style is deleted. Their profile setting will be altered to the style selected as the Board Default on the General Configuration page of the Administration Control Panel.

The second aspect of removing a style calls for deleting that style's related subdirectory of the templates directory. This will typically be done through the same means by which you copied the style into templates when installing it. Since it is possible to have multiple styles that use a single template or image set element with different themes, you should make certain that removing these files will not damage any styles you have not deleted in the Administration Control Panel.

Create or Customize

So far, we have only looked at installing new styles that already exist. This is only one of the ways in which we can alter the appearance of a phpBB, however. Two of our other options are creating a completely new style or customizing one already installed, like subSilver. Both of these options have some benefits and some drawbacks.

Creating a new style can really bring life to a forum. If your forum has a look that is unlike any other, your visitors are more likely to remember it. You probably remember some of the unique-looking websites you have visited in the past yourself. Also, you do not have to spend time looking through hundreds of existing styles for something you like or one that will fit nicely with the subject matter of your forum. Sometimes you may not even be able to find a style appropriate to your subject! The temptation to create your own style is great.

On the other hand, creating a new style is a lot of work! There are many graphics required for normal phpBB operations, and you will probably want to replace most of them with your own. You may even want to create new graphics and alter the template files to create new visual effects. Essentially, you would be designing an entire website. If you are not an experienced web designer or graphic artist, you may find the task to be a bit beyond your current skill level.

 

This is an excerpt from chapter 3 "Customizing Your Forum". The full chapter can be read in the book Building Online Communities with phpBB.

 

For more information: www.PacktPub.com/book/phpbb