[tutorial] mx_forum :: Self phpBB Modularized Module

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Last edited on Wed, 14 Jul 2004 2:00 am Exclamation

Presentation:
This forum/module/tutorial talks about one and only one of lots of possible solutions to a common problem:

How to make phpBB scripts act as portal blocks?

Please note, this is a work in progress and subject to change without prior notice. Consider it an experiment. Though, it is published for a simple reason: as here at phpMiX believe, if it worths to us, maybe it worths to you...

A big however, though:

The method presented herein is for advanced users only and provided to you on an "as is" basis, without warranties of any kind, etc. If you decide to apply this method to your system, you do so at your own risk. In no event shall phpMiX be liable for any direct or indirect damage arinsing from the use of all or part of this tutorial.

If you read, understand and believe this method worths a try on your side, be sure to make backups of your system before applying any change. Moreover, NEVER apply this method in your life site. Create an appropiate environment where you're safe in case you break anything as a result of playing with the inners of the system.

Contents:

Introduction.
Basic Module Structure.
mx_forum MODs -vs- phpBB MODs.
Hooking into phpBB Scripts.
Porting phpBB Scripts.
Porting phpBB Templates.
Particular Issues with phpBB Scripts:

:mb_1: Issues with faq.php (:mb_wk1:).
:mb_dot1: Issues with groupcp.php.
:mb_1: Issues with index.php (:mb_wk1:).
:mb_1: Issues with login.php.
:mb_0: Issues with memberlist.php.
:mb_arrowright: Issues with modcp.php (:mb_wk1:).
:mb_2: Issues with posting.php (:mb_wk1:).
:mb_0: Issues with privmsg.php (:mb_wk1:).
:mb_dot1: Issues with profile.php.
:mb_0: Issues with search.php (:mb_wk1:).
:mb_1: Issues with viewforum.php.
:mb_1: Issues with viewonline.php (:mb_wk1:).
:mb_3: Issues with viewtopic.php (:mb_wk1:).

Legend:

:mb_0:-:mb_9: Number of issues.
:mb_dot1: Not tested, yet!
:mb_arrowright: Working on it...
:mb_wk1: Templates with hardcoded references to images (see Porting phpBB Templates).

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Introduction:

Major problem when porting phpBB scripts as portal blocks is you'll end up re-applying any change made to any phpBB script to its portal block version.

All the MODs out there are thought and written for standalone phpBB installations, they have nothing to do with your portal. There are a couple of portal implementations out there... Smile

so to speak, MOD authors tend to simplify their job ...and complicate yours!

This forum will try to show you, through a series of small tutorials, how easy it is to modularize some (if not all) phpBB scripts to behave as portal blocks. So you can easilly re-port your new MOD'd phpBB scripts, again and again as portal blocks... in minutes! ...once you understand the method. Wink

Actually, we are going to choose one of several approaches to solve the problem, of course.

However, an advantage of this method is the fact that you create your own phpBB Modularized Module ( Smile

), which is going to be always up to date and perfectly MOD'd for your own needs. Mr. Green

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Basic Module Structure:

This chapter introduces the basic mx_forum module structure as well as the main procedures involved to help you figure out the overall process.
Requirements BEFORE installing the mx_forum module:
- Install phpBB following their own guides/requirements and verify it works.
- Install MX-System following their own guides/requirements and verify it works.
- Optionally, install other phpBB MODs and verify they work.
- Optionally, install other MX-Modules and verify they work.
Do not install mx_forum module until you're sure everything is up and running.
Once verified above requirements and BEFORE following any of the procedures described in this tutorial you should install the mx_forum module, following standard Portal procedure for installing modules (ie. Unzip, Upload and AdminCP->ModuleAdmin->Install).
- Basic structure for mx_forum module is:
  - modules/mx_forum
  - modules/mx_forum/mx_forum.pak
  - modules/mx_forum/includes
  - modules/mx_forum/includes/forum_hack.php
  - modules/mx_forum/includes/forum_pages.php
  - modules/mx_forum/templates
  - modules/mx_forum/templates/subSilver
- Module Attributes:
  - Module Name: phpBB Module
  - Description: Self Modularized phpBB Module
  - Path: modules/mx_forum/
  - Include this module in Admin Menu Navigation: unchecked
- Module Scripts:
  - forum_hack.php: This is the script being included by phpBB Scripts, either at phpBB folder (through common.php) or when ported as a Portal Block, at modules/mx_forum folder. Here is where the core of the mx_forum module lies. You should NOT touch the contents of this file for any reason.
  - forum_pages.php: Here is where phpBB Scripts are associated with their corresponding Portal Pages. You should modify this file for every Portal Page you create for a ported phpBB Script (see General Procedure to port a phpBB Script, below).
- The module will also contain block definitions for all phpBB scripts.
  
  Here's the Module PAK file: mx_forum.pak
Once the mx_forum module is installed, it is required to apply a small MOD (the phpBB Hook) to the file common.php located at phpBB folder, in order to catch all requests made to phpBB Scripts and transparently redirect them to the Portal when necessary (please, see chapter <a href="#Hooking_into_phpBB_Scripts">Hooking into phpBB Scripts</a> below).
Once the mx_forum module is installed and the Hook MOD correctly applied...

General procedure to port a phpBB Script as a Portal Block is:
- Copy the phpBB script to modules/mx_forum folder.
- Follow instructions on this tutorial on how to make the now mx_forum version of the phpBB script (located at modules/mx_forum folder), act and respond as a Portal Block.
- Create a new Portal Page for this ported phpBB script.
- Enable the Portal Page (by editing the modules/mx_forum/includes/forum_pages.php file).
- And Go!
If you apply a MOD to a phpBB Script that you already ported as a Portal Block, then you should re-port that script again.

General procedure to re-port a phpBB script is:
- Copy your MOD'd phpBB script to modules/mx_forum folder.
- Follow this tutorial to re-apply changes to that script, so it becomes a Portal Block again. Though, this time you'll do it faster.
Once a phpBB script has been ported as a Portal Block, it will always be rendered within a Portal Page (as far as that particular Page exists(*)) ...even if the script is invoked from the phpBB folder!!! As an example, if someone clicks on http://www.domain.com/forum/viewtopic.php?t=xx it will be automatically redirected to somewhere like http://www.domain.com/index.php?page=nn&t=xx. And everything transparent to the end-user(**). That's the magic behind the Hook installed to common.php at phpBB side.

Notes:
(*) The Page where you have placed that particular Block has been enabled by editing the modules/mx_forum/includes/forum_pages.php file.
(**) All known phpBB links will still work as entry points, then redirected to a Portal Page when necessary ...if you're worried about Bots or topic references you may already have, etc.

Additionally, once a phpBB script is ported as a Portal Block, you are allowed to use Portal features ...like permissions at Block or Page level. As an example: say you want to avoid guests accessing your memberlist... well, now you can set the correspoding Page as VIEW=REG. Or... to allow access to Private Messaging just for a particular User Group, just set the Page as VIEW=PRIVATE and PRIVATE=UserGroup, and so on...
If you wish to uninstall a ported phpBB script, all you need to do is:
- Disable the Portal Page (by editing the modules/mx_forum/includes/forum_pages.php file).
- Remove the Block from the Portal Page.
- Remove the script from the modules/mx_forum folder.
Finally, if you wish to uninstall the whole thing, the procedure is as simple as:
- Remove the Hook at phpBB side (see chapter: <a href="#Hooking_into_phpBB_Scripts">Hooking into phpBB Scripts</a> below).
- Goto AdminCP->PageAdmin and Delete the pages related to mx_forum Blocks.
- Goto AdminCP->ModuleAdmin and Delete the mx_forum Module.
- And remove the folder modules/mx_forum.

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

mx_forum MODs -vs- phpBB MODs

There are several aspects invalidating the possibility to use the standard phpBB MOD-Template system "as-is":
- The Official phpBB MOD-Template contains references to the phpBB MOD Database and to phpBB site which can't be applied here for obvious reasons.
- File related actions for phpBB MODs (COPY and OPEN) are based on paths relative to phpBB folder. However, most of the mx_forum MODs are based on paths relative to modules/mx_forum folder.
- Current set of actions available to phpBB MOD Authors make very difficult to write generic MODs as guidelines on how to port phpBB scripts as Portal Blocks. Our target here is a MOD'd phpBB installation and that means it is impossible to previously know which changes should be applied.
MOD-Template for mx_forum module looks like this:

mx_forum_mod__template_v0.1.0.txt
Actions used by mx_forum MODs:
- Actions compatible with Official phpBB MOD-Template (documented here and here):
  [COPY], [OPEN], [FIND], [REPLACE WITH], [AFTER, ADD], [BEFORE, ADD], [IN-LINE FIND], [IN-LINE REPLACE WITH], [IN-LINE AFTER, ADD], [IN-LINE BEFORE, ADD]
- mx_forum action extensions:
  - [REMOVE]: Purpose of this action is to remove the small piece of code previously found by a [FIND] or [IN-LINE FIND] actions. You can also see an example of this action in the phpBB KB Article: Uninstalling a MOD.
  - [FIND ALL OCCURRENCES OF]: This action is similar to a tipical global search and replace operation made by text editors. The text to search may be found or not. If found, it also may appear several times per line. So, to correctly execute this action, you should:
    - Place the cursor on top of the file being edited.
    - Search for the specified text.
    - Apply the next action (a [REPLACE WITH] or similar action) for all occurrences of the text found (if any).
Customization of mx_forum MODs:
- Some mx_forum MODs require some kind of manual customization to adapt the MOD to the target system.
- Basically, mx_forum MODs may contain MOD variables that should be replaced by a small piece of text BEFORE applying the MOD. mx_forum MOD variables are names delimited by < and > (ie. the "less than" and "greater than" symbols).
- Such customization will be explicitly described in its corresponding chapter of this tutorial.
Additional phpBB MOD-Template References:

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Hooking into phpBB Scripts:

Once the mx_forum module is installed, it is required to apply a small MOD (the phpBB Hook) to the file common.php located at phpBB folder, in order to catch all requests made to phpBB Scripts and transparently redirect them to the Portal when necessary.
Keep in mind if you "forget" this step, then direct links to phpBB Scripts ported as Portal Blocks coming from external places will never be rendered as a Portal Block!
To better understand why the Hook is required we need to explain what exactly does. Let's try it:
- First thing it checks is if $mx_root_path variable really exists and points where it is supposed to. If the hook itself figures out it has NOT been correctly customized (how to is explained below), it sends an error message and dies!
- Then it tries to figure out its current execution environment (faq.php, index.php, posting.php, etc.). ie. where it is being included (aka. called) by parsing the current requested URI.
- It redirects the request to a Portal Page, only if:
  - That phpBB script (the caller) also exists at modules/mx_forum folder.
  - It is safe to redirect that request to a Portal Page. So the Hook code will ignore things like posting.php?mode=smilies which generates the More Emoticons Popup, etc. where "jumping" to a Portal Page is not really useful for obvious reasons.
  - A Portal Page has been enabled for this phpBB Script (by editing the modules/mx_forum/includes/forum_pages.php file).

Before applying this MOD, it must be customized:

Set <mx_root_path> as the relative path from your phpBB folder to your Portal. For instance:

If your full paths are similar to these:
Portal -> http://www.domain.com/
Forum -> http://www.domain.com/forum/
Then you should set $mx_root_path = '../';

If your full paths are similar to these:
Portal -> http://www.domain.com/portal/
Forum -> http://www.domain.com/forum/
Then you should set $mx_root_path = '../portal/';

Note 1: The trailing slash is a must!
Note 2: If you made a mistake when setting <mx_root_path>, all you will see, when calling that phpBB script, is the following error message:

Quote:

Error in file: <phpbb_script>

Variable $mx_root_path is empty OR does not correctly point to the portal root path !!!

Please, check if you have correctly defined this variable.

Here's the Hook MOD:

mx_forum_mod_phpbb_hook_v0.1.0.txt

Note: While not begin released as an official phpBB MOD (for obvious reasons), once customized it becomes EasyMOD Compliant (EMC), so you can even use EM to apply this MOD.
If you wish to remove the Hooks, all you need to do is apply the Unhook MOD:

mx_forum_mod_phpbb_unhook_v0.1.0.txt

Note: This MOD is NOT EasyMOD Compliant (EMC), since it uses mx_forum MOD extensions (ie. the [REMOVE] action).

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Porting phpBB Scripts:

Copy the phpBB Script you wish to port as a Portal Block to the modules/mx_forum folder.
Before applying this MOD, it must be customized as follows:
- Replace the MOD variable <mx_forum_script> (used by the [OPEN] action of the MOD) by the name of the script you're going to port. For instance, if you're going to port the faq.php script, you should replace <mx_forum_script> by modules/mx_forum/faq.php and so on...
Here's the MOD:

mx_forum_mod_porting_phpbb_scripts_v0.1.0.txt
After applying the above Porting phpBB Scripts MOD, please check out any additional issue with the particular phpBB script you're porting (see <a href="#Contents">Table Of Contents</a> on top of this tutorial).
REMINDER: Once all necessary MODs are applied to the phpBB Script being ported AND a Portal Page has been created with the corresponding Block included... remember to enable the Portal Page by editing the modules/mx_forum/includes/forum_pages.php file.

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Porting phpBB Templates:

This step is required ONLY if one or more of the following actions is needed:
- To add a line-break at the bottom of the phpBB Block.
- To adjust possible hard-coded references to images to correctly point to them from the modules/mx_forum folder.
- To use the phpBB version of a particular template instead of the one that comes with the Portal at mxroot/templates/your-theme. Tipically needed if you added BBCodes, etc.
How to identify which phpBB templates may be affected?
- Open the ported phpBB Script from the modules/mx_forum folder.
- Search all occurrences of the string ".tpl" and note the full template names.
- Then, open those templates at phpbb/templates/your-theme folder AND evaluate if they need to be ported.
NOTE: Check out each Particular Issues chapter on this tutorial for a list of subSilver templates used by each phpBB script. Templates marked with the symbol (:mb_wk1:) contain hard-coded references to images. Hence, these templates should be ported.
General procedure to port a phpBB template would be as follows:
- Copy the template file from forum/templates/your-theme to modules/mx_forum/templates/your-theme.
- Apply any required changes and Upload.

As noted above, tipical changes to apply to ported phpBB templates are:

Optionally, append this line at the bottom of the template:

Code:

Replace all occurrences of "templates/your-theme/images" by "{U_PHPBB_ROOT_PATH}templates/your-theme/images".
None, if you only need to use this particular phpBB template in front of the one that comes with the Portal.

IMPORTANT NOTE:

Quote:

A problem arises with the particular way the portal loads templates.

It affects all versions of the Portal. Current version is MX 2.7.3 and it has been posted in a hidden forum (developement and CVS coordination) for discussion with the MX-Team. Link to this thread is:
http://www.mx-system.com/forum/viewtopic.php?p=23288#23288

Problem is the Portal comes with its own versions of some phpBB templates (ie. posting_body.tpl) located at mxroot/templates/your-theme. And current code (MX 2.7.3) in mxroot/includes/template.php (function make_filename) when it tries to load a template file, it first looks at the mxroot/templates/your-theme folder, so there's no chance to load the phpBB or mx_forum module versions (probably MOD'd and very different than the one that comes with the Portal) of those templates.

ATM, solution (already approved by the MX-Team) is:

mx_forum_mod_mx_template_v0.1.0.txt

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with faq.php:

Additional changes to apply to the block version of faq.php:
- A Block Parameter has been created when installing the mx_forum module to easilly allow the setting of the FAQ page to be shown. So the script should be modified to get the value of this parameter.
- Here's the MOD for all faq.php issues:
  
  mx_forum_mod_faq_v0.1.0.txt
Templates used by faq.php:

faq_body.tpl :mb_wk1:

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with groupcp.php:

Not tested, yet
Templates used by groupcp.php:

confirm_body.tpl
groupcp_info_body.tpl
groupcp_pending_info.tpl
groupcp_user_body.tpl

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with index.php:

No particular issues described, yet!
Templates used by index.php:

index_body.tpl :mb_wk1: <--- Recommended: Remove the ViewOnline and Login Blocks from this template!

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with login.php:

Additional changes to apply to the block version of login.php:
- The redirect argument parser should be fixed to remove the page=xx. Otherwise, URLs in the form of login.php?redirect=URL will not work.
- Here's the MOD for all login.php issues:
  
  mx_forum_mod_login_v0.1.0.txt
Templates used by login.php:

login_body.tpl

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with memberlist.php:

No particular issues described, yet!
Templates used by memberlist.php:

memberlist_body.tpl

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with modcp.php:

Not tested, yet
Templates used by modcp.php:

confirm_body.tpl
modcp_move.tpl
modcp_split.tpl :mb_wk1:
modcp_viewip.tpl
modcp_body.tpl

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with posting.php:

Additional changes to apply to the block version of posting.php:
- The template file posting_preview.tpl (subSilver) contains a harcoded reference to an image and should be fixed as described in Porting phpBB Templates chapter.
  
  Additional problem is posting_preview.tpl is rendered via assign_var_from_handle instead of pparse as usual. So, to populate {U_PHPBB_ROOT_PATH} for this template we have to call $mx_forum->common_template_vars() here too.
- Another change is required to fix the links within messages displayed after submiting changes (new, edit, delete).
- Here's the MOD for all posting.php issues:
  
  mx_forum_mod_posting_v0.1.0.txt
Modes of operation not displayed as a Portal Block:
- topicreview (template used: posting_topic_review.tpl)
- smilies (template used: posting_smilies.tpl)
Templates used by posting.php:

confirm_body.tpl
error_body.tpl
posting_body.tpl
posting_poll_body.tpl
posting_preview.tpl :mb_wk1:

< Back to Contents >

markus · [Administrator] Joined: 28 Jul 2003 Posts: 1124

Issues with privmsg.php:

No particular issues described, yet!
Templates used by privmsg.php:

confirm_body.tpl
error_body.tpl
posting_body.tpl
privmsgs_body.tpl :mb_wk1:
privmsgs_popup.tpl
privmsgs_preview.tpl
privmsgs_read_body.tpl

< Back to Contents >

	phpMiX.org Forum Index -> mxBB Modules -> mxBB Module: mx_forum	All times are GMT + 1 Hour Goto page 1, 2 Next
Page 1 of 2