Customizing phpBB Forums
From ThemesWiki
| Official Page |
| Project Documentation |
| Download |
|
phpBB is excellent and powerful forum software in many areas. Customization possibilities are one of the strongest. This tutorial will guide you with the skills that can give your forum a complete face-lift or expand its features beyond anything you might have imagined.
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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] Editing phpBB Files
Throughout this tutorial, 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 tutorial. 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..
[edit] 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.
[edit] Creating a Copy Style
For the purposes of illustration, this tutorial 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.
[edit] Time For Action Creating a Copy Style
- Make a copy of the
templates/subSilverdirectory. The copy should contain all the same files found undersubSilver. - Change the name of the copy directory to
subBook. - Rename the
subSilver.cfgandsubSilver.cssfiles tosubBook.cfgandsubBook.css, respectively. - Open the
theme_info.cfgfile for editing. In this file, you will seesubSilverused several times. Change each of these instances tosubBook. Take care that you do not delete or change anything else in the file. Remember to follow the proper editing procedures you learned earlier. - The name of the subSilver style is referenced in around forty to fifty lines inside template files in your
subBookdirectory. 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 theoverall_header.tplfile. - 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.
[edit] 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:
[edit] 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.
[edit] 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 -
subSilver -
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.
[edit] 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 tutorial, 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.
[edit] 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.
[edit] 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.
When you customize an existing style, you will save a lot of time over creating a new one. The existing structure will already be complete, other than any changes you want to make. You can quickly replace any images or colors to alter the mood of the forum, as you will see later in this tutorial. The work of the original style creator will serve as a guideline to help you develop your knowledge. Then again, if you customize a style, that same existing structure will limit you unless changed greatly. Chances are that the customized style will bear some resemblance to the original, and many people will know that at first glance.
So which method is better? It really depends on how much you want to change the look of a forum. There is a good chance you can find an existing style to customize that will not limit you too much. If you look at enough styles, however, you will find that many of them are based, at least in part, on the original subSilver style. For something unique, you will have to create a new style.
In the rest of this tutorial, we will learn to customize an existing style. However, the examples will use the subBook style created earlier in the tutorial. This approach will allow us to preserve the original subSilver style of your forum, while making any changes we choose to the subBook copy.
[edit] Customizing Through the Stylesheet
The quickest way to overhaul the look of a forum is to change its colors, fonts, and other visual (but non-graphical) decorations. When we looked at the basic elements of a style earlier, we learned that a theme defines and controls these concepts through the formatting rules of a Cascading Style Sheet (CSS). CSS formatting rules add stylistic data, such as specifications for fonts, colors, sizes, borders, and spacing to a document structured with a markup language like HTML. Since phpBB creates documents of this kind to display a forum, the preferred method for changing these parts of the outward appearance of the forum is CSS.
CSS rules can be stored in three different places: in an external CSS file such as subBook.css, in overall_header.tpl, or in a combination of the overall_header.tpl method with some database storage. subSilver uses the combination method, and therefore subBook will also do the same.
[edit] Editing the Stylesheet in the Admin Panel
We can look at the database storage portion of the combination method first. It allows us to edit certain aspects of the stylesheet through the Administration Control Panel. The values entered into the administration feature are placed into the SQL database and later retrieved for use on every page phpBB displays.
To access the stylesheet-editing tool, visit the Styles Admin section of the Administration Control Panel, and click the Management link. This loads the same Styles Administration page you saw when exploring the means of removing installed styles. However, we are now interested in the Edit link instead of the Delete link. Clicking Edit will load the Edit Theme page, which provides a simple form for changing colors, fonts, text sizes, and a few other theme aspects.
[edit] Time For Action Editing the Stylesheet
- Locate the line labeled Background Color on the page.
- There is a form field on this line containing the text E5E5E5. Delete that text.
- Type CC0000 in the form field. Use the number zero, not the capital letter O.
- Scroll down to the bottom of the page and press the Save Settings button.
- On the next page, click the word Here in the text Click Here to return to Style Administration. This returns you to the Styles Administration page, where your change will be reflected.
What Just Happened?
As the name suggests, the Edit Theme page allows you to alter some aspects of the forum's theme. Each aspect that can be altered has a matching form field, such as Background Color for the background color of forum pages. By replacing E5E5E5 with CC0000, you altered the page background color from a light gray to red. If you replace CC0000 with E5E5E5 and Save Settings again, the change will be reversed.
[edit] Editing Other Theme Components
You can change more than just the background color of pages. The first two options on the Edit 'Theme' page actually allow you to modify two aspects of the style, even though Theme may be used in their labels. Alterations to the Theme Name will be reflected in board style selection lists and Styles Administration. Selecting a new Template can change the entire layout of a forum while keeping the current color scheme. All templates in your forum's templates directory will be listed in this selection box, even if they are not currently used in an installed style.
The remaining thirty-eight options are presented in a three-column format. The first column, Theme Element, describes the individual settings while the second column holds the current values. When you install a new style, some values may or may not be provided automatically; it varies from style to style. These two columns are the most relevant to your needs.
The third column, Simple Name, can hold some extra descriptive information about the use of these settings. If you look at the Edit Theme page for subSilver, you can see this in action. Unfortunately, phpBB does not have a method of importing Simple Name data when installing new styles, so this column is often ignored. You can enter short descriptions of your own, but otherwise only subSilver will use this column:
Since there are so many options on this page, let us concentrate on the types of values that can be entered, the settings used most often, and the ones you would most likely want to change. Many settings are alternative versions of others, so looking at every single one in detail is not necessary. All of the options are listed in a table at the end of this section.
[edit] Allowed Values
There are several types of values that can be entered and most settings accept only one type. Those restricted to one kind of value can be grouped under filename, color, font size, and font face settings. All other settings accept filename, color, and CSS class name values, but only one kind of value can be used in each group of these settings.
The filename settings CSS Stylesheet and Background Image should only be used with the names of existing files in the templates directory of a style. It is possible to use a file that is not in a templates subdirectory, but this often requires some editing of multiple template files. Some styles, including subSilver, will not use one or both of this pair when first installed. Make sure a value is filled in for CSS Stylesheet regardless, as you may find yourself needing it later. Background Image is optional.
Color settings require a hexadecimal color code. Hexadecimal color codes, sometimes called HTML color codes, are combinations of six letters and numbers that represent a color, usually prefaced with a pound symbol (#). Many websites provide charts and lists that show examples of these codes. When entering a hexadecimal color code into the color settings of this page, you must not include the pound symbol. The color settings will accept only six character values, so including the pound will cause the last character of the code to be cut off! That can lead to some weird color effects. You may be tempted to enter a color name, such as red or green, for the color settings. If you do so, however, you will get some strange results. Lists of the different hexadecimal codes are available on many websites. Two good lists can be found at http://www.htmlgoodies.com/tutors/colors.html and http://webmonkey.wired.com/webmonkey/reference/color_codes/.
Font size settings are limited to simple integer numbers like 9, 10, or 15. These will usually be related to a font size in pixel or point measurements, but the type of measurement can vary with each style. Since some styles may also use percentage measurements, you may want to leave these settings alone until you have determined the type of units used in the stylesheet.
The last of the restricted value settings font faces accepts comma-separated lists of typeface names. An example of a good value is Verdana, Arial, Helvetica, sans-serif. If you want to include a name that consists of more than one word in the list, place it inside single or double quotes: for example, 'Verdana', 'Trebuchet MS'. You can also use a single name, but it is a better idea to use a list. When a list is provided, the first font that is installed on the viewer's computer will be used.
The more flexible settings allow you to use filenames, colors, or CSS class names for values, as already stated. Filename values operate under the same restrictions as those for filename-specific settings. Color values can be hexadecimal color codes, including the pound symbol this time, or simple names like blue. CSS class names are names of Cascading Style Sheet formatting rules. They will usually be short names made of all lowercase letters and numbers. The formatting rules named will be used to control the display of everything that the theme element controls.
[edit] Commonly Used and Altered Elements
You have already learned about a few settings, such as font sizes and faces, in the previous section. Now let us examine some more useful options in the Edit Theme page.
[edit] Table Cell Colors
The Table Cell Color 1, Table Cell Color 2, Table Cell Class 1, and Table Cell Class 2 elements are interesting because they are perhaps the most commonly used. Any aspect of phpBB that displays data in table rows, such as the member list, forums, and topics, can use these elements to achieve an alternating row color effect. For compatibility with phpBB's internal coding, Table Cell Class 1 often has a value of row1 and Table Cell Class 2 a value of row2. This is a sort of unspoken standard, but one that is not always used.
[edit] Font Colors
Two options that many forum administrators like to change, but often cannot locate without help, are Font Color 2 and Font Color 3. All font color settings are used to color a variety of text, but these two are used for the special colors given to administrator and moderator usernames on the forum in several locations like online user lists. Font Color 3 assigns the administrator names' color, and Font Color 2 details moderator name color.
Again, these colors are used in other places as well, so be sure to look around the forum if you change them. It is very easy to change the name colors to something nice only to find your table headers or code BBCodes have become unreadable.
Once you have edited the elements to your preferences, you should click the Save Settings button at the bottom of the Edit Theme page to store the new values in the database. You will be shown a confirmation message that the settings have been updated, and the new settings should be reflected on any page loaded after that message.
The following table lists the names of theme elements and defines them:
| Theme Element Name | Description |
|---|---|
| CSS Stylesheet | Filename for a Cascading Style Sheet file. |
| Background Image | Image used as a background for the forum. Not used in subSilver. |
| Background Color | Color of page backgrounds. |
| Text Color | Default text color of all pages. |
| Link Color | Default color of all unvisited links. |
| Visited Link Color | Color for all links that have been visited. |
| Active Link Color | When clicking a link, it switches color. Not used in subSilver. |
| Hover Link Color | When moving the mouse pointer over a link it changes to this color. |
| Table Row Color 1 | Background color for table rows, often very light. |
| Table Row Color 2 | Another, usually medium, table row background color. |
| Table Row Color 3 | Third row background color, rarely used and is often the darkest. |
| Table Row Class 1 | CSS class name for table rows. Not used in subSilver. |
| Table Row Class 2 | Class name for a second set of rows. Not used in subSilver. |
| Table Row Class 3 | Class name for a third row set. Not used in subSilver. |
| Table Header Color 1 | Color for table headings. Also used for page borders in subSilver. |
| Table Header Color 2 | Second heading color. Also used for table borders in subSilver. |
| Table Header Color 3 | Third heading color. Also used for inner table borders in subSilver. |
| Table Header Class 1 | CSS class name for table heading cells. |
| Table Header Class 2 | Class name for a second set of table heading cells. |
| Table Header Class 3 | Class name for a third heading set. |
| Table Cell Color 1 | Background color of various common table cells. |
| Table Cell Color 2 | Alternative table cell background color. |
| Table Cell Color 3 | Another table cell background color. Not used in subSilver. |
| Table Cell Class 1 | CSS Class name for table cells. Often used to alternate row colors. |
| Table Cell Class 2 | Second Class name for cells. Often used to alternate row colors. |
| Table Cell Class 3 | Third possible class name. Not used in subSilver. |
| Font Face 1 | Default type face for most text. |
| Font Face 2 | Second type face, sometimes for topic titles. |
| Font Face 3 | Third type face. Often used for code BBCode tags. |
| Font Size 1 | Smallest font size. |
| Font Size 2 | Medium font size. |
| Font Size 3 | Largest font size, used for most text, including posts. |
| Font Color 1 | Quote BBCode text color. |
| Font Color 2 | Code BBCode text color. Also moderator username color. |
| Font Color 3 | Table header cell text color. Also administrator user name color. |
| Span Class 1 | A CSS class name for use in HTML span tags. Not used in subSilver. |
| Span Class 2 | Another class name for span tags. Not used in subSilver. |
| Span Class 3 | Third class name for span tags. Not used in subSilver. |
[edit] Changing CSS Styles to Change the Look of Your Site
The second portion of the combined stylesheet storage method deals with CSS-formatting rules placed in the overall_header.tpl file of a template. These formatting rules, or CSS classes, control many aspects of the forum's display. By editing the CSS classes directly, you can create a broader range of design changes than are possible through the Edit Theme utility.
The first step is to locate the CSS classes in templates/subBook/overall_header.tpl. Open that file in WordPad and scroll down to a line that contains <style type="text/css">. All of the CSS classes are between this line and another containing </style>. Each of the classes has two major parts: a class name, also known as a selector, and a declaration block.
The class name is a short and descriptive name that will be used to associate the individual classes with elements of forum pages. Names may be the same as those of HTML tags, such as body, td, hr, or font, or author-created names preceded by a period, such as .postbody or .quote. A combination of the two, such as td.row1 is also acceptable. You will also see classes containing names separated by commas; this is a shortcut for applying one class to all of the named elements.
Declaration blocks consist of one or more declaration lines enclosed in curly brackets. Each declaration line holds a property name and value separated by a colon and ends with a semicolon. Several declaration lines can actually be placed on one line of text, as long as a semicolon ends each declaration, and you will see several such cases in the files. Property names and values specify the actual formatting features like colors, borders, and so on. Here is a sample line for underlining text:
text-decoration: underline;
Most styles' stylesheets will also include comment lines starting with /* and ending with */ that explain what display elements of the forum each class will affect. Comment lines do not affect any layout features themselves. An entire class might resemble this sample.
td.row2
{
color: black;
/* White Background */
background-color: #FFFFFF;
}
Until you reach a point where you are adding new features to your forum, you should not need to alter class names very much, if at all. On the other hand, editing the declaration blocks will let you do just about anything. By examining the existing entries in the file, you will get a good idea of what you can do by adding or removing declaration lines in each class.
[ Note - Hundreds of possible combinations of property names and values exist. There are also some types of class names not covered here or used in subSilver and subBook. For more information about Cascading Style Sheets beyond the scope of this tutorial, check out these resources:
184 Manually selected Style Sheet Resources: http://www.cbel.com/style_sheets/
W3Schools CSS Tutorials: http://www.w3schools.com/css/
css-discuss Wiki http://css-discuss.incutio.com/ ]
In overall_header.tpl, you will see many declaration lines containing special template variables like {T_BODY_BGCOLOR}. Template variables are a special feature of phpBB used to substitute data into the layout generated from the template files. Some recognizable characteristics of template variables are names beginning and ending with curly brackets and containing only letters, numbers, underscores, and periods. You will not see template variables whose names contain semicolons, colons, or most other special characters. Any template variables in the stylesheet will be replaced with the "theme element" values of the Edit Theme utility; they are where the combination of the database and overall_header.tpl come into play. For a listing of the template variables and their matching theme element names, consult the table at the end of this section.
Template variables can be applied to classes for other types of theme elements, as well. For an example, look at the first class in subBook's overall_header.tpl. This body class, which affects the HTML <body> tag and thus an entire webpage, uses several table color elements in scrollbar-related declaration lines. These lines will change the colors in certain parts of your web browser's scrollbar, if the browser supports them. The scrollbar properties are not part of the standard CSS features and only function in certain browsers, such as Microsoft's Internet Explorer. Netscape and Mozilla browsers ignore the scrollbar properties.
For an interesting example of how you can change the look of your forum, locate the .bodyline class. This would be on a single line about eight lines below the body class. Near the end of the line, you can see the border property, which manages the border around the forum pages. It should currently have values that create a solid, one pixel wide, light blue border, with the color changeable in Edit Theme. Now, replace the word solid with dashed. Save this change and look at your forum's index page it now has a dashed line for a border. You can also try dotted, ridge, and groove for some other effects. By altering the number portion of the 1px code in the same area, you can increase and decrease the width of the border. Try 10px and dotted together for an unusual view.
[edit] Using External Stylesheets
By placing a stylesheet in overall_header.tpl, phpBB gives you a lot of control through the Edit Theme page, but it comes at a cost. The stylesheet has to be freshly loaded on every page, and this can slow down a very busy forum. An alternative is to use an external stylesheet file, such as subSilver.css and subBook.css. Web browsers do not refresh external stylesheets as often, resulting in smaller page sizes and faster loading times. This type of stylesheet does not support the Edit Theme utility, however, so the utility is rendered almost useless. Edit Theme will still control administrator and moderator username colors and, depending on the style, row classes and colors.
To enable the external stylesheet for subBook, find the following line in templates/subBook/overall_header.tpl:
This line is an HTML comment line due to the!-- and - character sequences near the beginning and end. Like the Cascading Style Sheet comment lines, it has no effect on the page layout. By removing the comment characters, you can have the line become a reference to the external stylesheet file. The line should then look like this:
<link rel="stylesheet" href="templates/subBook/{T_HEAD_STYLESHEET}" type="text/css">
You should also delete all the CSS classes in overall_header.tpl, or they will override the same classes in the external stylesheet. If you have made any changes to those CSS classes, make identical changes in subBook.css before deleting the code from overall_header.tpl. You will find the same classes in subBook.css, but you cannot use template variables in external stylesheet files. If you make these same changes in simple_header.tpl and admin/page_header.tpl, you can control the appearance of the entire forum from a single stylesheet file. Note that the final line in admin/page_header.tpl will be slightly different. You need to add ../ before templates in this line for the stylesheet to be displayed properly on pages using this file. Those pages are generally Administration Control Panel pages, which only you may see (unless you give other users administrator access). The final line for admin/page_header.tpl is:
<link rel="stylesheet" href="../templates/subBook/{T_HEAD_STYLESHEET}" type="text/css">
The following table lists the template variables and related theme elements:
| Template Variable | Theme Element Name |
|---|---|
{T_HEAD_STYLESHEET}
| CSS Stylesheet |
{T_BODY_BACKGROUND}
| Background Image |
{T_BODY_BGCOLOR}
| Background Color |
{T_BODY_TEXT}
| Text Color |
{T_BODY_LINK}
| Link Color |
{T_BODY_VLINK}
| Visited Link Color |
{T_BODY_ALINK}
| Active Link Color |
{T_BODY_HLINK}
| Hover Link Color |
{T_TR_COLOR1}
| Table Row Color 1 |
{T_TR_COLOR2}
| Table Row Color 2 |
{T_TR_COLOR3}
| Table Row Color 3 |
{T_TR_CLASS1}
| Table Row Class 1 |
{T_TR_CLASS2}
| Table Row Class 2 |
{T_TR_CLASS3}
| Table Row Class 3 |
{T_TH_COLOR1}
| Table Header Color 1 |
{T_TH_COLOR2}
| Table Header Color 2 |
{T_TH_COLOR3}
| Table Header Color 3 |
{T_TH_CLASS1}
| Table Header Class 1 |
{T_TH_CLASS2}
| Table Header Class 2 |
{T_TH_CLASS3}
| Table Header Class 3 |
{T_TD_COLOR1}
| Table Cell Color 1 |
{T_TD_COLOR2}
| Table Cell Color 2 |
{T_TD_COLOR3}
| Table Cell Color 3 |
{T_TD_CLASS1}
| Table Cell Class 1 |
{T_TD_CLASS2}
| Table Cell Class 2 |
{T_TD_CLASS3}
| Table Cell Class 3 |
{T_FONTFACE1}
| Font Face 1 |
{T_FONTFACE2}
| Font Face 2 |
{T_FONTFACE3}
| Font Face 3 |
{T_FONTSIZE1}
| Font Size 1 |
{T_FONTSIZE2}
| Font Size 2 |
{T_FONTSIZE3}
| Font Size 3 |
{T_FONTCOLOR1}
| Font Color 1 |
{T_FONTCOLOR2}
| Font Color 2 |
{T_FONTCOLOR3}
| Font Color 3 |
{T_SPAN_CLASS1}
| Span Class 1 |
{T_SPAN_CLASS2}
| Span Class 2 |
{T_SPAN_CLASS3}
| Span Class 3 |
[edit] Customizing through Images
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.
You can also download new graphics from phpBB communities, of course. Both phpBB.com and phpBBHacks.com, which offer style downloads as mentioned previously, also offer some graphic sets. Some of their image downloads are rank and emoticon images, but you can find packs of normal forum buttons too. A few style authors have also made special PSD image packs available, which 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.
[edit] 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 tutorial, 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:
<img src="templates/subBook/images/logo_phpBB.gif" border="0" alt="{L_INDEX}" vspace="1" />
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.
[edit] 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.
[edit] 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 tutorial.
[edit] 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.
[edit] 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
[edit] Time For Action Installing a Small Modification
- Locate the
templates/subSilver/viewtopic_body.tplfile of your forum. Open this file in your text-editing program. - 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> - 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.tplfile, 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.tplfile, you have enabled the search button that can be shown with forum posts.
[edit] 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.
[ Note - 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 ACTION NAME. 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.
Note - 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 tutorial if you need to refresh your memory.
[edit] 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.
[edit] The SQL Action and Editing the Database
When a hack adds new features, they are often tracked in some manner by the SQL database of the forum. In order to get this working, you will need to make changes to the database. Modification authors will include these changes using one or more of three methods. The first method, and most popular in more recently created modifications, is to include an installer script file. Installer files are special files with a .php filename extension that can make database changes for you. They are typically named install.php or db_update.php, but the name can have some variety. To use these files, you normally only need to place them in your forum's directory structure (the Copy action handles that) and run the file.
This part might be confusing to you. People learning how to install modifications often ask, "What does it mean to run the file?" To run a .php file, you need to visit it in your web browser like a normal web page. A good comparison comes from thinking of your forum's viewtopic.php, which displays all topics. Every time you read a topic in the forum, you are running the viewtopic.php file. Just visiting your uploaded db_update.php file will begin the process of editing the database. Some complicated installers may walk you through several steps.
[ Note - Many installer scripts will not work unless you log in to the forum using an administrator account before running the file. Always be sure to log in first, and delete the installer file immediately after running. Leaving an installer script in place can be a major security risk! ]
A second method of including database changes is to place a list of SQL query commands in the installation instructions under an SQL action. The third method places the same kind of list in a separate text file, which might be named sql.txt or schema.sql. Other names are possible, but the important thing to note is that any file with an extension of .sql is a text file containing SQL queries. When either of these two methods is used, you will need to do one of two things: create your own installer script or run the changes manually.
It is not very hard to create your own installer script. In fact, there are generators that can create a db_update.php file for you! One such generator can be found at http://www.phpbbhacks.com/forums/db_generator.php. Simply copy the SQL queries from the SQL action or file and paste them into this or another generator, submit the form, and you will be presented with the code of a db_update.php file. You can download the file directly from that page, place it in your forum, and run the file in the same way you would run an author-supplied installer.
[ Note - Some SQL queries may not be compatible with db_update.php generators. These will usually produce installer scripts that display parse errors when run. If this happens, visit a friendly phpBB support forum and ask for help with making the queries compatible. ]
In order to make database changes manually, you can use phpMyAdmin or another similar database management utility. However, you may need to edit the SQL queries before you can do this. When you installed phpBB, you had an option to enter a database table prefix. phpBB uses the value of this option for the beginning of all database table names. Each query in a modification should mention a database table name such as phpbb_posts or phpbb_config. If your chosen table prefix were myforum_, you would need to change the table names to myforum_posts and myforum_config before using the queries. Installer script files will typically make this change automatically, so you should consider generating one if you are uncomfortable with this process. These are some queries as they might appear before and after changing the table prefix:
CREATE TABLE phpbb_tracker ( tracker_id mediumint(8) DEFAULT '0' NOT NULL, tracker1 tinyint(1) DEFAULT '0' NOT NULL, tracker2 varchar(40) NOT NULL, PRIMARY KEY (tracker_id), ); CREATE TABLE myforum_tracker ( tracker_id mediumint(8) DEFAULT '0' NOT NULL, tracker1 tinyint(1) DEFAULT '0' NOT NULL, tracker2 varchar(40) NOT NULL, PRIMARY KEY (tracker_id), ); INSERT INTO phpbb_tracker (tracker_id, tracker1, tracker2) VALUES (1, 3,'Some text'); INSERT INTO myforum_tracker (tracker_id, tracker1, tracker2) VALUES (1, 3,'Some text');
With the queries in the proper format, open phpMyAdmin and, if necessary, select your database in the left column. Click on the SQL tab or Query Window link. Either of these will load a page containing a large text box. Copy the SQL queries from the modification instructions or text file and paste them into this box. A click of the Go button should run the queries on the database automatically.
[edit] The Open Action
This simple action tells you the name and location of a file you need to edit. You should open this file in WordPad, or your favorite text-editing program, and be prepared to make changes to it. If you have not already backed up the file, do so now. All the other actions that follow an Open action should be preformed on the file listed in this action until you reach the end of the instructions or another Open action.
# #-----[ OPEN ]------------------------------------------ # includes/functions.php
[edit] The Find Action
Each Find action is followed by one or more lines of code that should be contained within the file in the last Open action. Your goal is to locate this code, which is supposed to be an easy task. Most text-editing programs, including WordPad, have a Find or Search function that makes searching the entire file quick and easy. The Find function should be accessible through the menus of the program or, in Windows programs, by pressing Ctrl+F.
Unfortunately, there are some problems that can make finding lines a chore. First, several versions of phpBB have been released. Each version has certain code changes, so phpBB 2.0 will have some modifications for early releases where the Find code is very different than the code in the latest version. In these cases, it is often best if you do not install the modification unless the relevant changes between versions seem minor. Another problem is that some modifications try to find code that has been changed, or even removed, by other modifications already. Some authors have tried to bypass this problem by only listing the first few characters of each line to find. That practice has created yet another problem due to misinterpretation of the actions that follow Find instructions. Finally, some lines of code appear more than once in some files. You may need to edit only a specific appearance or all instances.
How can we solve these problems? Sometimes it is not very easy. If you cannot locate some Find code, the first solution to try is searching for smaller portions of the code. Suppose you have a hard time locating the line of this instruction:
# #-----[ FIND ]------------------------------------------ # 'SOME_TPL_VARIABLE' => $some_php_variable,
Looking for a key part of the line, like SOME_TPL_VARIABLE, may allow you to find the line even if it has already been changed by another modification or version of phpBB. The ability to adapt lines of code is a key skill when installing modifications and you may need to develop this skill over time.
When dealing with lines or blocks of code that appear in a file several times, keep in mind that most modifications are written based on a top-to-bottom order. Say you have instructions containing two Find commands for one file, with the code of the second appearing twice in the file. The author usually means for you to locate the first appearance following the code of the first Find command.
[edit] The Addition Actions
Three actions can add a new code to a file: Before, Add; After, Add; and Replace With. Each of these addition actions will always follow a Find action, and operate in reference to the code in the Find action. In the case of Before, Add actions, the code following the action should be placed into the file on a line before the code of the Find action. For After, Add actions, the codes go onto a line after the Find action's code. A Replace With action will delete the Find action's code and substitute the new code for the old.
For the most part, these are simple steps. There is one point about both Before, Add and After, Add actions that cannot be stressed enough, and that is always place the new code on a new line, separate from all other code. Some modification authors, as has been mentioned, include only partial lines of code in their Find actions. The problem with this practice is that modification users tend to add new code right after that in a Find action, on the same line. This places new code right in the middle of the original code, creating a series of syntax errors that can make a forum inaccessible. If you always add code before or after Find code by inserting it on a completely new line, you should be able to avoid this problem.
To illustrate how the code of a file should look, here are some sample action sequences and the correct resulting code. For the sake of these examples, assume a file containing the following code has already been referenced in an Open action.
<?php $number1 = $number2 = $number3 = 0; $number1 = $x + $y; $number2 = $y + $z; $total = $number1 + $number2 + $number3; echo 'The total is: ' . $total; ?>
First, a simple Find and After, Add combination:
# #-----[ FIND ]------------------------------------------ # $number1 = $x + $y; $number2 = $y + $z; # #-----[ AFTER, ADD ]------------------------------------------ # $number3 = $a + $b;
This sequence should create:
$number1 = $number2 = $number3 = 0; $number1 = $x + $y; $number2 = $y + $z; $number3 = $a + $b; $total = $number1 + $number2 + $number3;
A Find and Before, Add combination is next:
#
#-----[ FIND ]------------------------------------------
#
$number1 = $x + $y;
$number2 = $y + $z;
#
#-----[ BEFORE, ADD ]------------------------------------------
#
$my_array = array('a' => 1, 'b'=> 2, 'x' => 3, 'y' => 4, 'z' => 5);
while( list($key, $value) = each($my_array) )
{
$$key = $value;
}
After applying this sequence, the file would contain:
$number1 = $number2 = $number3 = 0;
$my_array = array('a' => 1, 'b'=> 2, 'x' => 3, 'y' => 4, 'z' => 5);
while( list($key, $value) = each($my_array) )
{
$$key = $value;
}
$number1 = $x + $y;
$number2 = $y + $z;
A Find action followed by a Replace With action could be:
# #-----[ FIND ]------------------------------------------ # $total = $number1 + $number2 + $number3; # #-----[ REPLACE WITH ]------------------------------------------ # $average = ($number1 + $number2 + $number3) / 3;
That sequence would transform the end of the file into this snippet of code.
$average = ($number1 + $number2 + $number3) / 3; echo 'The total is: ' . $total; ?>
Finally, here is another version of the earlier Find and After, Add sequence. This time, the Find action contains only portions of the lines. The result of applying the sequence should be the same as if the full lines were given.
# #-----[ FIND ]------------------------------------------ # $number1 = $number2 = # #-----[ AFTER, ADD ]------------------------------------------ # $number3 = $a + $b;
[edit] The In-Line Actions
Despite what you have just learned about the importance of adding code on new lines, sometimes you will need to change a piece of code within a line. The In-Line actions are used for this. There are four of these: In-Line Find; In-Line Before, Add; In-Line After, Add; and In-Line Replace With. Ideally, you will see a Find action with a long line of code, followed by an In-Line Find with a short snippet of that line, then one of the other three In-Line actions. Use them just as you would their normal counterparts, but this time do not add the new code on a separate line. You will actually insert the code inside the current line. In several modifications that use In-Line actions, you may have to change a line in several different places.
Using the same short file above, here is an example of an In-Line Replace With action sequence that edits two parts of one line.
# #-----[ FIND ]------------------------------------------ # echo 'The total is: ' . $total; # #-----[ IN-LINE FIND ]------------------------------------------ # total # #-----[ IN-LINE REPLACE WITH ]------------------------------------------ # average # #-----[ IN-LINE FIND ]------------------------------------------ # $total # #-----[ IN-LINE REPLACE WITH ]------------------------------------------ # $average That sequence alters the end of the file to look like: $average = ($number1 + $number2 + $number3) / 3; echo 'The average is: ' . $average; ?>
[edit] The Last Action
Almost every modification's instructions end with a variation of this action:
# #-----[ SAVE/CLOSE ALL FILES ]------------------------------------------ # # End
This is the last step of the instructions. It serves as a reminder to save your changes, close any remaining open files, and transfer edited files to your forum if necessary. Once you have done those things, you should be finished with the modification installation. You should thoroughly test the installation with your administrator account, a normal user account, and, if necessary, a moderator account. Many modifications add features that work differently for accounts with different permissions. For testing purposes, it is best if you only install one modification at a time. If you were to install three or four modifications simultaneously and you encounter an error in your forum, you might have a hard time tracking down the cause.
The following table provides a quick reference of the modification Action:
| Action Name | Definition |
|---|---|
| Copy | Copies one or more files from one location to another. |
| SQL | Runs one or more SQL queries on your forum's database. These should usually be completed before installing
the remainder of the modification. |
| Open | Opens the file in preparation for editing. Every action following this until the last action, or another
Open action, should be performed on this file. It is followed by a single filename. |
| Find | This locates the code in the file and is followed by code. |
| After, Add | Places the following code on a new line after the code in the preceding Find action. It always follows
a Find action. |
| Before, Add | Places the following code on a new line before the code in the preceding Find action. It always follows
a Find action. |
| Replace With | Deletes the code found in the preceding Find action and puts the following code in its place. It always
follows a Find action. |
| In-Line Find | Usually follows a Find action. Locates the following code inside a longer line of code. |
| In-Line After, Add | Places the following code after the code in the preceding In-Line Find, on the same line of code.
It always follows an In-Line Find action. |
| In-Line Before, Add | Places the following code before the code in the preceding In-Line Find, on the same line of code.
It always follows an In-Line Find action. |
| In-Line Replace With | Deletes the code in the preceding In-Line Find and put this code in its place on the same line of code.
It always follows an In-Line Find action. |
| Save/Close All Files | Signals the end of file changes and reminds you to save your changes. It is always the last action of a
modification. |
| Add SQL | This is an older form of the SQL action, with the same meaning as that action. |
[edit] The Trouble with Templates
One very important aspect of modification installation remains, just when you thought you had finished it. When you install modifications, you will see that almost all of those modifying or adding template files will only mention the subSilver template in their instructions. By this time, you should have installed at least one other template on your forum. With so many templates existing, it is not practical for authors to mention all of them in their instructions. Since every phpBB forum has subSilver installed at some point, and many templates are built from subSilver, only that one template gets mentioned, with an unspoken understanding that it is really a reference to all templates.
The trouble with templates is that you have to install every modification's template file changes to all your installed templates, even though the instructions do not tell you to do this. Also, if you install modifications and later install new templates, you have to apply the modifications to those templates. Should you forget to modify a template, any forum members using that template will not be able to access the modification's features unless they switch to another that you did edit.
Another problem in this area is the code of the templates themselves. While many templates are created from subSilver, quite a few are not. The latter kinds tend to have some very different markup language coding in their files. It can seem nearly impossible to locate code in a Find action unless you break it down into individual template variables. You might actually have to rewrite the new template files or code to match the look of the alternative templates, too. It can be quite a headache.
[edit] Uninstalling Modifications
Occasionally, you may have a need to remove a modification after installing it. Maybe you've found that two modifications are conflicting with each other or a modification does not live up to your expectations. Whatever the reason, uninstalling tends to be easier than installing.
There are two methods of removing a modification's changes to your files. Since you created backups before editing any of your files, you can replace your current files with those backup copies. This reverts the forum's files to the same condition they were in before the modification was installed. If you have made changes to the files other than installing this modification, then you should not restore the backup files. Doing so in such a case will cause your other changes to be lost.
The second method is to go through the modification's instructions as if installing, but invert the action commands. For example, if the instructions have a Find action followed by an After, Add action, you would locate and delete the After, Add code. In the case of a Find and Replace With combination, you would search for the Replace With code, remove it, and place the Find code at that location. To further illustrate these concepts, the following example removes the Search button added to posts in the earlier modification installation exercise.
[edit] Time For Action Uninstalling a Small Modification
- Locate and open the
templates/subSilver/viewtopic_body.tplfile of your forum in a text-editing program. - Use the text-editing program's search feature to locate this line of text in the file. Again, most programs allow accessing such a feature from their menus or by pressing Ctrl+F on Windows systems.
//--></script><noscript>{postrow.ICQ_IMG}</noscript> {postrow.SEARCH_IMG}</td> - Now, locate the text
{postrow.SEARCH_IMG}within that line. - Delete this text and the single space before it. The line should once again look as it originally did:
//--></script><noscript>{postrow.ICQ_IMG}</noscript></td> - 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.tplfile, if you wish. - Go to your forum and look at any post. You should see that the Search image is no longer shown.
What Just Happened?
By reversing the actions you took to install the Search button modification, you have removed it from your forum. Instead of finding the original code and adding to it, you searched for the modified code. Then you removed the extra code added by the original modification. This restored the altered file to its original state.
[edit] Removing Other Changes
The need to remove new files and database changes is common to both methods of removing file changes reviewed before the previous example. New files added by a modification are quick and easy to deal with: just delete them. Removing database changes is a more complex aspect of uninstallation; however, phpMyAdmin is a handy tool for making this simple. When a modification has added a new table or a new column in a table, you can locate this addition in phpMyAdmin and click a Delete link, which often takes the form of a trash can icon, next to it. phpMyAdmin will ask you to confirm the deletion (or dropping, as it is called when dealing with tables or columns); do so and the change will be gone.
[edit] Example Modifications
Thousands of modifications for phpBB have been released for public use in the years since phpBB first appeared. Think of almost any feature you might like to add to or remove from a phpBB forum, and there will probably be at least one modification for that already. New modifications are created and released each week so the possibilities for customizing a forum through this method are endless.
One of the most popular modifications is the massive File Attachment Mod, which contains over 140 files. It adds a new feature to phpBB's posting forums allowing users to upload files that will be attached to and displayed with their posts. Another commonly used example is Modify Profile, formerly known as Add New Field to Profile. This modification is an instruction guide for adding new information fields to user registration and profile-editing forms. Many different kinds of fields can be added, ranging from simple text entry boxes to drop-down selection lists. The data stored in the new field can also be displayed in public profiles, topics, posts, and other places throughout a forum. Dozens of modifications alter or add new BBCodes. User and administration management tools, online games, stores, chat rooms, recent topics, download systems, phpBB bug fixes or upgrades, and website portals are examples of some other widely used modifications.
These lists are only scratching the surface when it comes to describing the types of modifications available for your use. It will definitely be worth your time to check out a few websites that list modifications; you will find something that you want to install at your forum if you look closely enough. Chances are you will find many things to use in customizing your forum.
[edit] Moving Elements
Some layout alterations can be made to your forum without taking the time to search for a detailed modification. While you can find modification downloads for some of these, modifications often don't deal with layout issues very well. The differences in templates, and sometimes those created by other modifications, often force forum administrators to rearrange their layout without any help. In order to move elements like this, you will need to have at least a basic knowledge of HTML coding.
You might have noticed that subSilver and subBook have some statistical data and a login box at the bottom of their forum index pages. One popular change that you can make is to move one or more of those elements to another part of the page. By finding the layout code that creates them in index_body.tpl and placing it closer to the top of the file, you can emphasize that your users should log in or the number of users and posts on your forum.
[edit] Adding New Elements to Your Forum
Creating new areas in your forum will usually require a full modification, complete with instructions. There are a couple of simple things that can be done without a modification, however. One of these is to add a new link to your forum's header menu.
[edit] Time For Action Adding a Menu Link
- Locate and open the
templates/subBook/overall_header.tplfile for editing. You can use thesubSilveroverall_header.tplfile instead, if you like. - Find the line in this file containing the code
. There will be several tab spaces at the beginning of the line. - Insert the following code on a new line before the code you just located:
<a href="{U_VIEWONLINE}" class="mainmenu"><img src="templates/subBook/images/icon_mini_members.gif" width="12" height="13" border="0" alt="{L_WHO_IS_ONLINE}" hspace="3" />{L_WHO_IS_ONLINE}</a></span> - Save your changes to the file and view your forum. You may need to reload or refresh the forum page, but you should see a new Who is Online link with the other links near the top of the forum.
What Just Happened?
The menu links of your forum, like Profile, FAQ, and Search, are created by HTML stored in the overall_header.tpl template file. By duplicating a line or series of lines that creates one of these links and altering the line a little, you can create a new menu link. In this case, the new link points to the viewonline.php file, which displays a list of users currently visiting the forum. If these steps were written up as a modification, they might look like this:
#
#-----[ OPEN ]------------------------------------------
#
templates/subBook/overall_header.tpl
#
#-----[ FIND ]------------------------------------------
#
<!-- BEGIN switch_user_logged_out -->
<a href="{U_REGISTER}" class="mainmenu"><img src="templates/subBook/images/icon_mini_register.gif" width="12"
height="13" border="0" alt="{L_REGISTER}" hspace="3" />{L_REGISTER}</a></span>
<!-- END switch_user_logged_out -->
#
#-----[ BEFORE, ADD ]------------------------------------------
#
<a href="{U_VIEWONLINE}" class="mainmenu"><img src="templates/subBook/images/icon_mini_members.gif" width="12"
height="13" border="0" alt="{L_WHO_IS_ONLINE}" hspace="3" />{L_WHO_IS_ONLINE}</a>
</span>
#
#-----[ SAVE/CLOSE ALL FILES ]------------------------------------------
#
# End
[edit] Adding New Languages
Another common change made by forum administrators is the installation of new language files. If you plan to have many visitors who are fluent in languages other than English or cannot read English, you might want to download and install a language pack from phpBB.com's Downloads section. Each language pack adds a new option to the Board Language drop-down list in user profiles and the Administration Control Panel. Selecting that option will cause the forum to be displayed in that language. Posts will not be translated, but many links and other default text will.
When adding language packs, you should keep in mind that you may have to edit the new language files. Some modifications will include new language files or instructions for editing language files. If you add a new language and do not copy these changes to that language, then some text will not appear on your forum. This situation is similar to that for modifications and templates; you must edit every language, even if the modification's instructions only mention one.
[edit] Additional References
- For instructions on Creating phpBB templates, click here
- For instructions on Installing phpBB, click here
- For instructions on Configuring phpBB, click here
- For instructions on Troubleshooting phpBB Forums, click here
[edit] Source
The source of this content is Chapter 4: Customizing Your Forum of Building Online Communities with phpBB by Jeremy Rogers, Mike Lothar, Stoyan Stefanov (Packt Publishing, 2005).
