phpBB3 MODs Tutorial

What are MODs and how to install them

MOD stands for modification. Modifications are a way to add extra features and functionalities to your phpBB3 board. The changes which you can introduce using MODs can be purely cosmetic, or you can use them to add different tools, to improve the security of your board and a lot more.

You can find many different mods in the Modification Database of the official phpBB site. The MODs are grouped in sections depending on their purpose and functionality. You can also use the search function of the official phpBB site if you want to find something specific. Just type the keyword(s) in the respective field, from the Search in forums option select MOD Database Releases, mark the button Topics for Display results as, and click on Search at the bottom of the page. Each MOD also has a topic in the MOD Database section of the forum on the official site. It might be helpful to read what other people think about the particular MOD and whether they had any problems or issues with the installation process or with using the MOD in general.

There is also a section for MODs in development, but it's not advisable to install such MODs on a live site.

There's no universal way to install MODs because they can be designed for performing and adding a wide range of functions. They are also of various complexity. The more complex the function which is about to be added, the longer and more difficult the installation process.

However, there are some general directions which can be helpful in figuring out how to install the MOD you have chosen. This tutorial is on how to install MODs manually by making changes to template files and/or core files, executing SQL queries, etc. There's also a way to make the process automatic by using AutoMOD, which is itself a MOD. To learn how to install and use AutoMOD read the tutorial on installing phpBB3 MODs with AutoMOD.

Before you start the installation make sure you have a recent backup copy of the phpBB3 files and of the database used by the application.

The first thing that you have to do before installing any MOD is to download to your local computer the archive of the MOD you have chosen. Make sure the MOD you're downloading is compatible with the version of your phpBB3. Then you should unpack the downloaded archive. The unpacked MOD folder contains an install XML file with instructions on how to install the MOD, a license.txt file and optionally a root folder and/or a contrib folder, and an XSL file.

The root folder contains files and directories (if there are such) that have to be added to your phpBB3 installation. It might also contain some other installation script and optionally files for different languages, for those who use other languages than English on their boards, and template files. If there are any additional language and template files they'll be located respectively in folders called language and template inside the root folder. The contrib folder (if there's one) usually contains instructions on how to enable some additional features and add-ons as part of the MOD, if you want them, of course.

However, the essential things in the unpacked MOD folder that you really need in order to perform the installation are the installation instructions in the XML install file and, if there are any, the files and folders in the root directory that have to be added to the phpBB3 installation on your hosting account. You can open the XML file (install_mod.xml in our example) with your internet browser. To do this click on the file with the right mouse button and from the menu that appears go to Open With and select your browser.

The first things that you should be able to see in the opened XML file are the name and a short description of the MOD (Topic Preview in our example), the version of the MOD, the installation level (e.g. easy) and an approximate estimation of the installation time (e.g. 10 minutes). Right under this information are the author's name and a link to the MOD on the official phpBB site. After that there's a list of the files that have to be edited, and optionally if there are new files that have to be added. In our example there are several files that have to be edited and a few new files that have to be added:

Example MOD Install XML-Files To Edit and Add

When you scroll down the XML install file you'll see detailed instructions. If there are any files that have to be uploaded to your account, you'll see the path to their location on your local computer and the path to the folder to which you have to upload them on your account. The path on your account is shown as relative to the root phpBB3 directory. For example, if your phpBB3 is installed in a folder called phpbb3 in the root public_html directory on your account and you have to upload a file called topic_preview.php in the includes folder of your phpBB3 installation, the path would be public_html/phpbb3/includes/topic_preview.php. But in the instructions the path would be specified as includes/topic_preview.php. If there are any wildcards (*), this means that the whole folder with its subfolders and files has to be uploaded to the specified location:

Example MOD Install XML-Files To Copy

Further down the XML install file you'll see detailed instructions on what files have to be edited and the exact code in each file that has to be edited. Depending on the MOD, you'll need to add some new code before or after the specified code that's already in the particular file. You may also have to replace some old code with some new one, etc. There's a panel at the top of which you can see which file you have to edit (e.g. Open: search_results.html). Then under Find you'll be given the line of code that you have to find in that particular file, and under the code that you have to find you'll be given the new code and what you have to do with it: add it before or after the old code, replace the old code, etc. Sometimes you may also be instructed to find a particular line, and then to edit just part of that line (e.g. In-line Find):

Example MOD Install XML-File Edit Procedures

One way to edit the required files is to download them from your hosting account to your local computer using an FTP client, and then using a text editor (e.g. WordPad, Notepad) you should open the file, find the required code and add before or after it the new code, or replace it, whatever is required. To find the code that you need you can use the search function of the text editor. With Notepad and WordPad, for example, click on the Edit menu, then on Find (or just press Ctr+F on your keyboard), type part of the code in the search box and click on Find Next. Make sure the code you find matches exactly the one you have to edit. Then copy the new code from the install XML file and paste it wherever necessary in the file you're editing. After you make all the changes to the file save it and upload it back in the same location on your account.

You can also edit the files from the Files section of the Pixie control panel, but it may take you longer to find the required code. To edit a file in the control panel, just click on the name of the file with the left mouse button to see the content of the file, make the changes and click on the Save and Close button.

Depending on the MOD, in addition to editing files and uploading new ones you might also need to make some changes to the database used by your phpBB3 installation, or perform some DIY tasks, such as running a script file with your browser or changing some settings from the administration control panel of your board.

In case you have to make some database changes you'll be given the SQL query/command that you have to execute. Here is an example taken from the install XML file of a MOD:

Example MOD Install XML-SQL Query

What you need to do is to execute the specified SQL query. You can do this from phpMyAdmin. You can access phpMyAdmin from the Databases section of the Pixie control panel (there's a link on the right). After you access phpMyAdmin click in the left frame on the name of the database used by your phpBB3 installation. When you do it you'll see in the right frame the database tables. Above them there are several tabs. Click on the one labeled SQL, copy the SQL query from the install XML file of the MOD, and paste it in the text field that appears after you click on the SQL tab in phpMyAdmin. Then just click on the Go button to execute the query.

By default the SQL query that is given in the install XML file uses the default database table prefix, which is phpbb_ (e.g. ALTER TABLE phpbb_forum...). If you changed the default prefix during the installation of phpBB3, you have to change the prefix in the SQL query to the actual one.

To complete the installation of a MOD very often you also have to perform some DIY task, such as purging the phpBB3 cache, configuring some settings in the administration control panel, opening a script on your account with the internet browser, etc.

After you perform all the tasks, refresh your board to check the results. If you did everything correctly, there shouldn't be any problems.

As part of our phpBB3 hosting services all HostKnox clients can request a free MOD installation.