phpBB - Customizing Your Forum 5

Another major part of a forum's appearance is created using images. Forum images can be divided into two main categories: those that are just for looks, and those that serve some function. The former might include a forum's logo or menu link images, while examples of the latter would be new post indicators and posting buttons. By replacing any of these images, you can create a new user interface and adapt your forum's design at the same time. If you are a graphic artist or experienced in creating your own images, you can create some awesome images to liven up your forum.

can be used to create new images for their styles using Adobe Photoshop and other image editors. PSD packs for styles you install, if available, may be useful when adding new features to your forum later.

Installing New Images to Change the Look of Your Site

There are two ways to install new images to a phpBB forum. The first is to replace an existing image. Replacing an image entails finding or creating an image, renaming it with the same filename as an image already used on your forum, deleting the existing image, and putting the new image in the same location. This is a quick way of getting new graphics on your forum, but it will limit you to the same type of image previously in place. If you have a JPEG image, like a digital photo, that you want to use for a New Topic button in subSilver or subBook, you would have to convert it to a GIF image, losing some picture quality in the process. For cases like this, it's better to use the second method of installing new images: adding an image with a new filename.

In order to get phpBB to detect the new filename, however, you may have to edit the template configuration file of the style in which you are installing the new image. If you will recall from earlier in the chapter, these files have a name matching that of a templates subdirectory, such as subSilver.cfg or subBook.cfg, and list many of the graphics found on a forum. The entries in this list usually resemble these examples:

$images['name'] = "$current_template_images/image.gif";$images['name'] = "$current_template_images/{LANG}/image.gif";

If you open subBook.cfg in WordPad, you should see several lines in this format. Generally speaking, you should only edit the parts of a line after the last backslash and before the last quotation mark, which would be image.gif in the example. If your new image is not inside the images subdirectory of the style's directory, like templates/subBook/images, then you would need to replace $current_template_images with the correct path to the image. It is usually easier to simply put the new file in the style's images directory. The special {LANG} placeholder allows phpBB to use different versions of an image in support of multiple languages.

The one image you might expect to find in the configuration file�the forum's phpBB logo�is actually not there. To change the filename for the logo, you will have to edit overall_header.tpl. The HTML image tag for the logo resembles:

Notice the phpBB logo is the logo_phpBB.gif file. Most people want to change the logo quickly, so this is a good file to experiment with replacing or renaming.

Hacking phpBB

Altering the look of your forum is only one aspect of customizations that you can perform with phpBB. For some interesting changes, you'll most likely want to add some completely new features to your forum. You may also want to remove some features that you do not plan to use. To add new features, remove existing features, or otherwise alter the abilities of a phpBB forum, you will have to edit the code of the PHP script files that are the heart of phpBB. You may also need to edit or add new template files to the styles installed on a forum, as well. The process of making these kinds of changes is called modifying or hacking phpBB.

MODs and Hacks

There are many sets of instructions for altering phpBB's features available at online phpBB communities. Such downloads may include step-by-step instructions for altering core phpBB files or the SQL database, adding new forum files, or any combination of those three categories. These downloads are commonly called MODs or Hacks. Hack was the original term used during the era of phpBB 1 and is still used extensively in some phpBB communities. With the advent of phpBB 2.0, the term MODs, from a shortened form of the word modifications, also became popular. To avoid confusion, the term modification will be used in this chapter.

phpBB Modification

What exactly does a modification include? That will depend on the scope of the modification. Very simple modifications typically include one text file containing instructions for altering an existing phpBB file. More complex modifications may also include new files to be added to phpBB and a special installer file. Some extremely complex modifications typically include all of these, plus already edited copies of the original phpBB files. All these files will be placed together in a compressed file, typically in the ZIP format.

While a group of developers created phpBB, modifications are typically the work of individual phpBB users that needed the effect created by the modification. phpBB is open source and released under the GNU General Public License so, it and any derivative works (like modifications) can be freely distributed to others at no charge. Modification authors make their works available to others in the hope that other forum administrators will benefit from them and eventually contribute back to the larger phpBB community. Therefore, there is a large and diverse group of modifications created in different coding methods and writing styles. Some modifications are also released in developmental stages, and you should be careful about using those. They often contain bugs, security holes, or incomplete features that may annoy your forum's visitors.

The best places to find large selections of phpBB modification downloads are:

� phpBBHacks.com: http://www.phpbbhacks.com/

� phpBB Official Site: http://www.phpbb.com/

Many modification authors will also release their works on their own websites or other phpBB communities. If possible, make sure you only download modifications described as compatible for the version of phpBB you are using. There are many releases of phpBB 1 and phpBB 2, but not all modifications will work with every phpBB release. phpBB 1 modifications, mainly found only at phpBBHacks.com now, will not work on any phpBB 2 release. Some phpBB 2 modifications will work only with early or later versions of phpBB 2.0.

Installing a Modification

When you find and download a modification you wish to install, you need to follow a series of steps to place the new code in your forum and activate it fully. Like many other things, the exact steps needed vary with each modification. There is a standard way of proceeding that is common to all modifications, however. To begin with, let's install this simple modification. It adds a button to each user's posts that allows others to quickly search for all posts by that user.

# #-----[ OPEN ]------------------------------------------ # templates/subSilver/viewtopic_body.tpl

#
#-----[ FIND ]------------------------------------------
#

//--></script><noscript>{postrow.ICQ_IMG}</noscript></td>

# #-----[ IN-LINE FIND ]------------------------------------------ # </noscript>

# #-----[ IN-LINE AFTER, ADD ]------------------------------------------# {postrow.SEARCH_IMG}

# #-----[ SAVE/CLOSE ALL FILES ]--------------------------------------

#
# End

Time For Action�Installing a Small Modification

6. Locate the templates/subSilver/viewtopic_body.tpl file of your forum. Open this file in your text-editing program.

7. Use the text-editing program's search feature to locate this line of text in the file. In many programs, this feature can be accessed from the menus or by pressing Ctrl+F on Windows systems.

//--></script><noscript>{postrow.ICQ_IMG}</noscript></td>

Now, locate the text </noscript> within that line.
Directly after </noscript>, type a space and the text {postrow.SEARCH_IMG}. The final version of the line should look like this example:

//--></script><noscript>{postrow.ICQ_IMG}</noscript> {postrow.SEARCH_IMG}</td>

Chapter 4

Save and close the file. If necessary, upload it to your website, replacing the existing file there. You may repeat all of these steps with the templates /subBook/viewtopic_body.tpl file, if you wish.
Go to your forum and look at any post. You should see a new Search image below the post.

What Just Happened?

Congratulations, you have just installed your first phpBB modification! The majority of modifications contain a series of instructions similar to those on the previous page. Authors intend you to use these instructions as a basic guide to adding the modification to your phpBB files. By placing a little bit of new code inside your viewtopic_body.tpl file, you have enabled the search button that can be shown with forum posts.

Installing a Downloaded Modification

After you have downloaded a modification that you wish to install, you must first decompress the downloaded file if it is a ZIP file or another archive file format. When you do so, one or more new files, and possibly directories containing more files, will be created. When there is only one file, it will typically be a simple text file that you can open in WordPad. The name of the file is usually readme.txt, install.txt, install.mod, or something like that. For the sake of example, let's use install.txt.

If a modification contains an install.mod file, you may not be able to open this file by double clicking on it like other files. The file extension .mod has been used by a popular music file format for years, so music players like WinAMP usually try to open double clicked .mod files. In these cases, you will have to open the file through WordPad's File | Open menu.

The install.txt will contain all the instructions for installing the modification's changes, as well as the author's credits and notes about the changes. Larger modifications may include both a readme.txt and an install.txt file. In those cases, it's usually a good idea to examine readme.txt before doing anything else, as it may contain special instructions beyond those found in install.txt.

A few modifications are simply written out in paragraph form, but the majority use a common template of a header and simple commands called actions. The modification header will contain basic information such as the modification's name, version number, author, description, and an estimation of installation difficulty and time. Important notes about the modification and its history might also be found here, so be certain to read the header fully. Actions describe steps of the modification installation using a header containing a brief, descriptive name followed by one or more lines of code.

Here is an example of an action header, as it may appear in a file of instructions.

# #-----[ ACTION NAME ]------------------------------------------ #

The actual name of each action will replace the text ACTIONNAME. There are many kinds of actions, each of which has a different meaning. When used in a set of instructions, action names are usually typed entirely in capital letters.

Remember to back up any file you are instructed to alter before doing anything to that file. Refer to the Editing phpBB Files section earlier in this chapter if you need to refresh your memory.

The Copy Action

This action, labeled Copy, is an instruction to place files into certain new locations. Typically, the files to be copied are part of the modification and must be uploaded to your forum. Sometimes they already exist in the forum and just need to be moved, but special cases like that should be noted in the modification's instructions.

# #-----[ COPY ]------------------------------------------ # db_update.php to db_update.php functions_new.php to includes/functions_new.php templates/*.* to templates/subSilver/*.*

Above is an example of a typical Copy action. Each line lists a file to copy on the left and the destination of the copy on the right. Unless otherwise noted, the destination path will be relative to your forum's main directory. With the example, you would place db_update.php in the main directory, alongside viewtopic.php and profile.php, functions_new.php inside the includes/ directory, and all the files in the modification's templates/ directory inside the forum's templates/subSilver/ directory. The special notation *.* is a quick way of saying all files within this directory.