MODxBB Installation & Configuration Guide
Welcome to the MODxBB documentation. These pages are included in the MODxBB package as well as available online on modxbb.net/documentation.
This manual features a linked table of contents on the right side. There are also information concerning the date of creation and last modification for each page on the right block.
They allow to quickly check if and when a page was updated.
I have also created a CSS file for print output, which should come handy for those who prefer to read these documentation pages on paper.
1. About MODxBB and this documentation
1.1 MODxBB
MODxBB integrates MODx and phpBB into each other while retaining scalability.
MODx is a highly customizable content management system that can also be used as a content management framework.
The bulletin board phpBB is a very powerful community management system that is widely used as a communication platform for communities or customers, however, it holds potential for much more than that.
Administrators who would like to use both, MODx and phpBB face the problem that users would need to register and maintain two accounts for a single site. One of the main purposes of MODxBB is to solve this issue by integrating both systems into each other.
It is a lot more than just a bridge for user accounts, though. Using MODxBB, a developer can access both interfaces on any phpBB page as well as on any MODx page.
More about MODxBB and its features can be read in the article Welcome to MODxBB on modxbb.net.
1.2 This documentation
This documentation has turned more detailed than originally planned, thus the additional delay (beside the formerly mentioned main reason). It is meant to be understood even by unexperienced users, however, it needs to be noted that the deeper your knowledge on (X)HTML, CSS and PHP is, the more use you can make of MODxBB's potential.
This guide covers all possible installation types, hence you won't need to read all of it. The optional sections start with a notice about when they are needed to be read.
Despite the not too simple installation and configuration progress, it is fairly easy to handle MODxBB once installed. There is no reason to get intimidated. An interface for easier installation and configuration is planned to be part of future versions.
1.3 Additional tutorials
More detailed tutorials, tips and examples on the different topics will be added on the modxbb.net blog later.
2. Installation
2.1 Requirements
- MODx Evolution 1.0.0 - 1.0.5 • recommended: 1.0.5
- phpBB 3.0.4 - 3.0.9 • recommended: 3.0.9
- MODxBB 0.9.4 (included in this package)
- A web server or web space with the capability to run both phpBB and MODx.
2.2 Install MODx
Start with installing the latest version of MODx Evolution. If you already have one installed, it is strongly recommended to update it to the latest version. Visit the MODx download page to check whether you have the latest version and get it if necessary.
You should take the site offline during the following installation progress of phpBB and MODxBB: Log into the Manager --> click Configuration --> On the "Site" tab scroll to 'Site status' and set it to 'Offline'.
2.3 Install phpBB
Create a subfolder 'forum' (any other should work too, but 'forum' is recommended) and install phpBB in it. Same as above applies here: If you already have an installation, visit the phpBB download page to make sure you have the latest version.
It is strongly recommended that the forum is in a subfolder of MODx (the site root). Anything else should only be done by advanced users.
If you want to have your forum visually integrated like on MODxBB.net, you need to adjust your phpBB main templates (overall_header & overall_footer). There is a detailed explanation of how this works in the respective phpBB.com forum thread.
TIP: The browser-integrated inspecting tools (e.g. Firebug in Firefox or DragonFly in Opera) are very helpful when styling your forum, because they make finding selectors and properties in the theme's CSS file a breeze. I also recommend the freeware tool Colour To HTML as it saves a lot of time when you are looking for a particular colour of a theme that you want to change into another one (Color-picker -> find in CSS).
Another tip that might save you a lot of time: overall_header.html and overall_footer.html put together are a complete HTML page. You can put them together (e.g. in an editor) during adjustment and split them again once done with styling.
Note that making the phpBB templates part of a MODx template or document is theoretically possible, but far from reasonable.
2.4 Install MODxBB
NOTE: The function_user.php featured in the MODxBB package includes a phpBB bug fix [by Hedgehog of phpBB] in line 2186 that resolves the issue of gallery avatars not being sorted properly. I added it along with the ability of MODxBB to use gallery avatars.
2.4.1 Backup
IMPORTANT: Backup any file before overwriting or editing it!
To find out what files are modified in a full installation of MODxBB, either read the Files List page or browse the "Documents" folder including subfolders.
If you prefer you can backup the whole site root including subfolders, but that's not necessary. The files that are going to be overwritten (quick installation) or edited (custom installation) can be found in the Documents folder of MODxBB.
2.4.2 Minimum installation
If all you want is displaying your chunks or snippets on your phpBB forum, copy the modxapi.php (included in the MODxBB package) to your site root and skip to chapter 2.4.6.
2.4.3 Quick installation
There are three requirements for the quick installation:
1. phpBB 3.0.9
2. MODx Evo 1.0.5
3. None of the files that will be replaced were modified by the user prior to this installation (unless you don't mind losing your changes).
DON'T FORGET TO BACKUP!
Simply copy the files in MODxBB\Documents to your site root retaining the folder structure.
NOTE: This assumes your forum folder is called "forum". Also, if you don't want to adjust your JOT to MODxBB style then skip the JOT folder.
2.4.4 Custom installation
The custom installation is needed if you use either an outdated version of phpBB or MODx, have modifications of either that you want to retain or just want to know what has been edited.
I abandoned my original plan to go step by step through every single line by naming the line numbers, because that holds a risk of confusing parts and is only viable to a limited extent. Depending on versions and amount of modifications added by the users the potential differences are too big.
Instead we will use a more safe and clear method: Visit the WinMerge homepage and download the latest version of WinMerge. This is an excellent freeware tool that can compare files and show their differences.
Linux and Mac users can find alternatives in this article.
All you have to do now is comparing the files in the "Original" folder with those in the "Documents" folder. Note the differences and their location in the file. Do not rely on the line number though! Instead check the lines before and after the differences and include those at the same location of the file on your web server.
Example:
Once installed, start WinMerge and click on File -> Open to add the file index.php located in the "Documents" folder as well as the one located in "Original", which you can find in the extracted MODxBB package.
Now download the index.php of your website and include the differences of the other two files shown by WinMerge (don't forget to backup your files!). When done, upload the edited and saved index.php back to your website root. Do the same with the other files.
2.4.5 Install the elements [snippets, plug-in]
Installing the MODxBB elements is optional. You can either install all of them or only a part. You can skip this section, if you don't need any of them. Following table lists all included elements:
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| LatestTopicsBB | snippet | Displays latest active forum topics |
| LoginBB | snippet | MODxBB login and user stats panel |
| OnlineListBB | snippet | Retractable box showing who is online |
| PrevPollsBB | snippet | Configurable site poll history |
| SitePollBB | snippet | Pulls phpBB polls to any page of the site |
| PluginBB | plug-in | Generates respective phpBB profile links on Web User profiles |
More detailed descriptions including screenshots can be found on MODxBB.net.
To install any of the snippets above, log into your MODx manager, then go to:
Elements -> Manage Elements -> Snippets and click "New Snippet".
The name is same as the file name or as in the above list. For the description enter <strong>0.9.4 </strong>, then enter the description from the table above. The description helps to recognize the snippet, the version number is important to differ from possible future versions.
Now paste the content of the respective snippet text file, which are located in the "Documents" folder of the extracted MODxBB package. Don't forget to save the snippet!
To install PluginBB go to Elements -> Manage Elements -> Plugins and click "New Plugin".
For the name, description and code do as above.
Now click on "System Events" and activate the check-boxes for "OnUserFormRenter" and for "OnWUsrFormRender". Save and close.
2.4.6 Edit your phpBB templates
If you want to visually adjust your phpBB forum to the rest of your site, start with styling your forum as explained in chapter 2.3 first.
The following step is only needed if you want to place your MODx elements (snippets, chunks) on your phpBB forum or if you want to display MODx error messages on the forum. Else skip to 3.Configuration.
Either edit it from within the phpBB Admin Control Panel (General -> Style -> Templates) or find your overall_header.html which is located in forum\styles\YourTheme\template (assumed your forum is installed in "forum/" and your theme is called "YourTheme") and add following lines at the TOP of it:
<!-- PHP --> if (!defined('ADMIN_START')) { require_once($phpbb_root_path . '../modxapi.php'); } else { require_once($phpbb_root_path . '../../modxapi.php'); } global $modx; $modx = new MODxAPI(); $modx->connect(); $modx->getSettings(); <!-- ENDPHP -->The next step is only needed if you want to display MODx error messages on your phpBB board. Add following lines at the BOTTOM of it:<!-- PHP --> $MODx_output = ''; global $MODx_output; if ($MODx_output) { echo $MODx_output; } <!-- ENDPHP -->Now find your overall_footer.html (located in the same folder) and add following lines to the TOP of it:<!-- PHP --> global $modx; <!-- ENDPHP -->
3. Configuration
3.1 Configure MODx
If you did the minimum installation, you can skip to 3.1.4.
3.1.1 Delete the WebLogin form
If you had installed it, you should get rid of the WebLogin registration form and any of its login panels from your site, because phpBB takes care of registration now and userdata is internally passed over to MODx. To provide a log-in panel on your MODx pages use the LoginBB snippet included in the MODxBB package.
3.1.2 Add a JOT postcount column to your MODx database
This is only needed if you want to adjust your JOT to MODxBB style as shown on the introduction page and on the MODx forum.
Log into your phpMyAdmin, choose the MODx database and click on modx_web_user_attributes (you might have another prefix than modx_). Now click on "Structure" (upper bar), scroll to where it says "Add" (depending on the phpMyAdmin theme it might also be at the top). Add 1 field, click the radio button for "At End of Table" then click go.
Now enter following values:
Field: postcount
Type: int(11)
Default: 0 [choose "As defined:" from the drop down list]
Comments: jot comments
Click the Save button!
3.1.3 Enter a guest- and a default JOT Avatar
Same as above applies here: This is only needed if you want to add the MODxBB modifications to your JOT.
Open chunk.comment.inc.html in your jot\templates folder (the one you uploaded earlier) and replace assets/images/YourDefaultAvatar.png in line 8 with the URL to your default avatar and assets/images/YourGuestAvatar.png in line 10 with the URL to your guests avatar.
You can upload the avatars to your assets folder or anywhere else you want, however, to retain coherence I recommend to add a group avatar for the Guests (Anonymous user) and Registered users group on phpBB and use those.
You can do that in the phpBB Admin Control Panel (ACP) --> Users and Groups --> Manage groups --> Settings.
3.1.4 Add a Weblink for your forum
To have your forum displayed on lists like those of Wayfinder etc. (for instance in a site map) a Weblink should be added for it. This can be done in the MODx manager. For more information on how to create Weblinks read the MODx documentation or ask on the forums.
3.2 Configure phpBB
3.2.1 Enable PHP in templates
This is only needed if you want to display MODx elements or error messages on your forum, else skip to chapter 3.2.2.
Log into your phpBB ACP and click on "Security settings" in the "Server configuration" section on the General tab.
Scroll to "Allow php in templates:" and choose the "Yes" radio button. Click Submit. This step is necessary to parse the MODx commands added earlier to your phpBB template.
SECURITY NOTICE: Don't download and run untrusted phpBB themes while this setting is enabled! You should download themes from phpBB.com or other trusted sources only anyway.
3.2.2 Untie forms to guest sessions
This step is only needed if you want to allow guest votes on your MODx pages using the SitePollBB snippet.
Go to the same page as in 3.2.1 (ACP -> General -> Server configuration -> Security settings) and find "Tie forms to guest sessions:" (should be at the bottom). Change to "No" and click Submit.
3.2.3 Set your board to recognize style changes
This step is needed if you are planning to add chunks or snippets to your phpBB board. It ensures that your forum recognizes and displays visual changes made by your MODx elements on the forum.
Log into your phpBB ACP. On the General tab scroll to the "Server configuration" section and click "Load settings". Now find "Recompile stale style components:", change to "Yes" and click Submit.
3.2.4 Add your MODx elements to the phpBB style template(s)
You can now add commands to run your MODx elements (chunks, snippets) on the forum. They can be added to either of the templates edited in 2.4.6 or to any other template that belongs to the same theme, however, I recommend to add them to the bottom of your overall_header.html.
This is an effective way to display ads to your forum (while I personally dislike ads in forums), a ticker, an announcement like on MODxBB.net or anything else you want to make your forum readers aware of.
Examples:
To run a MODx chunk that displays announcements on your forum, open the overall_header.html located in forum\styles\YourTheme\template and add following line at the bottom within the PHP tags added in 2.4.6:
echo $modx->getChunk('Announcement');Where "Announcement" is the name of your chunk. If you added the MODx error output lines earlier it will look like this:<!-- PHP --> echo $modx->getChunk('Announcement'); $MODx_output = ''; global $MODx_output; if ($MODx_output) { echo $MODx_output; } <!-- ENDPHP -->else:<!-- PHP --> echo $modx->getChunk('Announcement'); <!-- ENDPHP -->You can also add this anywhere else within the template or in any other template. To run a snippet instead use:echo $modx->runSnippet('SomeSnippet');If your snippet comes with parameters, use:echo $modx->runSnippet("MySnippet", array('column'=>'3', 'tpl'=>'MyTemplate')Where 'column' and 'tpl' are parameters, '3' and 'MyTemplate' the values. If you prefer a more readable version, create an array first:$parameters['column']=3; $parameters['tpl']=MyTemplate; echo $modx->runSnippet('snippet_name', $parameters);Don't forget the PHP tags when entering it into your template:<!-- PHP --> $parameters['column']=3; $parameters['tpl']=MyTemplate; echo $modx->runSnippet('snippet_name', $parameters); <!-- ENDPHP -->
3.3 Configure MODxBB elements
To configure the included snippets you need to open them and edit the variables in the configuration paragraph. Future versions will come with an option to add snippet parameters.
3.3.1 LatestTopicsBB
There are three variables you can set in the configuration section. The first one is $num_post and determines the amount of latest posts shown on the page this snippet is placed on, the second, named $num_chars sets the number of charachters shown per post and the last one is $DefaultAvatar, it allows to set a default avatar, shown for posts done by users who don't have an avatar set.
3.3.2 LoginBB
There are two things you can configure in this snippet. The $phpBB_folder variable in the first paragraph needs to be set to the name of your main forum folder. If it is - as recommended - 'forum', leave this one as is.
To configure the ranks shown on the user panel scroll down to "switch ($phpBB_rank)". The case statements are visually ordered by the likelihood of occurrence, while the numbers are the one used by phpBB to identify the respective rank. Most of this is self-explanatory, there however, will be an article on MODxBB.net that explains in detail how the whole ranks and groups system in phpBB and MODxBB work.
3.3.3 OnlineListBB
This snippet also has $phpBB_folder in the first paragraph that needs to be set in case your forum folder is not named 'forum'.
If you do NOT have the SitePollBB snippet on the same page, uncomment the second paragraph please (by removing /* and */ ).
OnlineListBB uses jQuery, to learn what it is and how it works read the jQuery documentation. Don't get scared away though, it is in fact just one line you need to add in order to make this work, which looks like this:
<script type="text/javascript" src="js/jquery-1.5.min.js"></script>
Above line assumes that you downloaded the jQuery script and copied it into the "js" folder.
Keep in mind that you might not need this, if you already have jQuery running for another script. You also might have to set the compatibility mode, if you use mootools as well for instance.
3.3.4 PrevPollsBB
This snippet facilitates a configurable poll history. It can be used as a history for site polls shown by SitePollBB or separately.
If your forum folder differs from the default name, you have to adjust it here as well. In the first paragraph find $phpbb_root_path and replace 'forum' to the name of your forum folder. E.g. if your forum folder is named 'board', replace './forum/' by './board/'.
There are five variables you can set in the configuration section (second paragraph).
$forum_ids sets the forum ID's to automatically take the latest poll from to show them on your MODx page where this snippet is placed on.
$num_posts determines the total amount of polls shown in the history.
$per_page determines the amount of polls shown per page.
$page_start sets the start value for the pagination. Where request_var is a phpBB function, which allows to securely pass over request values. It is recommended to keep this value as is.
3.3.5 SitePollBB
The configuration of this snippet is done in the php file poll.php, located in the modxbb folder shipped with the MODxBB package.
3.4 Configure MODxBB documents
3.4.1 poll.php
This is the main engine for the SitePollBB snippet. It holds two options to configure it.
Change the value $prevpollID on line 20 to the ID of your MODx page that holds the PrevPollsBB snippet connected to your SitePollBB snippet. Explanation: There is a "Previous polls" link on the SitePollBB snippet, the target of that link is determined here.
Line 54 allows to set the forum(s) from where the polls are pulled from to be placed on your MODx page that holds SitePollBB. You can choose either one or multiple.
E.g. if you want the latest polls of your forums with the ID's 12 and 13 shown as a site poll on the front page change that line as follows: $CFG['poll_forum'] = array(12,13);
The lines 57-59 determine whether bbcode, smilies and urls are parsed.
3.4.2 edit.php
MODxBB supports phpBB custom profile fields. You can (but don't need to) have them displayed on your MODx Manager in the web user profiles.
To do so you need to adjust edit.php and signup.php both located in the modxbb folder. There is one example for "fullname" included. If you create a custom profile field in phpBB with "fullname" as field identification, you will have values for that field automatically displayed in the MODx web user profiles for "Full name". To create a cpf log into your ACP, click the "Users and Groups" tab and click "Custom profile fields" in the Users section.
This file processes edits done within phpBB to profiles and passes them over to MODx, hence custom profile fields need to be separately entered if you want them in the MODx profiles as well. Lines 38-47 show how that works. The prefix pf_ is always added, the rest (here "fullname") is the field identification of the custom profile field.
A detailed tutorial of how to create and manage custom profile fields, including how to adjust your MODx web user profiles might follow on the MODxBB.net blog at a later time.
3.4.3 signup.php
The second file that needs to be adjusted if you want to share custom profile fields between MODx and phpBB is signup.php.
Line 26 holds the example for "fullname": $fields["fullname"] = $cp_data['pf_fullname'];
This assigns the cpf pf_fullname to the column "fullname" of the MODx web user database. You can also assign it to any other column or create a new one for it of course.
Line 28 assigns the phpBB user ID to the "phone" field of MODx. I have chosen this way for simplicity reasons. You can certainly create a phpBB_ID field in your MODx database or use any other field. This is used to display the phpBB profile link in the MODx profiles, thus if you use any other than the default field you need to adjust PluginBB, too (just find "phone" and replace it by your preferred field).
In line 29 replace "forum/download/file.php?avatar=g2_1266363854.png" with the URL to your default avatar (for users who didn't choose one). This example shows how it looks like, if you assign a default avatar for a group in phpBB and use that in MODxBB, which is the recommended way.
If you do NOT want to use the welcome PM functionality (sending customizable welcome private messages to newly registered users) deactivate line 33 by adding a // in front of it.
3.4.4 welcome.php
This file allows to customize and individualize the welcome PM sent to newly registered users.
As shown in line 25 you can use $BridgeUser as a placeholder for the nick of the messaged user. You can theoretically use any of the user's profile values stored in either MODx or phpBB. Smilies and BBcode are supported as well.
In line 45 $fields["phone"] holds the phpBB user ID. In case you have chosen another field as described in the signup.php section, replace "phone" by the one you have chosen.
The other values of that array should be self-explanatory.
4. General TIPS & NOTES
4.1 Use CSS to customize the snippet output
All MODxBB snippets support CSS, thus allow to customize the output. It is recommended to use a CSS-reset to ensure they look the same on all browsers (that's also a general CSS recommendation, not just concerning MODxBB).
The CSS selectors page lists the selectors you can adjust in your CSS file to define what the output of the MODxBB snippets on your site looks like. The sample values are identical to those used on MODxBB.net.
4.2 It is possible to have a separate blog avatar
Same applies to other profile details. Because changes made on the phpBB control panels are passed over to MODx, but those made in the MODx manager profiles are not passed over to phpBB.
IMPORTANT: If you have to make manual user changes in the ADMIN control panel (for instance to change a user name), you need to change it in MODx as well, because that is not automated in this version yet.
4.3 MODxBB allows highly customizable content
You can adjust content for each user according to his or her level and rank, but also to any other property. That applies to properties in the profile as well as to generates ones.
Examples:
- It is possible to create content that is only visible to logged in users.
- You can write a snippet for ADs that are shown to anyone visiting your MODx pages, but users with 1000 or more posts or those with a special rank "Premium User" (special ranks can be created in the phpBB ACP).
- Welcome users who celebrate their birthday with special content (e.g. happy birthday banner).
More details and examples on this topic will be posted on the MODxBB.net blog at a later time.
4.4 Auth system
Some readers might wonder with the phpBB system integrated into MODx to that extent, why doesn't MODxBB just use the phpBB authentication only? First of all, yes that is indeed possible and at one point I wondered the same, however, with completely dropping the MODx accounts some functionality and add-on elements will stop working. That also includes the role and permission system within the MODx manager. Additionally to that you wouldn't be able to manage the accounts within the manager anymore.
If that is all no problem to you and you are PHP savvy there shouldn't be anything stopping you from giving it a go. All you need is deactivating the lines that send updates to the MODx accounts.
I will write a tutorial concerning this topic sometimes in the future, if there is a demand for it.
4.5 PluginBB profile links
This is just a quick tip that might come in handy. The phpBB profile links generated by PluginBB in the MODx profiles can be opened in the frame. If you prefer a quick opening in a full window just open it in a new tab (mid mouse button or shift + left mouse button).
4.6 MODxBB logs
MODxBB generates logs that can be read in the MODx Manager (Reports -> System Events). They are supposed to help finding potential problems and hack attempts. The most important information are displaying without clicking for details. This saves time and increases the readability. Log-in errors are displayed as "Error type - IP - username", where P-fail means wrong password was entered and U-fail means invalid username.
4.7 SPAM counter measures
This topic is not directly related to MODxBB and not phpBB exclusive either. Anyone running a forum is very likely to have encountered the spam problem. Particularly since the beginning of this year there has been an increasing surge of spam attacks.
There are various ways to safe your forum from spam annoyance. I originally planned to introduce some of them here, but I found phpBB.com to already have a useful topic on this. Thus I will just add the links here:
Preventing Spam in phpBB3 - Most of the hints are also applicable for other boards.
Spam Discussion - Related discussion, featuring additionally tips.
4.8 Use Web2Manager to promote Web Users
When a user registers, MODxBB creates a respective web user account on MODx. Web2Manager is a very useful plug-in to quickly promote web users to Manager users. It also allows to, vice versa, create a web user account from an existing Manager user account. Existing accounts will get updated.
The newest version can be downloaded here: Web2Manager-0.3.3.zip
5. Known issues
5.1 Site poll options
In very rare cases an update of a site poll might add 2 options if guest voting is allowed AND guests are allowed to re-vote AND multiple votes are enabled. This is very unlikely to happen, but not impossible.
Workaround: Just delete the additional options.
5.2 LoginBB logout
Logging out using the link featured in the LoginBB snippet redirects to forum index page instead of the page visited when logged out, unlike when logging in.
Note: This is NOT a bug. Sending users back to the page they visited before logging out would have needed to modify another core file, while users who log out of a site will in most cases not care to where they get redirected to anyway.
Workaround: A modification of the phpBB function meta_refresh is needed to change the redirection of logging out users.
5.3 Page tags
MODx page tags ([~ID~]) are not evaluated on phpBB pages. This might change in one of the future versions.
N!Ce aka A.S.
Page Information
| Last Modiefied: | 20 November 2011 |
| Page Version: | 1.2.3 |
| First Published: | 17 May 2011 |
Table Of Contents
- 1. About MODxBB and this documentation
- 2. Installation
- 3. Configuration
- 4. General TIPS & NOTES
- 5. Known issues


